Pepsi Manual¶
Pepsi is a mail server for individuals and for small and medium-sized organisations that want to run their own e-mail instead of handing it to a large provider. It receives your mail from the Internet and sends your mail out, keeping it secure both inside your organisation and on its way to anyone else.
Secure e-mail without the hassle. Pepsi signs, encrypts and decrypts mail with the two established standards, OpenPGP and S/MIME, and finds and manages the keys that this requires. For every message, you can see plainly who really sent it. Your users do not need any special software, and a correspondent who has no encryption of their own can still read your protected mail on a secure web page.
Less spam. Like other mail servers, Pepsi checks where each message really comes from. It can also ask an unknown sender to confirm that they are human, or to attach a tiny payment with GNU Taler, before their mail reaches you. For your correspondents this costs almost nothing; for someone who sends millions of messages, it adds up to real money.
Easy to set up. You answer a few questions, and the setup program does the
rest: it generates all the keys, obtains the certificates and tells you exactly
which records to publish in the DNS. Afterwards, it checks that you published
them correctly. These records matter, because other providers use them to
decide whether to accept your mail. Debian and Ubuntu packages are available
from deb.taler.net (Installing Pepsi).
Fits into your system. Pepsi delivers incoming mail to your users’ mailboxes, to a separate delivery program, or to another mail server. It does not let mail programs read mailboxes over IMAP; for that, most sites add Dovecot.
Built for security. Pepsi is written in a memory-safe language and is split into small programs, each of which has only the rights that it needs. The Threat model and Security model chapters explain in detail what Pepsi protects against and how.
Free Software. Pepsi is free software under the GNU Affero General Public
License: you may run it for any purpose, study how it works and change it, and
share it with others, with or without your changes. Nobody can take these
freedoms away from you, and nobody can lock you in. The source code is public at
git://git.taler.net/pepsi.git.
Start with Introduction, which explains what Pepsi is, lists its
features, compares it with the established mail servers and explains how the
rest of this manual is organised. Getting started on a cheap VPS walks you from the DNS
setup to the first e-mail that you receive, and The Wizard shows the
pipelines that pepsi-setup --wizard builds and what each of its questions
decides.
Contents
- 1. Introduction
- 2. Design principles
- 2.1. 1. Free Software, under the operator’s control
- 2.2. 2. Do no harm to others
- 2.3. 3. Keep faith with users: no security surprises
- 2.4. 4. Collect and keep the minimum
- 2.5. 5. Work with what people already run
- 2.6. 6. Safe by default, easy to set up and use
- 2.7. 7. Operable and evolvable
- 2.8. 8. Simple enough to verify
- 2.9. 9. Reasonably efficient
- 3. Getting started on a cheap VPS
- 3.1. What we will build
- 3.2. Prerequisites
- 3.3. Step 1 — Delegate DNS and place the base records
- 3.4. Step 2 — Install Pepsi
- 3.5. Step 3 — Prepare the system
- 3.6. Step 4 — Write the configuration
- 3.7. Step 5 — Provision the schema, keys and certificate
- 3.8. Step 6 — Publish the remaining records and verify
- 3.9. Step 7 — Start the services
- 3.10. Step 8 — Send the first e-mail
- 3.11. Step 9 — Open the console (optional)
- 3.12. Sending mail too: add a submission port
- 3.13. Troubleshooting
- 3.14. Next steps
- 4. Installation
- 4.1. Prerequisites
- 4.2. Installing Pepsi
- 4.3. Verifying a download
- 4.4. Reproducible builds
- 4.5. Migrating from an existing mail server
- 4.6. Provisioning the database, keys and DNS
- 4.7. Setting up in a browser
- 4.8. Running the services
- 4.9. Upgrading
- 4.10. Users, groups and privileges
- 4.11. Migrating from GNU Mailman
- 5. Debian packages
- 6. The Wizard
- 7. Configuration
- 8. Operating Pepsi
- 9. Using Pepsi: a guide for users
- 9.1. What the mail server does for you
- 9.2. Setting up your mail program
- 9.3. Words in the subject of mail you receive
- 9.4. Words you can put in the subject of mail you send
- 9.5. Mail program extensions
- 9.6. Changing your settings by e-mail
- 9.7. A certificate from the organisation
- 9.8. When the first message from someone new arrives late
- 9.9. Mail from strangers, and your GNU Taler wallet
- 9.10. Mailing lists
- 9.11. Your own web pages
- 10. Troubleshooting
- 11. Supported Features
- 11.1. Inbound SMTP reception
- 11.2. Trace headers
- 11.3. Client authentication
- 11.4. Message submission
- 11.5. Boundary authentication
- 11.6. Authenticated Received Chain (ARC)
- 11.7. Sender Rewriting Scheme (SRS)
- 11.8. End-to-end encryption and signing
- 11.9. Server-side decryption and verification
- 11.10. Key management, discovery and publication
- 11.11. The secure-link fallback
- 11.12. Outbound DKIM signing
- 11.13. Delivery Status Notifications
- 11.14. Recycled addresses
- 11.15. Require TLS
- 11.16. Internationalised and 8-bit content
- 11.17. Outbound relay
- 11.18. Local delivery
- 11.19. Mailing lists and archives
- 11.20. Unsolicited mail
- 11.21. Operational features
- 11.22. Feature stability
- 12. SMTP Protocol Extensions
- 13. Key management
- 13.1. Three kinds of material
- 13.2. Custody: how a private key is stored
- 13.3. The privilege boundary
- 13.4. What custody protects against
- 13.5. Signing and encryption are separate
- 13.6. Creating identities
- 13.7. Certificates from a commercial CA: the managed PKI
- 13.8. pEp-style automatic keys
- 13.9. Two keys per user
- 13.10. Publishing our users’ keys
- 13.11. Backing up and rotating the key-encryption key
- 13.12. The forward-secrecy profile
- 13.13. Peer keys
- 13.14. Finding a correspondent’s key
- 13.15. A CLI walk-through
- 13.16. Configuration summary
- 13.17. See also
- 14. The secure-link fallback portal
- 15. Client interoperability
- 16. Threat model
- 16.1. How to read this chapter
- 16.2. Assets
- 16.3. Principals and how far each is trusted
- 16.4. Trust boundaries
- 16.5. Adversaries
- 16.6. End-to-end encryption: two custody modes
- 16.7. What a security indicator means
- 16.8. Forged notices
- 16.9. Per-address settings are a trust boundary
- 16.10. The network adversary
- 16.11. Availability
- 16.12. What Pepsi does not protect
- 16.13. The guarantees at a glance
- 16.14. See also
- 17. Security model
- 17.1. What Pepsi assumes
- 17.2. The privilege split
- 17.3. The private-key custody boundary
- 17.4. Certificates from a commercial CA
- 17.5. The DKIM signing daemon
- 17.6. A second factor for key management
- 17.7. Security keys (WebAuthn)
- 17.8. Signing in to the console by e-mail
- 17.9. An attacker who has the database
- 17.10. An attacker who has the configuration file
- 17.11. A process of the same account
- 17.12. Addresses are compared in one form
- 17.13. A login that changes owner
- 17.14. An attacker who compromises a stage worker
- 17.15. Specific defences
- 17.16. What Pepsi does not defend against
- 17.17. Reporting a vulnerability
- 17.18. See also
- 18. Dependencies
- 19. Microsoft Exchange as a gateway
- 19.1. Topologies
- 19.2. The routing decision
- 19.3. Exchange Online: the tenant endpoint
- 19.4. Address family selection
- 19.5. Loop prevention
- 19.6. Exchange connector configuration
- 19.7. The Outlook add-in
- 19.8. The
X-Pepsi-*header contract - 19.9. Identity auto-provisioning
- 19.10. Key distribution
- 19.11. Troubleshooting
- 19.12. What Pepsi does not do
- 20. Mail client extensions
- 21. Mailing lists
- 21.1. This subsystem is a reimplementation of GNU Mailman 3
- 21.2. What a list is
- 21.3. How the subsystem is put together
- 21.4. Getting started
- 21.5. Styles
- 21.6. Per-list settings
- 21.7. Configuration
- 21.8. Substring search is optional
- 21.9. Two account systems
- 21.10. Bounce processing
- 21.11. When content filtering leaves nothing
- 21.12. What a sender can make a list do
- 21.13. Known limitations
- 21.14. Digests
- 21.15. Declared differences from GNU Mailman 3
- 22. Archives
- 23. The GNU Mailman 3 REST API
- 23.1. There are two APIs in this tree
- 23.2. Where it is served
- 23.3. Authentication
- 23.4. The two versions differ in four ways
- 23.5. Template URIs
- 23.6. Three honest analogues
- 23.7. One resource of Pepsi’s own
- 23.8. What needs configuring beyond the credential
- 23.9. A worked example
- 23.10. What is not implemented
- 23.11. Testing it
- 24. The administrative API
- 24.1. Where it is served
- 24.2. Authentication
- 24.3. Authorisation: scopes
- 24.4. Conventions
- 24.5. Pagination
- 24.6. Endpoints
- 24.7. What this server cannot do
- 24.8. Correspondent keys
- 24.9. Trust anchors
- 24.10. Managed PKI
- 24.11. Greylisting
- 24.12. Quarantine
- 24.13. DKIM keys
- 24.14. Secure links
- 24.15. DNS records
- 24.16. Online setup
- 24.17. Hardening
- 24.18. The audit log
- 24.19. The mail log (off by default)
- 24.20. Bootstrapping
- 24.21. The browser console
- 25. The administration console
- 25.1. Three listener flags, and two of them have opposite advice
- 25.2. Reaching it safely
- 25.3. Signing in
- 25.4. What the console can and cannot do
- 25.5. The pages
- 25.6. Two templating engines, two purposes
- 25.7. No scripting, no remote assets
- 25.8. Accessibility
- 25.9. The public mailing-list pages
- 25.10. Two account systems, and neither grants the other anything
- 25.11. The member’s pages
- 25.12. The owner and moderator console
- 25.13. The interfaces’ languages
- 26. Architecture
- 27. The message state
- 28. Extending the Pipeline
- 28.1. When a stage is the right tool
- 28.2. Anatomy of a stage crate
- 28.3. The body
- 28.4. Terminal helpers (choose exactly one)
- 28.5. Errors
- 28.6. Rules the stages live by
- 28.7. Wiring it in
- 28.8. Testing a stage
- 28.9. Adding support for migrating from another MTA
- 28.10. Integrating an external credential-refresh service
- 28.11. Database schema lifecycle
- 28.12. Making a release
- 28.13. Keeping the feature-stability table current
- 29. Test Suite
- 30. Benchmark Suite
- 31. Performance
- 32. pepsi-ingress
- 33. pepsi-dispatch
- 34. pepsi-httpd
- 35. pepsi-stage-arc
- 36. pepsi-stage-srs
- 37. pepsi-stage-encrypt
- 38. pepsi-stage-decrypt
- 39. pepsi-stage-dkim-sign
- 40. pepsi-stage-bounce
- 41. pepsi-stage-aliases
- 42. pepsi-stage-relay-to-internet
- 43. pepsi-stage-relay-to-smarthost
- 44. pepsi-stage-relay-to-maildir
- 45. pepsi-stage-dot-forward
- 46. pepsi-stage-relay-to-lmtp
- 47. pepsi-stage-discard
- 48. pepsi-stage-anti-spam
- 49. pepsi-stage-auto-pay
- 50. pepsi-stage-check-whitelist
- 51. pepsi-stage-auto-whitelist
- 52. pepsi-stage-autocrypt-learn
- 53. pepsi-stage-reencrypt
- 54. pepsi-stage-detect-language
- 55. pepsi-detect-language
- 56. pepsi-stage-block-language
- 57. pepsi-stage-vacation
- 58. pepsi-stage-secretary
- 59. pepsi-stage-edit-settings
- 60. pepsi-stage-if
- 61. pepsi-stage-milter
- 62. pepsi-stage-quarantine
- 63. pepsi-stage-route
- 64. pepsi-stage-vks-confirm
- 65. pepsi-stage-dmarc-report
- 66. pepsi-stage-defang
- 67. pepsi-stage-secure-link
- 68. pepsi-setup
- 69. pepsi-queue
- 70. pepsi-status
- 71. pepsi-reputation
- 72. pepsi-greylist
- 73. pepsi-dkim
- 74. pepsi-sendmail
- 75. pepsi-whitelist
- 76. pepsi-keys
- 77. pepsi-keydisc
- 78. pepsi-settings
- 79. pepsi-list
- 80. pepsi-archive
- 81. pepsi-stage-list
- 82. pepsi-stage-list-post
- 83. pepsi-stage-list-deliver
- 84. pepsi-stage-list-command
- 85. pepsi-stage-list-bounce
- 86. pepsi-tlsrpt
- 87. pepsi-secure-link
- 88. pepsi-failure-bouncer
- 89. pepsi-quota
- 90. pepsi-helper-token-refresh
- 91. pepsi-telemetry
- 92. pepsi-telemetry-client
- 93. pepsi-config
- 94. Feature stability
- 95. Manual pages
- 96. Vulnerabilities in E-mail implementations
- 96.1. How this chapter is organised
- 96.2. Summary
- 96.3. Transport and infrastructure
- 96.4. Sender authenticity and mail flow
- 96.5. Message format and rendering
- 96.6. Mail software
- 96.7. End-to-end encryption and keys
- 96.8. Cryptographic primitives and libraries
- 96.9. Accounts and people
- 96.10. Who must act on what remains
- 97. RFC Index
- 98. Bibliography
Indices