web/doc-mail.wml

   1 #use wml::debian::template title="LDAP Gateway"
   2
   3 The LDAP directory has a PGP secured mail gateway that
   4 allows users to safely and conviently effect changes to their entries. It
   5 makes use of PGP signed input messages to positivly identify the user and
   6 to confirm the validity of the request. Furthermore it implements a replay
   7 cache that prevents the gateway from accepting the same message more than
   8 once.
   9
  10 <p>
  11 There are three functions logically split into 3 sperate email addresses
  12 that are implemented by the gateway: <b>ping</b>, <b>new password</b> and
  13 <b>changes</b>. The function to act on is the first argument to the program.
  14
  15 <p>
  16 Error handling is currently done by generating a bounce message and passing
  17 descriptive error text to the mailer. This can generate a somewhat hard to
  18 read error message, but it does have all the relevent information.
  19
  20 <h1>Ping</h1>
  21 The ping command simply returns the users public record. It is usefull for
  22 testing the gateway and for the requester to get a basic dump of their
  23 record. In future this address might 'freshen' the record to indicate the
  24 user is alive. Any PGP signed message will produce a reply.
  25
  26 <h1>New Password</h1>
  27 If a user looses their password they can request that a new one be generated
  28 for them. This is done by sending the phrase "Please change my Debian
  29 password" to chpasswd@db.debian.org. The phrase is required to prevent the
  30 daemon from triggering on arbitary signed email. The best way to invoke this
  31 feature is with
  32 <pre>echo "Please change my Debian password" | gpg --clearsign | mail chpasswd@db.debian.org</pre>
  33 After validating the request the daemon will generate a new random password,
  34 set it in the directory and respond with an ecrpyted message containing the
  35 new password. The password can be changed using one of the other interface
  36 methods.
  37
  38 <h1>Changes</h1>
  39 An address is provided for making almost arbitary changes to the contents of
  40 the record. The daemon parse its input line by line and acts on each line in
  41 a command oriented manner. Anything, except for passwords, can be changed
  42 using this mechanism. Note however that because this is a mail gateway it
  43 does stringent checking on its input. The other tools allow fields to be set
  44 to virtually anything, the gateway requires specific field formats to be met.
  45
  46 <ul>
  47 <li>A line of the form <tt>'field: value'</tt> will change the contents of
  48 the field to value. Some simple checks are performed on value to make sure
  49 that it is not sent to nonsense. The values that can be changed are:
  50 <b>c</b>, <b>l</b>, <b>facsimiletelephonenumber</b>, <b>telephonenumber</b>,
  51 <b>postaladdress</b>, <b>postalcode</b>,
  52 <b>loginshell</b>, <b>emailforward</b>, <b>ircnick</b>, <b>onvacation</b>,
  53 and <b>labledurl</b>
  54
  55 <li>The daemon has a special parser to help changing latitude and longitude
  56 values. It accepts several common formats for position information and
  57 converts them to one of the standard forms. The permitted types are
  58 <pre>D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w
  59 +-DDD.DDDDD, +- DDDMM.MMMM, +-DDDMMSS.SSSS [standard forms]
  60 DDxMM.MMMM, DD:MM.MMMM x, DD:MM:SS.SSS X)</pre>
  61 and the request format is <tt>'Lat: xxx Long: xxx'</tt> where <tt>xxx</tt>
  62 is one of the permitted types. The resulting response will include how the
  63 input was parsed and the value in decimal degrees.
  64
  65 <li>
  66 Part of the replicated dataset is a virtual .ssh/authorized_keys file for
  67 each user. The change address is the simplest way to set the RSA key(s) you
  68 intend to use. Simply place a key on a line by itself, the full SSH key
  69 format specification is supported, see sshd(8). Probably the most common way
  70 to use this function will be
  71 <pre>cat .ssh/identity.pub | gpg --clearsign | mail change@db.debian.org</pre>
  72 which will set the authentication key to the identity you are using.
  73
  74 Multiple keys per user are supported, but they must all be sent at once.
  75
  76 <li>Debian.net DNS Zone Entry. The only way to get a debian.net address is
  77 to use the mail gateway. It
  78 will verify the request and prevent name collisions automatically. Requests
  79 can take two forms: <tt>'foo in a 1.2.3.4'</tt> or <tt>'foo in cname
  80 foo.bar.'</tt> The precise form is critical and must not be deviated from.
  81
  82 Like the SSH function above, multiple hosts are supported, but they must all
  83 be sent at once. The debian.net zone is only reloaded once per day at
  84 midnight -0700.
  85
  86 <li>If the single word <b>show</b> appears on a line then a PGP encrypted version
  87 of the entire record will be attached to the result email.
  88 </ul>
  89
  90 After processing the requests the daemon will generate a report which contains
  91 each input command and the action taken. If there are any parsing errors
  92 processing stops immediately, but valid changes up to that point are
  93 processed.
  94
  95 <h2>Notes</h2>
  96 <p>
  97 In this document PGP refers to any message or key that GnuPG is
  98 able to generate or parse, specificaly it includes both PGP2.x and OpenPGP
  99 (aka GnuPG) keys.
 100 <p>
 101 Due to the replay cache the clock on the computer that generates the
 102 signatures has to be accurate to at least one day. If it is off by several
 103 months or more then the deamon will outright reject all messages.
 104 <p>
 105 Examples are given using GnuPG, but PGP 2.x can also be used. The correct
 106 options to generate a clear signed ascii armored message in 'filter' mode
 107 are <tt>pgp -fast</tt> which does the same as <tt>gpg --clearsign</tt>
 108 <p>
 109 Debian.org machines rely on secured replication to transfer login data out
 110 of the database. Replication is performed at 15 min intervals so it can take
 111 a short while before any changes made take effect.