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