html/doc-mail.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html lang="en">
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=">
   5   <title>Debian Project -- LDAP Gateway</title>
   6   <link rev="made" href="mailto:webmaster@debian.org">
   7   <meta name="Generator" content="WML 2.0.11 (19-Aug-2006)">
   8   <meta name="Modified" content="2009-06-02 12:31:59">
   9 </head>
  10 <body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#800080" alink="#FF0000">
  11 <table width="100%" align="center" border="0" cellpadding="3" cellspacing="0" summary="">
  12 <tr>
  13   <td align="left" valign="middle">
  14   <a href="http://www.debian.org/"><img src="http://www.debian.org/logos/openlogo-nd-50.png" border="0" hspace="0" vspace="0" alt=""></a>
  15   <a href="http://www.debian.org/" rel="start"><img src="http://www.debian.org/Pics/debian.png" border="0" hspace="0" vspace="0" alt="Debian Project"></a>
  16   </td>
  17 </tr>
  18 </table>
  19 <!--UdmComment-->
  20 <table bgcolor="#DF0451" border="0" cellpadding="0" cellspacing="0" width="100%" summary="">
  21 <tr>
  22 <td valign="top">
  23 <img src="http://www.debian.org/Pics/red-upperleft.png" align="left" border="0" hspace="0" vspace="0" alt="">
  24 </td>
  25 <td rowspan="2" align="center">
  26 <a href="http://www.debian.org/intro/about"><img src="http://www.debian.org/Pics/about.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="About Debian"></a>
  27 <a href="http://www.debian.org/News/"><img src="http://www.debian.org/Pics/news.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="News"></a>
  28 <a href="http://www.debian.org/distrib/"><img src="http://www.debian.org/Pics/getting.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="Getting Debian"></a>
  29 <a href="http://www.debian.org/support"><img src="http://www.debian.org/Pics/support.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="Support"></a>
  30 <a href="http://www.debian.org/devel/"><img src="http://www.debian.org/Pics/devel.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="Developers'&nbsp;Corner"></a>
  31 <a href="http://www.debian.org/sitemap" rel="contents"><img src="http://www.debian.org/Pics/sitemap.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="Site map"></a>
  32 <a href="http://search.debian.org/"><img src="http://www.debian.org/Pics/search.en.gif" align="middle" border="0" hspace="4" vspace="7" alt="Search"></a>
  33 </td>
  34 <td valign="top">
  35 <img src="http://www.debian.org/Pics/red-upperright.png" align="right" border="0" hspace="0" vspace="0" alt="">
  36 </td>
  37 </tr>
  38 <tr>
  39 <td valign="bottom">
  40 <img src="http://www.debian.org/Pics/red-lowerleft.png" align="left" border="0" hspace="0" vspace="0" alt="">
  41 </td>
  42 <td valign="bottom">
  43 <img src="http://www.debian.org/Pics/red-lowerright.png" align="right" border="0" hspace="0" vspace="0" alt="">
  44 </td>
  45 </tr>
  46 </table>
  47 <!--/UdmComment-->
  48 <h1>LDAP Gateway</h1>
  49 <p>
  50 The LDAP directory has a PGP secured mail gateway that
  51 allows users to safely and conveniently effect changes to their entries. It
  52 makes use of PGP signed input messages to positively identify the user and
  53 to confirm the validity of the request. Furthermore it implements a replay
  54 cache that prevents the gateway from accepting the same message more than
  55 once.
  56 <p>
  57 There are three functions logically split into 3 separate email addresses
  58 that are implemented by the gateway: <b>ping</b>, <b>new password</b> and
  59 <b>changes</b>. The function to act on is the first argument to the program.
  60 <p>
  61 Error handling is currently done by generating a bounce message and passing
  62 descriptive error text to the mailer. This can generate a somewhat hard to
  63 read error message, but it does have all the relevant information.
  64 <h1>Ping</h1>
  65 The ping command simply returns the users public record. It is useful for
  66 testing the gateway and for the requester to get a basic dump of their
  67 record. In future this address might 'freshen' the record to indicate the
  68 user is alive. Any PGP signed message will produce a reply.
  69 <h1>New Password</h1>
  70 If a user looses their password they can request that a new one be generated
  71 for them. This is done by sending the phrase "Please change my Debian
  72 password" to chpasswd@db.debian.org. The phrase is required to prevent the
  73 daemon from triggering on arbitrary signed email. The best way to invoke this
  74 feature is with
  75 <pre>echo "Please change my Debian password" | gpg --clearsign | mail chpasswd@db.debian.org</pre>
  76 After validating the request the daemon will generate a new random password,
  77 set it in the directory and respond with an encrypted message containing the
  78 new password. The password can be changed using one of the other interface
  79 methods.
  80 <h1>Changes</h1>
  81 An address (changes@db.debian.org) is provided for making almost arbitrary
  82 changes to the contents of the record. The daemon parses its input line by
  83 line and acts on each line in a command oriented manner. Anything, except for
  84 passwords, can be changed using this mechanism. Note however that because
  85 this is a mail gateway it does stringent checking on its input. The other
  86 tools allow fields to be set to virtually anything, the gateway requires
  87 specific field formats to be met.
  88 <ul>
  89 <li>A line of the form <tt>'field: value'</tt> will change the contents of
  90 the field to value. Some simple checks are performed on value to make sure
  91 that it is not set to nonsense. You can't set an empty string as
  92 value, use <tt>del</tt> instead (see below). The values that can
  93 be changed are:
  94 <b>c</b>, <b>l</b>, <b>facsimileTelephoneNumber</b>, <b>telephoneNumber</b>,
  95 <b>postalAddress</b>, <b>postalCode</b>,
  96 <b>loginShell</b>, <b>emailForward</b>,
  97 <b>jabberJID</b>, <b>ircNick</b>, <b>icqUin</b>,
  98 <b>onVacation</b>,
  99 <b>labledURI</b>,
 100 <b>birthDate</b> (YYYYMMDD),
 101 <b>mailDisableMessage</b>,
 102 <b>mailGreylisting</b> (TRUE|FALSE),
 103 <b>mailCallout</b> (TRUE|FALSE),
 104 <b>VoIP</b>,
 105 and <b>gender</b> (1|2|9|male|female|unspecified).
 106 <li>A line of the form <tt>'del field'</tt> will completly remove all
 107 occurrences of a field. Useful e.g. to unset your vacation status.
 108 The fields that can be deleted are:
 109 <b>c</b>, <b>l</b>, <b>facsimileTelephoneNumber</b>, <b>telephoneNumber</b>,
 110 <b>postalAddress</b>, <b>postalCode</b>, <b>emailForward</b>,
 111 <b>onVacation</b>, <b>labeledURI</b>, <b>latitude</b>, <b>longitude</b>, <b>dnsZoneEntry</b>,
 112 <b>ircNick</b>, <b>jabberJID</b>, <b>icquin</b>,
 113 <b>sshRSAAuthKey</b>,
 114 <b>mailGreylisting</b>, <b>mailCallout</b>, <b>mailRBL</b>, <b>mailRHSBL</b>, <b>mailDisableMessage</b>, <b>mailWhitelist</b>,
 115 <b>birthDate</b>,
 116 <b>jpegPhoto</b>, <b>VoIP</b>
 117 <li>The daemon has a special parser to help changing latitude and longitude
 118 values. It accepts several common formats for position information and
 119 converts them to one of the standard forms. The permitted types are
 120 <pre>D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w
 121 +-DDD.DDDDD, +- DDDMM.MMMM, +-DDDMMSS.SSSS [standard forms]
 122 DDxMM.MMMM, DD:MM.MMMM x, DD:MM:SS.SSS X)</pre>
 123 and the request format is <tt>'Lat: xxx Long: xxx'</tt> where <tt>xxx</tt>
 124 is one of the permitted types. The resulting response will include how the
 125 input was parsed and the value in decimal degrees.
 126 <li>
 127 Part of the replicated dataset is a virtual .ssh/authorized_keys file for
 128 each user. The change address is the simplest way to set the RSA key(s) you
 129 intend to use. Simply place a key on a line by itself, the full SSH key
 130 format specification is supported, see sshd(8). Probably the most common way
 131 to use this function will be
 132 <pre>cat .ssh/id_rsa.pub | gpg --clearsign | mail changes@db.debian.org</pre>
 133 which will set the authentication key to the identity you are using.
 134 Multiple keys per user are supported, but they must all be sent at once.
 135 <li>RBL, RHSBL, and whitelists can only be updated via the mail gateway. Like
 136 DNS and ssh keys, any list specified must be specified in its enterity. The format is:
 137 <b>listtype</b> <b>dns.domain.of.rbl/IP to whitelist</b> where listtype is one of mailRBL,
 138 mailRHSBL, and mailWhitelist
 139 <li>Debian.net DNS Zone Entry. The only way to get a debian.net address is
 140 to use the mail gateway. It
 141 will verify the request and prevent name collisions automatically. Requests
 142 can take three forms: <tt>'foo in a 1.2.3.4'</tt>, <tt>'foo in cname
 143 foo.bar.'</tt>, or <tt>'foo in mx 10 foo.bar.'</tt> (note the trailing dot).
 144 Note that you
 145 cannot combine CNAME with any other record types. The precise form
 146 is critical and must not be deviated from.
 147 Like the SSH function above, multiple hosts are supported, but they must all
 148 be sent at once. The debian.net zone is reloaded hourly.
 149 <li>If the single word <b>show</b> appears on a line then a PGP encrypted version
 150 of the entire record will be attached to the resulting email.
 151 </ul>
 152 After processing the requests the daemon will generate a report which contains
 153 each input command and the action taken. If there are any parsing errors
 154 processing stops immediately, but valid changes up to that point are
 155 processed.
 156 <h2>Notes</h2>
 157 <p>
 158 In this document PGP refers to any message or key that GnuPG is
 159 able to generate or parse, specifically it includes both PGP2.x and OpenPGP
 160 (aka GnuPG) keys.
 161 <p>
 162 Due to the replay cache the clock on the computer that generates the
 163 signatures has to be accurate to at least one day. If it is off by several
 164 months or more then the daemon will outright reject all messages.
 165 <p>
 166 Examples are given using GnuPG, but PGP 2.x can also be used. The correct
 167 options to generate a clear signed ascii armored message in 'filter' mode
 168 are <tt>pgp -fast</tt> which does the same as <tt>gpg --clearsign</tt>
 169 <p>
 170 Debian.org machines rely on secured replication to transfer login data out
 171 of the database. Replication is performed at 15 min intervals so it can take
 172 a short while before any changes made take effect.
 173 <p>
 174 If the mail you're sending to the mail robot is too long for your MTA
 175 and gets split please use a different mail origin or pass the mail to
 176 the MTA on a debian.org machine, e.g. gluck:
 177 <pre>cat .ssh/id_rsa.pub | gpg --clearsign | ssh gluck mail changes@db.debian.org</pre>
 178 <hr noshade width="100%" size="1">
 179 Back to the <a href="http://www.debian.org/">Debian Project homepage</a>.
 180 <hr noshade width="100%" size="1">
 181 <small>
 182 You can contact us at
 183 <a href="mailto:admin@db.debian.org">admin@db.debian.org</a>.
 184 </small>
 185 <p>
 186 <p><small>
 187 Last Modified: Tue, Jun 2 12:31:58 UTC 2009
 188   <br>
 189   Copyright &copy; 1997-2009
 190  <a href="http://www.spi-inc.org/">SPI</a>; See <a href="http://www.debian.org/license" rel="copyright">license terms</a><br>
 191   Debian is a registered trademark of Software in the Public Interest, Inc.
 192 </small></p>
 193 </body>
 194 </html>