doc/ud-mailgate.8.yo

   1 mailto(admin@db.debian.org)
   2 manpage(ud-mailgate)(1)(28 Sep 1999)(userdir-ldap)()
   3 manpagename(ud-mailgate)(PGP mail gateway to the LDAP directory)
   4
   5 manpagesynopsis()
   6   ud-mailgate function
   7
   8 manpagedescription()
   9 ud-mailgate implements a PGP secured mail gateway to an LDAP directory that
  10 allows users to safely and conviently effect changes to their entries. It
  11 makes use of PGP signed input messages to positivly identify the user and
  12 to confirm the validity of the request. Furthermore it implements a replay
  13 cache that prevents the gateway from accepting the same message more than
  14 once.
  15
  16 There are three functions logically split into 3 sperate email addresses
  17 that are implemented by the gateway: bf(ping), bf(new password) and
  18 bf(changes). The function to act on is the first argument to the program.
  19
  20 ud-mailgate was designed to take its message on stdin from a mailsystem like
  21 Exim, with full message headers intact. It transparently decodes PGP/MIME
  22 and PGP clearsigned messages and passes them through GnuPG for verification.
  23 Support for PGP2.x users is maintained by passing options to GunPG that
  24 generate encrypted messages they are able to decode, however this option
  25 is only enabled for PGP2.x keys, OpenPGP keys use the new packet formats.
  26
  27 Error handling is currently done by generating a bounce message and passing
  28 descriptive error text to the mailer. For mailers like Exim this generates a
  29 very hard to read message, but it does have the relevent information
  30 embedded in it.
  31
  32 manpagesection(PING)
  33 The ping command simply returns the users public record. It is usefull for
  34 testing the gateway and for the requester to get a basic dump of their
  35 record. In future this address might 'freshen' the record to indicate the
  36 user is alive. Any PGP signed message will produce a reply.
  37
  38 manpagesection(NEW PASSWORD)
  39 If a user looses their password they can request that a new one be generated
  40 for them. This is done by sending the phrase "Please change my Debian
  41 password" to chpasswd@db.debian.org. The phrase is required to prevent the
  42 daemon from triggering on arbitary signed email. The best way to invoke this
  43 feature is with verb(echo "Please change my Debian password" | gpg
  44 --clearsign | mail chpasswd@db.debian.org)
  45 After validating the request the daemon will generate a new random password,
  46 set it in the directory and respond with an ecrpyted message containing the
  47 new password. The password can be changed using one of the other interface
  48 methods.
  49
  50 manpagesection(CHANGES)
  51 An address is provided for making almost arbitary changes to the contents of
  52 the record. The daemon parse its input line by line and acts on each line in
  53 a command oriented manner. Anything, except for passwords, can be changed
  54 using this mechanism. Note however that because this is a mail gateway it
  55 does stringent checking on its input. The other tools allow fields to be set
  56 to virtually anything, the gateway requires specific field formats to be met.
  57
  58 startdit()
  59 dit(Arbitary Change)
  60 A line of the form bf('field: value') will change the contents of the field
  61 to value. Some simple checks are performed on value to make sure that it is
  62 not sent to nonsense. The values that can be changed are: c, l,
  63 facsimiletelephonenumber, telephonenumber, postaladdress, postalcode,
  64 loginshell, emailforward, ircnick, onvacation, and labledurl. See
  65 ud-info(1) for information on the meanings of each field type.
  66
  67 dit(Latitude/Longitude Change)
  68 The daemon has a special parser to help changing latitude and longitude
  69 values. It accepts several common formats for position information and
  70 converts them to one of the standard forms. The permitted types are
  71 verb(D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w
  72 +-DDD.DDDDD, +- DDDMM.MMMM, +-DDDMMSS.SSSS [standard forms]
  73 DDxMM.MMMM, DD:MM.MMMM x, DD:MM:SS.SSS X)
  74 and the request format is bf('Lat: xxx Long: xxx') where xxx is one of the
  75 permitted types. The resulting response will include how the input was
  76 parsed and the value in decimal degrees.
  77
  78 dit(SSH RSA Authentication key load)
  79 Part of the replicated dataset is a virtual .ssh/authorized_keys file for
  80 each user. The change address is the simplest way to set the RSA key(s) you
  81 intend to use. Simply place a key on a line by itself, the full SSH key
  82 format specification is supported, see sshd(8). Probably the most common way
  83 to use this function will be verb(cat .ssh/identity.pub | gpg --clearsign |
  84 mail change@db.debian.org) which will set the authentication key to the
  85 identity you are using.
  86
  87 Multiple keys per user are supported, but they must all be sent at once.
  88
  89 dit(DNS Zone Entry)
  90 The only way to get a debian.net address is to use this mail gateway. It
  91 will verify the request and prevent name collisions automatically. Requests
  92 can take two forms: bf('foo in a 1.2.3.4') or bf('foo in cname foo.bar.')
  93 The precise form is critical and must not be deviated from.
  94
  95 Like the SSH function above, multiple hosts are supported, but they must all
  96 be sent at once. The debian.net zone is only reloaded once per day at
  97 midnight -0700.
  98
  99 dit(Show Function)
 100 If the single word bf('show') appears on a line then a PGP encrypted version
 101 of the entire record will be attached to the result email.
 102
 103 dit(Erasing an entry)
 104 The command bf('del foo') can be used to erase any of the entries settable by
 105 the user. The erasable attributes are: c, l, facsimiletelephonenumber,
 106 telephonenumber, postaladdress, postalcode, emailforward, ircnick,
 107 onvacation, labeledurl, latitude, longitude, and sshrsaauthkey.
 108
 109 enddit()
 110
 111 After processing the requests the daemon will generate a report which contains
 112 each input command and the action taken. If there are any parsing errors
 113 processing stops immediately, but valid changes up to that point are
 114 processed.
 115
 116 manpagesection(NOTES)
 117 In this document PGP refers to any message or key that GnuPG is
 118 able to generate or parse, specificaly it includes both PGP2.x and OpenPGP
 119 (aka GnuPG) keys.
 120
 121 Due to the replay cache the clock on the computer that generates the
 122 signatures has to be accurate to at least one day. If it is off by several
 123 months or more then the deamon will outright reject all messages.
 124
 125 Examples are given using GnuPG, but PGP 2.x can also be used. The correct
 126 options to generate a clear signed ascii armored message in 'filter' mode
 127 are bf(pgp -fast) which does the same as bf(gpg --clearsign)
 128
 129 Debian.org machines rely on secured replication to transfer login data out
 130 of the database. Replication is performed at 15 min intervals so it can take
 131 a short while before any changes made take effect.
 132
 133 manpagefiles()
 134 itemize(
 135   it() /etc/userdir-ldap/userdir-ldap.conf
 136   Configuration variables to select what server and what base DN to use.
 137 )
 138
 139 manpageauthor()
 140 userdir-ldap was written by Jason Gunthorpe <jgg@debian.org>.
 141