diff --git a/man/en/filter-sake.8 b/man/en/filter-sake.8 new file mode 100644 index 0000000..88cd2f9 --- /dev/null +++ b/man/en/filter-sake.8 @@ -0,0 +1,97 @@ +.\" Copyright (c) 2023 Rodolphe Bréard +.\" +.\" Copying and distribution of this file, with or without modification, +.\" are permitted in any medium without royalty provided the copyright +.\" notice and this notice are preserved. This file is offered as-is, +.\" without any warranty. +.Dd Aug 25, 2023 +.Dt FILTER-SAKE 8 +.Os +.Sh NAME +.Nm filter-sake +.Nd Sub-address key filter for OpenSMTPD +.Sh SYNOPSIS +.Nm +.Op Fl a|--address Ar STRING +.Op Fl A|--address-file Ar FILE +.Op Fl s|--separator Ar CHAR +.Sh DESCRIPTION +.Nm +is a filter for OpenSMTPD that enforce the presence of a validation code in sub-addresses. +.Pp +The options are as follows: +.Bl -tag +.It Fl a, -address Ar STRING +An address where the filter will enforce the presence of a valid verification code. +See the +.Sx ADDRESS FORMAT +section to learn about the format that is expected. +This option may be specified multiple times. +.It Fl A, -address-file Ar FILE +File where each line is an address as specified in +.Dq --address . +Empty lines and lines starting with the +.Sq # +character are ignored. +.It Fl s, -separator Ar CHAR +The sub-address delimiter character. +Default is +.Sq + . +This value must match the character defined in +.Pa smtpd.conf +using +.Dq smtp sub-addr-delim . +.El +.Sh ADDRESS FORMAT +An address must be composed of the following elements: +.Bl -dash -compact +.It +the local part +.It +(optional) an +.Sq @ +followed by a domain name +.It +the +.So +: +.Sc +character +.It +the private key in base64 (with padding) +.El +.Pp +Specifying a domain name configures the filter to match addresses on both the local part and the specified domain name. +If no domain name is specified, the match will be on the local part only, and therefore all domain names will be accepted. +.Sh PRIVATE KEY GENERATION +Privates keys must have a length of either 128 bits (16 bytes) or 256 bits (32 bytes). +Unless you have some very specific needs, you should choose a 128 bits key. +.Pp +To generate a key, it is recommended to use +.Dq openssl rand -base64 16 . +.Sh EXAMPLE OPENSMTPD CONFIGURATION +The following example shows how you can integrate filter-sake in your +.Pa smtpd.conf : +.Bd -literal -offset indent +# Sub-addresses +smtp sub-addr-delim "+" +filter "sake" proc-exec "filter-sake -s '+' -a 'a@example.org:11voiefK5PgCX5F1TTcuoQ==' -a 'b:3pUdigGQNXYBeKJdYDdERQ=='" + +# Tables +table domains { "example.org", "example.com" } +table vusers { "test" = "1000:100:/var/vmail/test", "b" = "1000:100:/var/vmail/b" } +table aliases { "a" = "test" } + +# Listening +listen on 127.0.0.1 hostname localhost filter "sake" +listen on ::1 hostname localhost filter "sake" + +# Delivering +action "deliver" maildir userbase alias +match from any for domain action "deliver" +.Ed +.Sh SEE ALSO +.Xr smtpd.conf 5 +.Sh AUTHORS +.An Rodolphe Bréard +.Aq v.man.fcb3mbje@breard.tf