From 6d6f69c99ef79bddb9e6ff14c9cda8ddaf012509 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 17 Sep 2021 07:38:36 -0500 Subject: doc: add lei-security(7) manpage It seems like a good idea to have a manpage where somebody can quickly look up and address their concerns as to what to put on encrypted device/filesystem. And I probably would've designed lei around make(1) for parallelization if I didn't have to keep credentials off the FS :P --- Documentation/lei-add-external.pod | 4 +- Documentation/lei-security.pod | 134 +++++++++++++++++++++++++++++++++++++ Documentation/txt2pre | 8 ++- 3 files changed, 143 insertions(+), 3 deletions(-) create mode 100644 Documentation/lei-security.pod (limited to 'Documentation') diff --git a/Documentation/lei-add-external.pod b/Documentation/lei-add-external.pod index 71229865..9c8bde0f 100644 --- a/Documentation/lei-add-external.pod +++ b/Documentation/lei-add-external.pod @@ -10,8 +10,8 @@ lei add-external [OPTIONS] LOCATION Configure lei to search against an external (an inbox or external index). When C is an existing local path, it should point -to a directory that is a C.inboxdir> or -C.topdir> value in ~/.public-inbox/config. +to a directory that is a C or +C value in ~/.public-inbox/config. =head1 OPTIONS diff --git a/Documentation/lei-security.pod b/Documentation/lei-security.pod new file mode 100644 index 00000000..4b712c2d --- /dev/null +++ b/Documentation/lei-security.pod @@ -0,0 +1,134 @@ +=head1 NAME + +lei - security information + +=head1 SYNOPSIS + +L is intended for use with both publicly-archived +and "private" mail in personal mailboxes. This document is +intended to give an overview of security implications and +lower^Wmanage user expectations. + +=head1 DESCRIPTION + +lei expects to be run as a regular user on a Unix-like system. +It expects a case-sensitive filesystem with standard Unix +permissions support. + +It does not use POSIX ACLs, extended attributes, nor any other +security-related functions which require non-standard Perl modules. + +=head1 INTERNAL FILES + +lei runs with a umask of 077 to prevent other users on the +system from accessing each other's mail. + +The git storage and Xapian databases are located at +C<$XDG_DATA_HOME/lei/store> (typically C<~/.local/share/lei/store>). +Any personal mail imported will reside here, so this should +be on an encrypted filesystem or block device. + +C<$XDG_RUNTIME_DIR/lei> (typically C or +C) contain the socket used to access the lei +daemon. It must only be accessible to the owner (mode 0700). + +C<$XDG_CACHE_HOME/lei> (typically C<~/.cache/lei>) will +contain IMAP and Maildir folder names which could leak sensitive +information as well as git repository names. + +C<$XDG_DATA_HOME/lei/saved-searches> (typically +C<~/.local/share/lei/saved-searches>) will contain aforementioned +folder names as well as (removable) search history. + +The configuration for lei resides at C<$XDG_CONFIG_HOME/lei/config> +(typically C<~/.config/lei/config>). It may contain sensitive pathnames +and hostnames in the config if a user chooses to configure them. + +lei itself will never write credentials to the +filesystem. However, L may be +configured to do so. lei will only read C<~/.netrc> if +C<--netrc> is used (and it will never write to C<~/.netrc>). + +C<$XDG_CACHE_HOME/public-inbox> (typically C<~/.cache/public-inbox>) +can contain data and L-built modules which can be +shared with public-facing L instances; +so no private data should be in "public-inbox" paths. + +=head1 EXTERNAL FILES + +Locations set by L can be shared with +public-facing L processes. They may +reside on shared storage and may be made world-readable to +other users on the local system. + +=head1 NETWORK ACCESS + +lei currently uses the L and L executables in +C<$PATH> for HTTP and HTTPS network access. Interactive +authentication for HTTP and HTTPS is not-yet-supported since all +currently supported HTTP/HTTPS sources are L +instances. + +The L library is used for IMAP and IMAPS. +L (standard library) is used for NNTP and NNTPS. + +L and L will use L +for TLS if available. In turn, L uses the +widely-installed OpenSSL library. + +STARTTLS will be attempted if advertised by the server +unless IMAPS or NNTPS are used. C<-c imap.starttls=0> +and C<-c nntp.startls=0> may be used to disable STARTTLS. + +L will be used if C<-c imap.proxy> or +C<-c nntp.proxy> point to a C +address (common for Tor). + +The C<--netrc> switch may be passed to curl and used for +NNTP/IMAP access (via L). + +=head1 CREDENTIAL DATA + +lei uses L to prompt users for IMAP and NNTP +usernames and passwords. These passwords are not encrypted in +memory and get transferred across processes via anonymous UNIX +sockets and pipes. They may be exposed via syscall tracing +tools (e.g. L). + +While credentials are not written to the filesystem by default, +it is possible for them to end up on disk if processes are +swapped out. Use of an encrypted swap partition is recommended. + +=head1 DENIAL-OF-SERVICE VECTORS + +lei uses the same MIME parsing library as L +with limits header sizes, parts, nesting and boundary limits +similar to those found in SpamAssassin and postfix. + +Email address parsing is handled by L if +available, but may fall back to regular expressions which favor +speed and predictable execution times over correctness. + +=head1 ENCRYPTED EMAILS + +Not yet supported, but it should eventually be possible to +configure decryption and indexing of encrypted messages and +attachments. When supported, decrypted terms will be stored +in Xapian DBs under C<$XDG_DATA_HOME/lei/store>. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +The mail archives are hosted at L and +L + +=head1 COPYRIGHT + +Copyright all contributors L + +License: AGPL-3.0+ L + +=head1 SEE ALSO + +L, L diff --git a/Documentation/txt2pre b/Documentation/txt2pre index 6367374d..7bc31d23 100755 --- a/Documentation/txt2pre +++ b/Documentation/txt2pre @@ -21,6 +21,7 @@ for (qw[lei(1) lei-forget-external(1) lei-forget-search(1) lei-import(1) + lei-index(1) lei-init(1) lei-lcat(1) lei-ls-external(1) @@ -31,14 +32,19 @@ for (qw[lei(1) lei-p2q(1) lei-q(1) lei-rediff(1) + lei-rm(1) + lei-store-format(5) + lei-security(7) lei-tag(1) lei-up(1) public-inbox.cgi(1) - public-inbox-compact(1) + public-inbox-clone(1) + public-inbox-config(5) public-inbox-config(5) public-inbox-convert(1) public-inbox-daemon(8) public-inbox-edit(1) + public-inbox-fetch(1) public-inbox-glossary(7) public-inbox-httpd(1) public-inbox-imapd(1) -- cgit v1.2.3-24-ge0c7