LDAP user guide¶
Tutorial¶
Our LDAP configuration is rather exotic. You will typically use the web interface and the OpenPGP-enabled email interface. This documentation aims at getting you familiar with the basics.
Tip
If you're looking for advanced documentation on how to operate this service, head over to the service documentation.
Getting to know LDAP¶
You should have received an email like this when your LDAP account was created:
Subject: New ud-ldap account for <your name here>
That includes information about how to configure email forwarding and SSH keys. You should follow those steps to configure your SSH key to get SSH access to servers (see ssh-jump-host).
How to change my email forward?¶
If you use Thunderbird and use it to manage your OpenPGP key, compose a new
plain text (not HTML) message to changes@db.torproject.org, enter any subject
line and write this in the message body:
emailForward: user@example.com
Before sending the email, open the OpenPGP drop-down menu at the top of the
compose window and click Digitally Sign.
If you use GnuPG, send an (inline!) signed OpenPGP email to
changes@db.torproject.org to change your email forward.
A command like this, in a UNIX shell, would do it:
echo "emailForward: user@example.com" | gpg --armor --sign
Then copy-paste that in your email client, making sure to avoid double-signing the email and sending in clear text (instead of HTML).
The email forward can also be changed in the web interface.
Password reset¶
If you have lost or forgotten your LDAP password or if you are are newly hired by TPI (congratulations!) and don't know your password yet, you can have it reset by sending a PGP signed message to the mail gateway.
The email should:
- be sent to
chpasswd@db.torproject.org - be composed in plain text (not HTML)
- be PGP signed by your key
- have exactly (and just) this text as the message body:
Please change my Tor password
If you use Thunderbird and use it to manage your OpenPGP key, compose a new message in plain text (not HTML). You can configure sending emails in plaintext in your account settings, or if your new messages are usually composed in HTML you can hold the Shift key while clicking on the "+ New Message" button. Enter any subject line and write the message body described above.
Before sending the email, open the OpenPGP drop-down menu at the top of the
compose window and click Digitally Sign.
Or, you can use GnuPG directly and then send an (inline!) email with your client of choice. A command like the following, in a UNIX shell, will create the signed text that you can copy-paste in your email. Make sure to avoid double-signing the email and sending it in clear text (instead of HTML):
echo "Please change my Tor password" | gpg --armor --sign
However you sent your signed email, the daemon will then respond with a new randomized password encrypted with your key. You can then use the update form with your new password to change your it to a strong password, in the "Change password" field, that you can remember or (preferably) a stronger password (longer and more random) stored in your password manager. Note: on that "update form" login page the button you should use to login is, unintuitively, labeled "Update my info"
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, which includes instructions on SSH public key authentication, for example.
Note: If you get an answer saying Error: Unable to check the signature or the
signature was invalid, it may be the case that you hit a bug and will need
help from a sysadmin to reset your password or change other settings (see
tpo/tpa/team#42514). In that case, please create an issue in tpo/tpa/team> to
get help.
How do I update my OpenPGP key?¶
LDAP requires an OpenPGP key fingerprint in its records and uses that trust anchor to review changes like resetting your password or uploading an SSH key.
You can't, unfortunately, update the OpenPGP key yourself. Setting the key should have been done as part of your on-boarding. If it has not been done or you need to perform changes on the key, you should file an issue with TPA, detailing what change you want. Include a copy of the public key certificate.
To check whether your fingerprint is already stored in LDAP, search for your database entry in https://db.torproject.org/search.cgi and check the "PGP/GPG fingerprint" field.
We acknowledge this workflow is far from ideal, see tpo/tpa/team#40129 and tpo/tpa/team#29671 for further discussion and future work.
How-to¶
Set a sudo password¶
See the sudo password user configuration.
Operate the mail gateway¶
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.
Note: If you get an answer saying Error: Unable to check the signature or the
signature was invalid, it may be the case that you hit a bug and will need
help from a sysadmin to reset your password or change other settings (see
tpo/tpa/team#42514). In that case, please create an issue in tpo/tpa/team> to
get help.
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: valuewill 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, usedelinstead (see below). The values that can be changed are:loginShell,emailForward,ircNick,jabberJID,labledURI, andVoIP
- del field: A line of the form
del fieldwill completely remove all occurrences of a field. Useful e.g. to unset your vacation status.
- SSH keys changes, see 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.torproject.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¶
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 keys verification¶
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.
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 minutes and at most 15 minutes to propagate to the relevant host. See the configuration file distribution section for more details on why it is so.