Using

Monkeysign comes in two different interfaces: a commandline interface named monkeysign and a graphical interface named monkeyscan.

Monkeysign creates a temporary keyring to sign keys, and then encrypts and sends the signature by email to the owner of the key. This makes possible to verify that the holder of the private key (used to decrypt the signature) has also access to the mailbox mentioned in the key.

Note

Make sure you have your email credentials in hand and read the Sending signed key material section before starting, as Monkeysign does not know, by default, how to send email.

Tip

If you have problems using Monkeysign, please do report issues and bugs about it, it’s a great way of contributing! We also welcome documentation, translation and patches, see Contributing for more information.

Monkeysign

The commandline interface should provide you with a complete help file when called with --help:

monkeysign --help

For example, to sign the Monkeysign test key:

monkeysign 3F94 240C 918E 6359 0B04  152E 86E4 E70A 96F4 7C6A

This will fetch the key from your keyring (or a keyserver) and sign it in a temporary keyring, then encrypt the signature and send it in an email to the owner of the key. Emails can be sent in different ways, documented in Sending signed key material.

If the wrong secret key is chosen to sign the key, you can override it with the --user option.

<div class=”caution”> It is important to use <span class=”application”>Monkeysign</span> with the fingerprint, <em>not with the key id</em>, specially when using it through the Tor network, as keyids can be duplicated easily, unlike fingerprints. </div>

Monkeyscan

The graphical interface (GUI) should be self-explanatory, it should be in your regular application menus, or you can call start it form the commandline with:

monkeyscan

The GUI will show you a bar code representing the fingerprint of what Monkeysign thinks is your primary key. You can change that in the Identity menu, or by customizing the default-key parameter in your gpg.conf file.

On the left side, you should see the output of your camera. You can change cameras (if you have more than one) in the Video device menu, where you can also turn off the camera altogether.

To exchange fingerprints, you should point the camera at another user’s bar code. Monkeysign will detect that user’s key fingerprint, fetch the key over the network from keyservers, then ask you for confirmation before signing and sending the email, just like the command line interface. See Sending signed key material for more information about how email is sent in Monkeysign in general.

There is a very crude preferences window available in the Edit menu. There is work underway to improve it (see 0xACAB issue #41), but it should allow you to create a configuration file with your personal settings. See Configuration files for more information about this as well.

Sending signed key material

Monkeysign will attempt to send the signed key by email, unless the --no-mail argument is specified. In this case, the encrypted key material is shown on the terminal and should be copy-pasted in the medium of your choice.

Monkeysign, by default, assumes you have a local MTA installed, which is often not the case on laptop and desktop computers. To properly send email, you need to tell Monkeysign how to use your MUA. For this, you can use the --mua option. For example, you can use Thunderbird to send email with the following configuration:

monkeysign --mua "thunderbird -compose to=%(to)s,subject=%(subject)s,body=%(body)s,attachment=%(attach)s" [...]

A more general case is to use the xdg-email command which automatically uses your configured email client correctly. This is the default when the --mua flag is used without argument:

monkeysign --mua [...]

Your default mail client can be modified in your desktop environment control panel, or with the xdg-mime command, for example this will set Thunderbird as your default email client:

xdg-mime default thunderbird.desktop x-scheme-handler/mailto

Finally, note that you need to confirm when you are finished writing the actual email. This is because we cannot tell when the email is sent, because a lot of software (especially Thunderbird) return before the email is sent, see Debian BTS #677430 for more information about this issue.

By default, Monkeysign sends email using the command defined in the --mta option, which you can also modify. Essentially, the difference between --mta and --mua is that the complete message is piped through the MTA command whereas it is passed as an argument on the commandline for MUA commands.

Also note that when a MUA is used, only the key material is encrypted: the body of the email is sent in the clear. This is because Monkeysign cannot control how the attachment layout in the MUA in a standard way. Furthermore, it may be more difficult for the end-user to import the key, as the recipient’s MUA may not know how to both decrypt and import the key at the same time. The MTA method doesn’t have this problem because of MIME encapsulation. See also 0xACAB issue #7 for a broader technical discussion about the --mua implementation.

Note that you can also send email using your provider’s SMTP server directly, turning Monkeysign into a MUA itself. For example:

monkeysign --smtp=mail.example.com:587 --smtpuser=john [fingerprint of OpenPGP key to sign]

In the above, Monkeysign will attempt to connect to the mail.example.com SMTP server over the submission port (587), attempt to upgrade the connection securely (using STARTTLS) and use the john username. Password will be prompted securely.

Note

To use a raw TLS connection, you can also use the --tls flag.

Configuration files

Monkeysign will read /etc/monkeysign.conf and ~/.config/monkeysign.conf (in that order) for configuration options. Each option can be specified on its own line. Lines starting with the pound sign (#) are ignored as comments. A configuration file can be generated with the --save option, or through the preferences window in the GUI. Here is a sample configuration file:

# use my SMTP server to send email
smtpserver=smtp.example.com:587
# this is my username, password is securely prompted interactively
smtpuser=john
# be more verbose
verbose

As you can see, flags like --verbose are simply specified on their own, while options with arguments need to be seperated with an equal (=) sign.