From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00 shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id C65E11F8C8 for ; Fri, 17 Sep 2021 12:38:36 +0000 (UTC) From: Eric Wong To: meta@public-inbox.org Subject: [PATCH] doc: add lei-security(7) manpage Date: Fri, 17 Sep 2021 07:38:36 -0500 Message-Id: <20210917123836.15825-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: 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 +- MANIFEST | 1 + Makefile.PL | 3 +- 5 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 Documentation/lei-security.pod 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) diff --git a/MANIFEST b/MANIFEST index 9f11f2f9..218e20e9 100644 --- a/MANIFEST +++ b/MANIFEST @@ -44,6 +44,7 @@ Documentation/lei-p2q.pod Documentation/lei-q.pod Documentation/lei-rediff.pod Documentation/lei-rm.pod +Documentation/lei-security.pod Documentation/lei-store-format.pod Documentation/lei-tag.pod Documentation/lei-up.pod diff --git a/Makefile.PL b/Makefile.PL index 1e935012..f56445ae 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -54,7 +54,8 @@ $v->{-m5} = [ qw(public-inbox-config public-inbox-v1-format public-inbox-v2-format public-inbox-extindex-format lei-mail-formats lei-store-format ) ]; -$v->{-m7} = [ qw(lei-overview public-inbox-overview public-inbox-tuning +$v->{-m7} = [ qw(lei-overview lei-security + public-inbox-overview public-inbox-tuning public-inbox-glossary) ]; $v->{-m8} = [ qw(public-inbox-daemon) ]; my @sections = (1, 5, 7, 8);