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