From 9a4b1d202c222f1ebcb9dad414c1d08cf490310a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodolphe=20Br=C3=A9ard?= Date: Sun, 16 Apr 2023 18:37:42 +0200 Subject: [PATCH] Add a man page --- README.md | 2 +- man/en/filter-dkimout.8 | 150 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+), 1 deletion(-) create mode 100644 man/en/filter-dkimout.8 diff --git a/README.md b/README.md index e4c3c2b..6c37020 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ Matthew Green wrote an excellent article on this subject: [Ok Google: please pub ### Where is the documentation? -A man page will be available by the time this filter is ready to use. +The complete documentation can be found in the `filter-dkimout (8)` man page. ### One of my keys has been compromised, how do I revoke it? diff --git a/man/en/filter-dkimout.8 b/man/en/filter-dkimout.8 new file mode 100644 index 0000000..b6efe5c --- /dev/null +++ b/man/en/filter-dkimout.8 @@ -0,0 +1,150 @@ +.\" Copyright (c) 2019-2020 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 Apr 16, 2023 +.Dt FILTER-DKIMOUT 8 +.Os +.Sh NAME +.Nm filter-dkimout +.Nd DKIM filter for OpenSMTPD +.Sh SYNOPSIS +.Nm +.Op Fl a|--algorithm Ar STRING +.Op Fl b|--key-data-base Ar FILE +.Op Fl c|--canonicalization Ar STRING +.Op Fl d|--domain Ar STRING +.Op Fl D|--domain-file Ar FILE +.Op Fl f|--revocation-list Ar FILE +.Op Fl h|--header Ar STRING +.Op Fl o|--header-optional Ar STRING +.Op Fl p|--cryptoperiod Ar UINT +.Op Fl r|--revocation Ar UINT +.Op Fl u|--dns-update-cmd Ar STRING +.Op Fl v|--verbose +.Op Fl V|--version +.Op Fl x|--expiration Ar UINT +.Sh DESCRIPTION +.Nm +is an OpenSMTPD filter for OpenSMTPD that signs outgoing emails using DKIM. +It provides automatic key generation and rotation. +.Pp +The options are as follows: +.Bl -tag +.It Fl a, -algorithm Ar STRING +The signing algorithm. Possible values are: +.Pp +.Bl -dash -compact +.It +ed25519-sha256 +.It +rsa2048-sha256 +.Aq default +.It +rsa3072-sha256 +.It +rsa4096-sha256 +.El +.It Fl b, -key-data-base Ar FILE +Path to an SQLite 3 database where keys are stored. +Will be created if does not exists. +.It Fl c, -canonicalization Ar STRING +The canonicalization algorithm used to generate the signature. +Must be composed of two methods separated by a slash character. +The first method will be used for the headers and the second one for the body. +Available methods are: +.Pp +.Bl -dash -compact +.It +simple +.It +relaxed +.El +.Pp +Default is +.Qo +relaxed/relaxed +.Qc . +.It Fl d, -domain Ar STRING +A domain name for which it is possible to sign for. +Multiple +.Fl d +options are additive. +.It Fl D, -domain-file Ar FILE +Path to a file witch contains a domain name on each line. +.It Fl f, -revocation-list Ar FILE +Path to the revocation list file. +Will be created if does not exists. +This file is opened in append mode, which means previous content will not be deleted. +.It Fl h, -header Ar STRING +Header that will always be included in the signature, even if not present. +It is possible to specify multiple headers separated by a colon. +Multiple +.Fl h +options are additive. +Set to an empty string to deactivate. +.Pp +Default is +.Qo +from:reply-to:subject:date:to:cc +.Qc . +.It Fl o, -header-optional Ar STRING +Header that will be included in the signature only if present. +It is possible to specify multiple headers separated by a colon. +Multiple +.Fl o +options are additive. +Set to an empty string to deactivate. +.Pp +Default is +.Qo +resent-date:resent-from:resent-to:resent-cc:in-reply-to:references:list-id:list-help:list-unsubscribe:list-subscribe:list-post:list-owner:list-archive +.Qc . +.It Fl p, -cryptoperiod Ar UINT +The cryptoperiod, in seconds. +Default is 15552000 +.Aq 180 days . +.It Fl r, -revocation Ar UINT +Number of seconds between the end of the cryptoperiod and the revocation. +Default is 1728000 +.Aq 20 days . +.It Fl u, -dns-update-cmd Ar STRING +Command that will be executed to update DNS entries. +.It Fl v, -verbose +Verbose mode. +Multiple +.Fl v +options increase the verbosity. +The maximum is 2. +.It Fl V, -version +Display the version number and exit. +.It Fl x, -expiration Ar UINT +Signature expiration, in seconds. +Default is 1296000 +.Aq 15 days . +Set to 0 to deactivate. +.El +.Sh SEE ALSO +.Xr smtpd-filters 7 +.Sh STANDARDS +.Bl -hyphen +.It +.Rs +.%A D. Crocker +.%D September 2011 +.%R RFC 6376 +.%T DomainKeys Identified Mail (DKIM) Signatures +.Re +.It +.Rs +.%A J. Levine +.%D September 2018 +.%R RFC 8463 +.%T A New Cryptographic Signature Method for DomainKeys Identified Mail (DKIM) +.Re +.El +.Sh AUTHORS +.An Rodolphe Bréard +.Aq rodolphe@breard.tf