Fix typo in update.wml spotted by Sylvain Beucler.
[mirror/userdir-ldap-cgi.git] / html / doc-mail.wml
1 #use wml::db.d.o title="LDAP Gateway"
2
3 <p>
4 The LDAP directory has a PGP secured mail gateway that
5 allows users to safely and conveniently effect changes to their entries. It
6 makes use of PGP signed input messages to positively identify the user and
7 to confirm the validity of the request. Furthermore it implements a replay
8 cache that prevents the gateway from accepting the same message more than
9 once.
10
11 <p>
12 There are three functions logically split into 3 separate email addresses
13 that are implemented by the gateway: <b>ping</b>, <b>new password</b> and
14 <b>changes</b>. The function to act on is the first argument to the program.
15
16 <p>
17 Error handling is currently done by generating a bounce message and passing
18 descriptive error text to the mailer. This can generate a somewhat hard to 
19 read error message, but it does have all the relevant information.
20
21 <h1>Ping</h1>
22 The ping command simply returns the users public record. It is useful for
23 testing the gateway and for the requester to get a basic dump of their
24 record. In future this address might 'freshen' the record to indicate the
25 user is alive. Any PGP signed message will produce a reply.
26
27 <h1>New Password</h1>
28 If a user looses their password they can request that a new one be generated 
29 for them. This is done by sending the phrase "Please change my Debian 
30 password" to chpasswd@db.debian.org. The phrase is required to prevent the 
31 daemon from triggering on arbitrary signed email. The best way to invoke this
32 feature is with 
33 <pre>echo "Please change my Debian password" | gpg --clearsign | mail chpasswd@db.debian.org</pre>
34 After validating the request the daemon will generate a new random password,
35 set it in the directory and respond with an encrypted message containing the
36 new password. The password can be changed using one of the other interface
37 methods.
38
39 <h1>Changes</h1>
40 An address (changes@db.debian.org) is provided for making almost arbitrary 
41 changes to the contents of the record. The daemon parses its input line by 
42 line and acts on each line in a command oriented manner. Anything, except for 
43 passwords, can be changed using this mechanism. Note however that because 
44 this is a mail gateway it does stringent checking on its input. The other 
45 tools allow fields to be set to virtually anything, the gateway requires 
46 specific field formats to be met.
47
48 <ul>
49 <li>A line of the form <tt>'field: value'</tt> will change the contents of 
50 the field to value. Some simple checks are performed on value to make sure 
51 that it is not set to nonsense. You can't set an empty string as
52 value, use <tt>del</tt> instead (see below). The values that can
53 be changed are: 
54 <b>c</b>, <b>l</b>, <b>facsimileTelephoneNumber</b>, <b>telephoneNumber</b>, 
55 <b>postalAddress</b>, <b>postalCode</b>,
56 <b>loginShell</b>, <b>emailForward</b>,
57 <b>jabberJID</b>, <b>ircNick</b>, <b>icqUin</b>,
58 <b>onVacation</b>, 
59 <b>labledURI</b>,
60 <b>birthDate</b> (YYYYMMDD),
61 <b>mailDisableMessage</b>,
62 <b>mailGreylisting</b> (TRUE|FALSE),
63 <b>mailCallout</b> (TRUE|FALSE),
64 <b>mailContentInspectionAction</b> (markup|blackhole|reject)
65 <b>mailDefaultOptions</b> (TRUE|FALSE),
66 <b>bATVToken</b>,
67 <b>VoIP</b>,
68 and <b>gender</b> (1|2|9|male|female|unspecified).
69
70 <li>A line of the form <tt>'del field'</tt> will completly remove all
71 occurrences of a field. Useful e.g. to unset your vacation status.
72 The fields that can be deleted are:
73 <b>c</b>, <b>l</b>, <b>facsimileTelephoneNumber</b>, <b>telephoneNumber</b>,
74 <b>postalAddress</b>, <b>postalCode</b>, <b>emailForward</b>,
75 <b>onVacation</b>, <b>labeledURI</b>, <b>latitude</b>, <b>longitude</b>, <b>dnsZoneEntry</b>,
76 <b>ircNick</b>, <b>jabberJID</b>, <b>icquin</b>,
77 <b>sshRSAAuthKey</b>,
78 <b>mailGreylisting</b>,
79 <b>mailCallout</b>,
80 <b>mailRBL</b>,
81 <b>mailRHSBL</b>,
82 <b>mailDisableMessage</b>,
83 <b>mailWhitelist</b>,
84 <b>mailContentInspectionAction</b>,
85 <b>mailDefaultOptions</b>,
86 <b>bATVToken</b>,
87 <b>birthDate</b>,
88 <b>jpegPhoto</b>, <b>VoIP</b>
89
90 <li>The daemon has a special parser to help changing latitude and longitude
91 values. It accepts several common formats for position information and
92 converts them to one of the standard forms. The permitted types are 
93 <pre>D = Degrees, M = Minutes, S = Seconds, x = n,s,e,w
94 +-DDD.DDDDD, +- DDDMM.MMMM, +-DDDMMSS.SSSS [standard forms]
95 DDxMM.MMMM, DD:MM.MMMM x, DD:MM:SS.SSS X)</pre>
96 and the request format is <tt>'Lat: xxx Long: xxx'</tt> where <tt>xxx</tt> 
97 is one of the permitted types. The resulting response will include how the 
98 input was parsed and the value in decimal degrees.
99
100 <li>
101 Part of the replicated dataset is a virtual .ssh/authorized_keys file for
102 each user. The change address is the simplest way to set the RSA key(s) you
103 intend to use. Simply place a key on a line by itself, the full SSH key
104 format specification is supported, see sshd(8). Probably the most common way
105 to use this function will be 
106 <pre>cat .ssh/id_rsa.pub | gpg --clearsign | mail changes@db.debian.org</pre>
107 which will set the authentication key to the identity you are using.
108
109 Multiple keys per user are supported, but they must all be sent at once.
110
111 Keys can be exported to a subset of machines by prepending
112 <b>allowed_hosts=$fqdn,$fqdn2</b> to the specific key. The allowed machines
113 must only be separated by a comma.
114
115 <i>Example:</i>
116 <pre>
117 # cat .ssh/debian-machines.pub
118 allowed_hosts=ravel.debian.org,gluck.debian.org ssh-rsa AAAAB3Nz..mOX/JQ== user@machine
119 ssh-rsa AAAAB3Nz..uD0khQ== user@machine
120 </pre>
121
122 <li>RBL, RHSBL, and whitelists can only be updated via the mail gateway.  Like
123 DNS and ssh keys, any list specified must be specified in its enterity.  The format is:
124 <b>listtype</b> <b>dns.domain.of.rbl/IP to whitelist</b> where listtype is one of mailRBL,
125 mailRHSBL, and mailWhitelist
126
127 <li>Debian.net DNS Zone Entry. The only way to get a debian.net address is
128 to use the mail gateway. It
129 will verify the request and prevent name collisions automatically. Requests
130 can take three forms: <tt>'foo in a 1.2.3.4'</tt>, <tt>'foo in cname
131 foo.bar.'</tt>, or <tt>'foo in mx 10 foo.bar.'</tt> (note the trailing dot).
132 Note that you
133 cannot combine CNAME with any other record types. The precise form
134 is critical and must not be deviated from.
135 Like the SSH function above, multiple hosts are supported, but they must all
136 be sent at once. The debian.net zone is reloaded hourly.
137
138 <li>If the single word <b>show</b> appears on a line then a PGP encrypted version
139 of the entire record will be attached to the resulting email.
140 </ul>
141
142 After processing the requests the daemon will generate a report which contains
143 each input command and the action taken. If there are any parsing errors 
144 processing stops immediately, but valid changes up to that point are
145 processed. 
146
147 <h2>Notes</h2>
148 <p>
149 In this document PGP refers to any message or key that GnuPG is
150 able to generate or parse, specifically it includes both PGP2.x and OpenPGP
151 (aka GnuPG) keys. 
152 <p>
153 Due to the replay cache the clock on the computer that generates the
154 signatures has to be accurate to at least one day. If it is off by several
155 months or more then the daemon will outright reject all messages.
156 <p>
157 Examples are given using GnuPG, but PGP 2.x can also be used. The correct
158 options to generate a clear signed ascii armored message in 'filter' mode
159 are <tt>pgp -fast</tt> which does the same as <tt>gpg --clearsign</tt>
160 <p>
161 Debian.org machines rely on secured replication to transfer login data out
162 of the database. Replication is performed at 15 min intervals so it can take
163 a short while before any changes made take effect.
164 <p>
165 If the mail you're sending to the mail robot is too long for your MTA
166 and gets split please use a different mail origin or pass the mail to
167 the MTA on a debian.org machine, e.g. ravel:
168 <pre>cat .ssh/id_rsa.pub | gpg --clearsign | ssh ravel mail changes@db.debian.org</pre>