From f42595c4de6b10a9f81d17f4360361130458c2af Mon Sep 17 00:00:00 2001 From: jgg <> Date: Fri, 1 Oct 1999 01:49:39 +0000 Subject: [PATCH] New doc --- doc/ud-mailgate.8.yo | 135 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 doc/ud-mailgate.8.yo diff --git a/doc/ud-mailgate.8.yo b/doc/ud-mailgate.8.yo new file mode 100644 index 0000000..4fb1bac --- /dev/null +++ b/doc/ud-mailgate.8.yo @@ -0,0 +1,135 @@ +mailto(admin@db.debian.org) +manpage(ud-mailgate)(1)(28 Sep 1999)(userdir-ldap)() +manpagename(ud-mailgate)(PGP mail gateway to the LDAP directory) + +manpagesynopsis() + ud-mailgate function + +manpagedescription() +ud-mailgate implements a PGP secured mail gateway to an LDAP directory that +allows users to safely and conviently effect changes to their entries. It +makes use of PGP signed input messages to positivly 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 sperate email addresses +that are implemented by the gateway: bf(ping), bf(new password) and +bf(changes). The function to act on is the first argument to the program. + +ud-mailgate was designed to take its message on stdin from a mailsystem like +Exim, with full message headers intact. It transparently decodes PGP/MIME +and PGP clearsigned messages and passes them through GnuPG for verification. +Support for PGP2.x users is maintained by passing options to GunPG that +generate encrypted messages they are able to decode, however this option +is only enabled for PGP2.x keys, OpenPGP keys use the new packet formats. + +Error handling is currently done by generating a bounce message and passing +descriptive error text to the mailer. For mailers like Exim this generates a +very hard to read message, but it does have the relevent information +embedded in it. + +manpagesection(PING) +The ping command simply returns the users public record. It is usefull 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. + +manpagesection(NEW PASSWORD) +If a user looses 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 chpasswd@db.debian.org. The phrase is required to prevent the +daemon from triggering on arbitary signed email. The best way to invoke this +feature is with verb(echo "Please change my Debian password" | gpg +--clearsign | mail chpasswd@db.debian.org) +After validating the request the daemon will generate a new random password, +set it in the directory and respond with an ecrpyted message containing the +new password. The password can be changed using one of the other interface +methods. + +manpagesection(CHANGES) +An address is provided for making almost arbitary changes to the contents of +the record. The daemon parse 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. + +startdit() +dit(Arbitary Change) +A line of the form bf('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 sent to nonsense. The values that can be changed are: c, l, +facsimiletelephonenumber, telephonenumber, postaladdress, postalcode, +loginshell, emailforward, ircnick, onvacation, and onvacation. See +ud-info(1) for information on the meanings of each field type. + +dit(Latitude/Longitude Change) +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 +verb(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 bf('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. + +dit(SSH RSA Authentication key load) +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 verb(cat .ssh/identity.pub | gpg --clearsign | +mail change@debian.org) which 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. + +dit(DNS Zone Entry) +The only way to get a debian.net address is to use this mail gateway. It +will verify the request and prevent name collisions automatically. Requests +can take two forms: bf('foo in a 1.2.3.4') or bf('foo in cname foo.bar.') +The precise form is critical and must not be deviated from. + +Like the SSH function above, multiple hosts are supported, but they must all +be sent at once. The debian.net zone is only reloaded once per day at +midnight -0700. + +dit(Show Function) +If the single word bf('show') appears on a line then a PGP encrypted version +of the entire record will be attached to the result email. + +enddit() + +After processing the requests the daemon will generate a report which contains +each input command and the action taken. If there are any parsing errors +processing stops immediately, but valid changes up to that point are +processed. + +manpagesection(NOTES) +In this document PGP refers to any message or key that GnuPG is +able to generate or parse, specificaly 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 deamon 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 bf(pgp -fast) which does the same as bf(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. + +manpagefiles() +itemize( + it() /etc/userdir-ldap/userdir-ldap.conf + Configuration variables to select what server and what base DN to use. +) + +manpageauthor() +userdir-ldap was written by Jason Gunthorpe . + -- 2.20.1