--- /dev/null
+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 <jgg@debian.org>.
+
projects / mirror / userdir-ldap.git / commitdiff