Documentation/lei-security.pod

   1 =head1 NAME
   2
   3 lei - security information
   4
   5 =head1 SYNOPSIS
   6
   7 L<lei(1)> is intended for use with both publicly-archived
   8 and "private" mail in personal mailboxes.  This document is
   9 intended to give an overview of security implications and
  10 lower^Wmanage user expectations.
  11
  12 =head1 DESCRIPTION
  13
  14 lei expects to be run as a regular user on a Unix-like system.
  15 It expects a case-sensitive filesystem with standard Unix
  16 permissions support.
  17
  18 It does not use POSIX ACLs, extended attributes, nor any other
  19 security-related functions which require non-standard Perl modules.
  20
  21 =head1 INTERNAL FILES
  22
  23 lei runs with a umask of 077 to prevent other users on the
  24 system from accessing each other's mail.
  25
  26 The git storage and Xapian databases are located at
  27 C<$XDG_DATA_HOME/lei/store> (typically C<~/.local/share/lei/store>).
  28 Any personal mail imported will reside here, so this should
  29 be on an encrypted filesystem or block device.
  30
  31 C<$XDG_RUNTIME_DIR/lei> (typically C</run/user/$UID/lei> or
  32 C</tmp/lei-$UID>) contain the socket used to access the lei
  33 daemon.  It must only be accessible to the owner (mode 0700).
  34
  35 C<$XDG_CACHE_HOME/lei> (typically C<~/.cache/lei>) will
  36 contain IMAP and Maildir folder names which could leak sensitive
  37 information as well as git repository names.
  38
  39 C<$XDG_DATA_HOME/lei/saved-searches> (typically
  40 C<~/.local/share/lei/saved-searches>) will contain aforementioned
  41 folder names as well as (removable) search history.
  42
  43 The configuration for lei resides at C<$XDG_CONFIG_HOME/lei/config>
  44 (typically C<~/.config/lei/config>).  It may contain sensitive pathnames
  45 and hostnames in the config if a user chooses to configure them.
  46
  47 lei itself will never write credentials to the
  48 filesystem.  However, L<git-credential(1)> may be
  49 configured to do so.  lei will only read C<~/.netrc> if
  50 C<--netrc> is used (and it will never write to C<~/.netrc>).
  51
  52 C<$XDG_CACHE_HOME/public-inbox> (typically C<~/.cache/public-inbox>)
  53 can contain data and L<Inline::C>-built modules which can be
  54 shared with public-facing L<public-inbox-daemon(8)> instances;
  55 so no private data should be in "public-inbox" paths.
  56
  57 =head1 EXTERNAL FILES
  58
  59 Locations set by L<lei-add-external(1)> can be shared with
  60 public-facing L<public-inbox-daemon(8)> processes.  They may
  61 reside on shared storage and may be made world-readable to
  62 other users on the local system.
  63
  64 =head1 NETWORK ACCESS
  65
  66 lei currently uses the L<curl(1)> and L<git(1)> executables in
  67 C<$PATH> for HTTP and HTTPS network access.  Interactive
  68 authentication for HTTP and HTTPS is not-yet-supported since all
  69 currently supported HTTP/HTTPS sources are L<PublicInbox::WWW>
  70 instances.
  71
  72 The L<Mail::IMAPClient> library is used for IMAP and IMAPS.
  73 L<Net::NNTP> (standard library) is used for NNTP and NNTPS.
  74
  75 L<Mail::IMAPClient> and L<Net::NNTP> will use L<IO::Socket::SSL>
  76 for TLS if available.  In turn, L<IO::Socket::SSL> uses the
  77 widely-installed OpenSSL library.
  78
  79 STARTTLS will be attempted if advertised by the server
  80 unless IMAPS or NNTPS are used.  C<-c imap.starttls=0>
  81 and C<-c nntp.startls=0> may be used to disable STARTTLS.
  82
  83 L<IO::Socket::Socks> will be used if C<-c imap.proxy> or
  84 C<-c nntp.proxy> point to a C<socks5h://$HOST:$PORT>
  85 address (common for Tor).
  86
  87 The C<--netrc> switch may be passed to curl and used for
  88 NNTP/IMAP access (via L<Net::Netrc>).
  89
  90 =head1 CREDENTIAL DATA
  91
  92 lei uses L<git-credential(1)> to prompt users for IMAP and NNTP
  93 usernames and passwords.  These passwords are not encrypted in
  94 memory and get transferred across processes via anonymous UNIX
  95 sockets and pipes.  They may be exposed via syscall tracing
  96 tools (e.g. L<strace(1)>).
  97
  98 While credentials are not written to the filesystem by default,
  99 it is possible for them to end up on disk if processes are
 100 swapped out.  Use of an encrypted swap partition is recommended.
 101
 102 =head1 AUTHENTICATION METHODS
 103
 104 LOGIN (username + password) is known to work over IMAP(S),
 105 as does AUTH=ANONYMOUS (which is used by L<public-inbox-imapd(1)>
 106 as part of our test suite).  AUTHINFO may work for NNTP, but
 107 is untested.  Testers will be needed for other authentication
 108 methods.
 109
 110 =head1 DENIAL-OF-SERVICE VECTORS
 111
 112 lei uses the same MIME parsing library as L<public-inbox-mda(1)>
 113 with limits header sizes, parts, nesting and boundary limits
 114 similar to those found in SpamAssassin and postfix.
 115
 116 Email address parsing is handled by L<Email::Address::XS> if
 117 available, but may fall back to regular expressions which favor
 118 speed and predictable execution times over correctness.
 119
 120 =head1 ENCRYPTED EMAILS
 121
 122 Not yet supported, but it should eventually be possible to
 123 configure decryption and indexing of encrypted messages and
 124 attachments.  When supported, decrypted terms will be stored
 125 in Xapian DBs under C<$XDG_DATA_HOME/lei/store>.
 126
 127 =head1 CONTACT
 128
 129 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 130
 131 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 132 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 133
 134 =head1 COPYRIGHT
 135
 136 Copyright all contributors L<mailto:meta@public-inbox.org>
 137
 138 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 139
 140 =head1 SEE ALSO
 141
 142 L<lei-overview(7)>, L<lei(1)>