$OpenBSD: README,v 1.1 2013/03/08 06:42:09 ajacoutot Exp $
+-----------------------------------------------------------------------
| Running ${FULLPKGNAME} on OpenBSD
+-----------------------------------------------------------------------
(1) Choose a selector name. Current convention is to use a code for the
current month and year, or just the year. However, you are free to
choose any name you wish, especially if you have a selector assignment
scheme in mind.
(2) Create a public/private keypair for signing:
(a) Run the script "dkim-genkey".
This will generate a private key in PEM format and a TXT record
appropriate for insertion into your DNS zone file. Insert the contents
of the TXT record file into your DNS zone file, increment the
serial number, and reload your DNS server so that the new record
is published. This is by far the easiest approach.
(b) If for some reason you cannot use the "dkim-genkey" script, manually
generate a public and private key. The steps below are exactly what
is performed by the dkim-genkey script.
(i) Run this command:
% openssl genrsa -out rsa.private 1024
This generates a private key and writes it to the file "rsa.private".
The generated key is in PEM format and is a 1024-bit key, the
minimum required by the DKIM specification.
(ii) Run this command:
% openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM
This reads the private key generated in the previous step and
extracts from it the matching public key. This is written to the
file "rsa.public".
(iii) Add a TXT DNS record containing the base64 encoding of your public
key, which is everything between the BEGIN and END lines in the
rsa.public file generated above, with spaces and newlines removed.
It should be in this form:
"g=*; k=rsa; t=y; p=MFwwDQYJ...AwEAAQ=="
...using, of course, your own public key's base64 data. The name of
the TXT record should be SELECTOR._domainkey.example.com (where
"SELECTOR" is the name you chose and "example.com" is your domain
name). Reload your nameserver so that the record gets published.
If you are running BIND 9 the command is "rndc reload"; for other
nameservers, consult your vendor documentation.
For a translation of the parameter and value pairs shown here, see
the DKIM specification (RFC4871) section 3.6. The specification
is available in a file in the source code package called
"rfc4871.txt". Basically this key record just announces an RSA
public key and also declares that your site is using this key in
test mode so nobody should take any real action based on success
or failure of the use of this key to verify a message.
(3) Store the private key in a safe place. We generally use a path like
/var/db/dkim/SELECTOR.key.pem (where "SELECTOR" is the name you chose).
The /var/db/dkim directory and the associated .pem file should be owned by
the user that will be executing the filter (preferably not the
superuser) and be mode 0700 and 0600 respectively.
(4) Start dkim-filter. You will need at least the "-p" option. (A manual
page for this tool is available and will be installed by the above
process if you want to see the available options.) The current
recommended set of command line options is:
-l -p SOCKETSPEC -d DOMAIN -k KEYPATH -s SELECTOR
...where SOCKETSPEC is the socket you want the MTA to use (see below),
DOMAIN is the domain or set of domains for which you want to sign
mail, KEYPATH is the path to the private key file you generated, and
SELECTOR is the selector name you picked. You can tack "-f" on there
if you want it to run in the foreground instead of in the background
as a daemon.
The SOCKETSPEC is a socket where the MTA will attempt to connect
to your filter. The filter must therefore be listening there for
connections from MTAs in order to process messages. See the
documentation in libmilter (available with the open source sendmail
source code) for details on selecting and specifying a socket.
