The LDAP directory has a PGP secured mail gateway that allows users to safely and conveniently effect changes to their entries. It makes use of PGP signed input messages to positively identify the user and to confirm the validity of the request. Furthermore it implements a replay cache that prevents the gateway from accepting the same message more than once.
There are three functions logically split into 3 separate email addresses that are implemented by the gateway: ping, new password and changes. The function to act on is the first argument to the program.
Error handling is currently done by generating a bounce message and passing descriptive error text to the mailer. This can generate a somewhat hard to read error message, but it does have all the relevant information.
PingThe ping command simply returns the users public record. It is useful for testing the gateway and for the requester to get a basic dump of their record. In future this address might 'freshen' the record to indicate the user is alive. Any PGP signed message will produce a reply.
New PasswordIf a user loses their password they can request that a new one be generated for them. This is done by sending the phrase "Please change my Debian password" to firstname.lastname@example.org. The phrase is required to prevent the daemon from triggering on arbitrary signed email. The best way to invoke this feature is with
echo "Please change my Debian password" | gpg --clearsign | mail email@example.comAfter validating the request the daemon will generate a new random password, set it in the directory and respond with an encrypted message containing the new password. The password can be changed using one of the other interface methods.
ChangesAn address (firstname.lastname@example.org) is provided for making almost arbitrary changes to the contents of the record. The daemon parses its input line by line and acts on each line in a command oriented manner. Anything, except for passwords, can be changed using this mechanism. Note however that because this is a mail gateway it does stringent checking on its input. The other tools allow fields to be set to virtually anything, the gateway requires specific field formats to be met.
- A line of the form 'field: value' will change the contents of the field to value. Some simple checks are performed on value to make sure that it is not set to nonsense. You can't set an empty string as value, use del instead (see below). The values that can be changed are: c, l, facsimileTelephoneNumber, telephoneNumber, postalAddress, postalCode, loginShell, emailForward, jabberJID, ircNick, icqUin, onVacation, labledURI, birthDate (YYYYMMDD), mailDisableMessage, mailGreylisting (TRUE|FALSE), mailCallout (TRUE|FALSE), mailContentInspectionAction (markup|blackhole|reject) mailDefaultOptions (TRUE|FALSE), bATVToken, and VoIP
- A line of the form 'del field' will completly remove all occurrences of a field. Useful e.g. to unset your vacation status. The fields that can be deleted are: c, l, facsimileTelephoneNumber, telephoneNumber, postalAddress, postalCode, emailForward, onVacation, labeledURI, latitude, longitude, dnsZoneEntry, ircNick, jabberJID, icquin, sshRSAAuthKey, mailGreylisting, mailCallout, mailRBL, mailRHSBL, mailDisableMessage, mailWhitelist, mailContentInspectionAction, mailDefaultOptions, dkimPubKey, bATVToken, birthDate, jpegPhoto, VoIP
- The daemon has a special parser to help changing latitude and longitude
values. It accepts several common formats for position information and
converts them to one of the standard forms. The permitted types are
D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w +-DDD.DDDDD, +- DDDMM.MMMM, +-DDDMMSS.SSSS [standard forms] DDxMM.MMMM, DD:MM.MMMM x, DD:MM:SS.SSS X)and the request format is 'Lat: xxx Long: xxx' where xxx is one of the permitted types. The resulting response will include how the input was parsed and the value in decimal degrees.
Part of the replicated dataset is a virtual .ssh/authorized_keys file for
each user. The change address is the simplest way to set the RSA key(s) you
intend to use. Simply place a key on a line by itself, the full SSH key
format specification is supported, see sshd(8). Probably the most common way
to use this function will be
cat .ssh/id_rsa.pub | gpg --clearsign | mail email@example.com will set the authentication key to the identity you are using. Multiple keys per user are supported, but they must all be sent at once. To retrieve the existing SSH keys in order to merge existing keys with new ones, use the 'show' command documented below. Keys can be exported to a subset of machines by prepending allowed_hosts=$fqdn,$fqdn2 to the specific key. The allowed machines must only be separated by a comma. Example:
allowed_hosts=ravel.debian.org,gluck.debian.org ssh-rsa AAAAB3Nz..mOX/JQ== user@machine ssh-rsa AAAAB3Nz..uD0khQ== user@machine
- RBL, RHSBL, and whitelists can only be updated via the mail gateway. Like DNS and SSH keys, any list specified must be specified in its entirety. The format is: listtype dns.domain.of.rbl/IP to whitelist where listtype is one of mailRBL, mailRHSBL, and mailWhitelist
- The only way to get a dnsZoneEntry record for a debian.net address is to
use the mail gateway. It will verify the request and prevent name collisions
automatically. Requests can take several forms:
- foo in a 192.0.2.123
- to create an A record for foo.debian.net
- foo in aaaa 2001:DB8::12:34
- to create an AAAA record for foo.debian.net
- foo in cname example.org.
- to create a CNAME record for foo.debian.net
- foo in txt plain text here
- to create a TXT record for foo.debian.net
- foo in txt v=spf1 spf policy here
- to create an SPF TXT record for foo.debian.net
- foo in mx 10 example.org.
- to create an MX record for foo.debian.net
- you probably want the trailing dot for the target (right-hand-side) hostname with the CNAME and MX records, and
- that you cannot combine CNAME with any other record types.
- Like the SSH function above, multiple hosts are supported, but they must all be sent at once.
- Hostnames need not be directly under the debian.net domain, they can be at several levels so you can for instance do:
example IN CNAME cdn-provider.example.org. _76da4963bbe19b135862864a4ce2dd86.example IN CNAME _76da4963bbe19b135862864a4ce2dd86.cGFzc3dvcmQgLW4K.validation.cdn-provider.example.org.
- Hostnames (the name part on the left-hand-side) need to be relative to the origin and not fully qualified. I.e., use example and not example.debian.net. as the hostname.
- You can add DKIM public keys using the mail gateway. A request should be of the form:
dkimPubKey: <selector>.<uid>.user <base64-encoded key>or
dkimPubKey: <selector>.<uid>.user p=<base64-encoded key> k=<algorithm> [attr=value ...]to create a TXT record for
- "uid" must be your debian.org username
- "selector" must be alphanumeric, "_" or "-"
- supported key algorithms are "rsa" and "ed25519", with the default being "rsa"
- supported hash types are "sha256"
- unsupported key attributes are ignored
dkimPubKey: <selector>.<uid>.user CNAME <someselector.example.org.>Like the SSH and debian.net DNS functions above, multiple selectors are supported, but they must all be sent at once.
- If the single word show appears on a line then a PGP encrypted version
of the entire record will be attached to the resulting email. For example:
echo show | gpg --clearsign | mail firstname.lastname@example.org
In this document PGP refers to any message or key that GnuPG is able to generate or parse, specifically it includes both PGP2.x and OpenPGP (aka GnuPG) keys.
Due to the replay cache the clock on the computer that generates the signatures has to be accurate to at least one day. If it is off by several months or more then the daemon will outright reject all messages.
Examples are given using GnuPG, but PGP 2.x can also be used. The correct options to generate a clear signed ascii armored message in 'filter' mode are pgp -fast which does the same as gpg --clearsign
Debian.org machines rely on secured replication to transfer login data out of the database. Replication is performed at 15 min intervals so it can take a short while before any changes made take effect.
If the mail you're sending to the mail robot is too long for your MUA and gets split, or if you want something that is more robust while copy pasting into a web-mailer, you can try to create a non-clearsigned message and mail that to email@example.com:
cat .ssh/id_rsa.pub | gpg --armor --sign
You can contact us at firstname.lastname@example.org.