4.8 Key and Cert

mtn cert selector certname [certval]

Create a new certificate with name certname, for all revisions matching selector (see Selectors).

If certval is provided, it is the value of the certificate. Otherwise the certificate value is read from stdin.

mtn dropkey keyid

Drop the public and/or private key. This command should be used with caution as changes are irreversible without a backup of the key(s) that were dropped.

mtn genkey keyid

This command generates an RSA public/private key pair, using a system random number generator, and stores it in your keystore under the key name keyid.keyhash. The key’s hash is printed out after the key has been created.

The private half of the key is stored in an encrypted form, so that anyone who can read your keystore cannot extract your private key and use it. You must provide a passphrase for your key when it is generated, which is used to determine the encryption key. In the future you will need to enter this passphrase again each time you sign a certificate, which happens every time you commit to your database. You can tell monotone to automatically use a certain passphrase for a given key using the get_passphrase(key_identity) (see get_passphrase), but this significantly increases the risk of a key compromise on your local computer. Be careful using this hook.

Another way to avoid entering the private key passphrase each time it is needed is to export it to ssh-agent; see mtn ssh_agent_export, mtn ssh_agent_add.

The public key is stored in the database; the public and private keys are stored in the keystore. This allows copying the database without copying the private key.

The location of the keystore is specified by --keydir; it defaults to the value stored in _MTN/options for commands executed in a workspace, or to the system default ($HOME/.monotone/keys on Unix and Cygwin, %APPDATA%/monotone/keys on native Win32).

mtn passphrase keyid

This command lets you change the passphrase of the private half of the key id.

mtn ssh_agent_add

This command will add your monotone keys to your current ssh-agent session. You will be asked for the passphrase for each of your monotone private keys and they will be added to the ssh-agent. Once this is done you should be able to type ssh-add -l and see your monotone key listed. When you subsequently use these keys through monotone it will use ssh-agent for signing without asking your for your passphrase.

On Windows native, monotone only supports the PuTTY ssh-agent implementation. On Windows Cygwin and Unix, any standard ssh-agent implementation can be used.

This command is mainly for use in a session script as monotone will automatically add your keys to ssh-agent on first use if it is available. For example the following two examples are equivalent:

$ mtn ssh_agent_add
enter passphrase for key ID [user@example.com]:
$ mtn ci -m"Changed foo to bar"
$ mtn push -k user@example.com

$ mtn ci -m"Changed foo to bar"
enter passphrase for key ID [user@example.com]:
$ mtn push -k user@example.com

In the second example, monotone automatically added the key to ssh-agent, making entering the passphrase not needed during the push.

mtn ssh_agent_export [filename]

This command will export your private key in a format that ssh-agent can read (PKCS8, PEM), to filename (defaults to standard output). You will be asked for your current key’s monotone password and a new password to encrypt the key with (the ssh passphrase). The key will be printed to stdout. Once you have put this key in a file simply add it to ssh-agent and you will only have to enter your key password once as ssh-agent will cache the key for you.

$ mtn ssh_agent_export ~/.ssh/id_monotone
enter passphrase for key ID [user@example.com] (1234abcd...):
enter new passphrase for key ID [user@example.com] (1234abcd...):
confirm passphrase for key ID [user@example.com] (1234abcd...):
$ chmod 600 ~/.ssh/id_monotone
$ ssh-agent /bin/bash
$ ssh-add ~/.ssh/id_monotone
Enter passphrase for /home/user/.ssh/id_monotone:
Identity added: /home/user/.ssh/id_monotone (/home/user/.ssh/id_monotone)
$ mtn ci -m"Changed foo to bar"
$ mtn push -k user@example.com

You can also use the --ssh-sign option to control whether ssh-agent will be used for signing. If set to yes, ssh-agent will be used to sign. If your key has not been added to ssh-agent monotone will fall back to its internal signing code and ask you for your password. If set to only, monotone will sign only with ssh-agent. If set to no, monotone will always use its internal signing code even if ssh-agent is running and has your monotone key loaded. If set to check, monotone will sign with both ssh-agent (if your key is loaded into it) and monotone’s internal signing code, then compare the results. check will be removed at some future time as it is meant only for testing and will not work with all signing algorithms.

mtn trusted id certname certval signers

This command lets you test your revision trust hook get_revision_cert_trust. You pass it a revision ID (see Selectors), a certificate name, a certificate value, and one or more key IDs or key names, and it will tell you whether, under your current settings, Monotone would trust a cert on that revision with that value signed by those keys.

The specified keys must exist either in your keystore or in the database.