diff --git a/howto/ldap.md b/howto/ldap.md index e4fa6095e005f7b27ea076a2983b000d76719a65..31bd21e7ffda71b8da9ec6655f18a14860fe0dee 100644 --- a/howto/ldap.md +++ b/howto/ldap.md @@ -10,18 +10,12 @@ management procedures, see [issue 40129](https://gitlab.torproject.org/tpo/tpa/t # Tutorial -The main LDAP documentation is on [web interface][db.torproject.org]. See -specifically the instructions on how to: +Our LDAP configuration is rather exotic. You will typically use the +[web interface][db.torproject.org] and the OpenPGP-enabled email interface. This +documentation aims at getting you familiar with the basics. [db.torproject.org]: https://db.torproject.org/ - * [reset a lost password](https://db.torproject.org/password.html) - * [change your SSH key](https://db.torproject.org/doc-mail.html) - -The rest of this document is targeted at sysadmins troubleshooting -LDAP issues, setting up new services, or trying to understand the -setup. - ## Getting to know LDAP You should have received an email like this when your LDAP account was @@ -46,12 +40,182 @@ double-signing the email and sending in clear text (instead of HTML). The email forward can also be changed in the [web interface][db.torproject.org]. +## Password reset + +<!-- warning: this documentation is copied from `html/password.wml` --> +<!-- in the userdir-ldap-cgi.git repository. It should be updated in --> +<!-- both places if changes are made. --> + +If you have lost or forgotten your LDAP password, you can have it +reset by sending a PGP signed message to the mail gateway: + + echo "Please change my Tor password" | gpg --armor --sign + +And email the result to `chpasswd@db.torproject.org`. Make sure you +send the email as plain text, not HTML. + +The daemon will then respond with a new randomized password encrypted +with your key. Then use the [update form](https://db.torproject.org/login.html) to change your password +to a strong password you can remember or (preferably) a stronger +password stored in your password manager. + +You cannot set a new password via the mail gateway. + +Alternatively, you can do without a password and use PGP to manipulate +your LDAP information through the [mail gateway](#operate-the-mail-gateway), which includes +instructions on SSH public key authentication, for example. + # How-to ## Set a sudo password See the [sudo password user configuration](doc/accounts#sudo). +## Operate the mail gateway + +<!-- warning: this documentation is copied from `html/doc-mail.wml` --> +<!-- in the userdir-ldap-cgi.git repository. It should be updated in --> +<!-- both places if changes are made. --> + +The LDAP directory has a PGP secured mail gateway that allows users to safely +and conveniently effect changes to their entries. It makes use of PGP signed +input messages to positively identify the user and to confirm the validity of +the request. Furthermore it implements a replay cache that prevents the gateway +from accepting the same message more than once. + +There are three functions logically split into 3 separate email addresses that +are implemented by the gateway: ping, new password and changes. The function to +act on is the first argument to the program. + +Error handling is currently done by generating a bounce message and passing +descriptive error text to the mailer. This can generate a somewhat hard to read +error message, but it does have all the relevant information. + +### ping + +The ping command simply returns the users public record. It is useful for +testing the gateway and for the requester to get a basic dump of their record. +In future this address might 'freshen' the record to indicate the user is +alive. Any PGP signed message will produce a reply. + +### New Password + +If a user loses their password they can request that a new one be generated for +them. This is done by sending the phrase "Please change my Tor password" to +`chpasswd@db.torproject.org`. The phrase is required to prevent the daemon from +triggering on arbitrary signed email. The best way to invoke this feature is +with: + + echo "Please change my Tor password" | gpg --armor --sign | mail chpasswd@db.torproject.org + +After validating the request the daemon will generate a new random password, +set it in the directory and respond with an encrypted message containing the +new password. The password can be changed using one of the other interface +methods. + +### Changes + +An address (`changes@db.torproject.org`) is provided for making almost arbitrary +changes to the contents of the record. The daemon parses its input line by line +and acts on each line in a command oriented manner. Anything, except for +passwords, can be changed using this mechanism. Note however that because this +is a mail gateway it does stringent checking on its input. The other tools +allow fields to be set to virtually anything, the gateway requires specific +field formats to be met. + + * **field**: A line of the form `field: value` will change the + contents of the field to value. Some simple checks are performed on + value to make sure that it is not set to nonsense. You can't set an + empty string as value, use `del` instead (see below). The values that + can be changed are: `loginShell`, `emailForward`, `ircNick`, `jabberJID`, + `labledURI`, and `VoIP` + + * **del field**: A line of the form `del field` will completly remove all + occurrences of a field. Useful e.g. to unset your vacation status. + + * **SSH keys changes**, see [uploading a SSH user key](#uploading-a-ssh-user-key) + + * **show**: If the single word show appears on a line in a PGP signed + mail then a PGP encrypted version of the entire record will be + attached to the resulting email. For example: + + echo show | gpg --clearsign | mail changes@db.debian.org + +Note that the changes alias does not handle PGP/MIME emails. + +After processing the requests the daemon will generate a report which +contains each input command and the action taken. If there are any +parsing errors processing stops immediately, but valid changes up to +that point are processed. + +### Notes + +In this document PGP refers to any message or key that GnuPG is able to +generate or parse, specifically it includes both PGP2.x and OpenPGP (aka GnuPG) +keys. + +Due to the replay cache the clock on the computer that generates the signatures +has to be accurate to at least one day. If it is off by several months or more +then the daemon will outright reject all messages. + +## Uploading a SSH user key + +<!-- warning: this documentation is copied from a part of `html/doc-mail.wml` --> +<!-- in the userdir-ldap-cgi.git repository. It should be updated in --> +<!-- both places if changes are made. --> + +To upload a key into your `authorized_keys` file on all servers, +simply place the key on a line by itself, sign the message and send it +to `changes@db.torproject.org`. The full SSH key format specification +is supported, see sshd(8). Probably the most common way to use this +function will be + + gpg --armor --sign < ~/.ssh/id_rsa.pub | mail changes@db.torproject.org + +Which will set your `authorized_keys` to `~/.ssh/id_rsa.pub` on all +servers. + +Supported key types are RSA (at least 2048 bits) and Ed25519. + +Multiple keys per user are supported, but they must all be sent at +once. To retrieve the existing SSH keys in order to merge existing +keys with new ones, use the `show` command documented above. + +Keys can be exported to a subset of machines by prepending +`allowed_hosts=$fqdn,$fqdn2` to the specific key. The allowed machines +must only be separated by a comma. Example: + + allowed_hosts=ravel.debian.org,gluck.debian.org ssh-rsa AAAAB3Nz..mOX/JQ== user@machine + ssh-rsa AAAAB3Nz..uD0khQ== user@machine + +## SSH host key verification + +<!-- warning: this documentation is copied from `html/doc-hosts.wml` --> +<!-- in the userdir-ldap-cgi.git repository. It should be updated in --> +<!-- both places if changes are made. --> + +The SSH host keys are stored in the LDAP database. The key and its +fingerprint will be displayed alongside machine details in the +[machine list](https://db.torproject.org/machines.cgi). + +Developers that have a secure path to a DNSSEC enabled resolver can +verify the existing SSHFP records by adding `VerifyHostKeyDNS yes` to +their `~/.ssh/config` file. + +On machines in which are updated from the LDAP database, +`/etc/ssh/ssh_known_hosts` contains the keys for all hosts in this +domain. + +Developers should add `StrictHostKeyChecking yes` to their +`~/.ssh/config` file so that they only connect to trusted +hosts. Either with the DNSSEC records or the file mentioned above, +nearly all hosts in the domain can be trusted automatically. + +Developers can also execute `ud-host -f` or `ud-host -f -h host` on a +server in order to display all host fingerprints or only the +fingerprints of a particular host in order to compare it with the +output of ssh on an external host. + ## Know when will my change take effect? Once a change is saved to LDAP, the actual change will take at least 5