Monkeysphere FAQ

  1. ssh related questions
    1. Q. What is the difference between the different monkeysphere commands?
    2. Q. Does setting up Monkeysphere for SSH touch anything in my current setup, like ssh host files, etc? I'm concerned about it being a reversible process.
    3. Q. Is there any way to have sshd look at both authorized_keys locations?
    4. Q. What if some users want to add regular ssh public keys, in the traditional way? How does Monkeysphere deal with that?
    5. Q. What do I put in .monkeysphere/authorized_user_ids?
    6. Q. Is there a way to get my ssh public key out of my OpenPGP key, so I can provide it to someone who isn't using the Monkeysphere?
    7. Q. What if somebody puts a key with the UID to the key servers which might actually be another persons/companies domain? Say ssh://google.com
    8. Q. Why do I sometimes get a warning (such as the one at the bottom of the doc page about signing service keys) when connecting via ssh, and sometimes Monkeysphere just goes ahead and adds the certificate as a valid host key to .ssh/known_hosts without a warning?
    9. Q. Doesn't the SSH specification include the possibiliy of OpenPGP certificates on the wire?
    10. Q. Why does the ssh proxycommand require a separate program (socat)?
  2. general questions
    1. Q. Have you thought about widening the scope of your project?
    2. Q. What exactly does the "monkeysphere-host revoke-key KEYID|FILE" do?
    3. Q. What does "monkeysphere-host add-revoker" do?
    4. Q. Why would I use add-revoker on myself when I have the private key
    5. Q. Is there another way to invalidate the host key if I cannot revoke it?
    6. Q. Should I create a revocation certificate?
    7. Q. Do you plan on implementing server-side HTTPS client authentication?
    8. Q. X.509 PKI actually offers things like key transitions, revocations and expirations, why can't you just use X.509 which seems to be pretty widely adopted?
    9. Q. When did you start this project?
    10. Q. I am changing the hostname on my server, how should I handle the Monkeysphere parts?
    11. Q. What does the '=' in gpg --search '=ssh://server.example.net' mean exactly, I saw it on your getting-started-admin page.
    12. Q. How do I "verify" the identity of a server, I want to sign my host key, but I'm used to doing this with people, not servers.
    13. Q. How do I debug the Monkeysphere?
    14. Q. Should I set trust on my host key?
    15. Q. Why use an OpenPGP authentication-capable subkey instead of just marking my OpenPGP primary key to be authentication-capable?
  3. similar and related projects
    1. Q. What do you think about firegpg?
    2. Q. What do you think about enigform?
  4. keyserver questions
    1. Q. Do you have a keyserver you can recommend?
    2. Q. How do I get encrypted transport to a keyserver?
    3. Q. Why would you want to have encrypted queries to keyservers? Isn't the data that they hold essentially public anyways?
  5. OpenPGP questions
    1. Q. How do you move an lsignature from one place to another?
    2. Q. How do I find all the lsigned ids that I have?

ssh related questions

Q. What is the difference between the different monkeysphere commands?

monkeysphere is the interface to the user functions for monkeysphere SSH; monkeysphere-host handles managing OpenPGP keys on the host (importing keys into the OpenPGP WoT, publishing keys, etc.); monkeysphere-authentication handles authentication of users to the local system via SSH (choosing your trusted identity certifiers, updating authorized_keys, etc.)

Q. Does setting up Monkeysphere for SSH touch anything in my current setup, like ssh host files, etc? I'm concerned about it being a reversible process.

In order for users to be able to identify your host through the WoT, you use monkeysphere-host import-key ... to read the ssh host key and turn it into an OpenPGP certificate. However, it does not modify the original ssh host key in any way. All it does is take the raw RSA key and import it into the OpenPGP web of trust, binding it to a user-ID associated with the host. For a host to identify users through the WoT using monkeysphere-authentication, you need to modify /etc/ssh/sshd_config so that sshd knows to look at /var/lib/monkeysphere/authorized_keys/%u. This is the only change needed, and is easily reversible.

Q. Is there any way to have sshd look at both authorized_keys locations?

OpenSSH 5.9 and later releases support multiple paths for the AuthorizedKeysFile directive. However, because it is designed to be compatible with older versions of OpenSSH, monkeysphere-authentication automatically adds in all keys specified in %h/.ssh/authorized_keys by default when doing an update (see below).

Q. What if some users want to add regular ssh public keys, in the traditional way? How does Monkeysphere deal with that?

Some users do expect to be able to add raw public keys, and do not want their ssh public key bound to their identity in the WoT. By default, monkeysphere-authentication actually appends ~/.ssh/authorized_keys to the list of keys generated via the WoT (although this is configurable, if you do not want users to be able to do this). This means that you can run a Monkeysphere setup, and you can use your standard public key authentication setup along side each other. There is one caveat to this: changes to ~/.ssh/authorized_keys aren't immediately effective, because they only get slurped into the generated keys when the WoT re-generation is run (via a regular run of "monkeysphere-authentication update-users").

Q. What do I put in .monkeysphere/authorized_user_ids?

You need to put valid OpenPGP UIDs into this file. Don't put key-ids, the point is to identify you by your human name, you need to put the exact UID that appears on your key, one per line.

Q. Is there a way to get my ssh public key out of my OpenPGP key, so I can provide it to someone who isn't using the Monkeysphere?

You should get them to run the Monkeysphere! Ok, one way to do this is to load your Monkeysphere key into your ssh-agent with monkeysphere subkey-to-ssh-agent, and then extract the public key in OpenSSH format with ssh-add -L.

If you're trying to communicate your key to someone you already know through the OpenPGP web of trust, and they have Monkeysphere installed, just tell them to run monkeysphere keys-for-userid $USERID (where $USERID is, for example, Maria Gonzalez <maria@example.org>).

If the other person doesn't have the Monkeysphere at all, but has the gnupg-agent installed (from gnupg2 2.0.9-3 or later), you can also tell them to pull your key from the keyservers, verify your identity, and then convert it to a ssh public key. If $KEYID is your key ID, the steps for the other person would be:

gpg --recv-key $KEYID
gpg --list-options show-uid-validity --check-sigs $KEYID
gpgkey2ssh $KEYID >> .ssh/authorized_keys

Q. What if somebody puts a key with the UID to the key servers which might actually be another persons/companies domain? Say ssh://google.com

The signatures on this hypothetical key, and their certifications keep this from being a problem. You can go create an X.509 certificate that claims to have a CN=www.google.com, and sign it with your own personal CA. The Monkeysphere deliberately relies on your explicitly-stated trust paths to determine which of the keys out there are valid. The google.com people shouldn't be blindly trusting any certifications out there.

Q. Why do I sometimes get a warning (such as the one at the bottom of the doc page about signing service keys) when connecting via ssh, and sometimes Monkeysphere just goes ahead and adds the certificate as a valid host key to .ssh/known_hosts without a warning?

The warning is what is called the 'marginal use case' or 'marginal UI'. You will only see this when the host you are connecting to does not have fully calculated validity for that host key, based on your stated trust configurations. The host key in this situation only has 'marginal' trust. You do not see this warning if the host key has 'full' trust. These settings are done on the OpenPGP keys associated with the server key, and the keys of the people who have certified the host key. If you signed a host's certificate with your own key, then it will have full calculated validity, because your own key has 'ultimate ownertrust', which in this case is indistinguishable from "full" ownertrust.

Q. Doesn't the SSH specification include the possibiliy of OpenPGP certificates on the wire?

It does, but the free implementations don't seem to support it. The Monkeysphere approach is to handle the verification out-of-band, instead of forcing a change on the wire. This makes things easier to deploy and has been helpful because it lets us concentrate on the bigger questions of trust and verification, instead of getting mired in patching source and wire protocol issues.

Q. Why does the ssh proxycommand require a separate program (socat)?

The proxycommand needs to be able to make the TCP connection, and although openssh is capable of doing that, we are constrained by the fact that openssh doesn't have a hook capability that would let us adjust the known_hosts file at connection, nor does it expose to us the possibility of having a hook that just verifies a key. For this reason, the Monkeysphere ProxyCommand needs to be able to make the TCP connection to the host itself after verifying the key. Newer versions of ssh don't require us to use external programs, so this may change in the future.

general questions

Q. Have you thought about widening the scope of your project?

Yes, indeed. On a more generalized scale, the CA architecture is obviously flawed, it isn't just us monkeys who think this. A number of other people also complain about the problem of centralized authority and wish there was something else. We would like to think that we are creating a rallying point around this issue. We've learned significantly handling things via the monkeysphere model. We've started with ssh and https, but we definitely have hopes to extend this reach. The project has proceeded one step at a time starting with openssh and then we broadened the project to usurp the dominant X.509 PKI for TLS/HTTPS authentication.

Q. What exactly does the "monkeysphere-host revoke-key KEYID|FILE" do?

It is similar to an ordinary revocation certificate for a standard GPG key

Q. What does "monkeysphere-host add-revoker" do?

add-revoker can be used to enable users (including yourself) to revoke the host key, if you trust them to do so. If your host were to become compromised, and you were to completely lose control or access to its host key (e.g. if your machine was physically stolen), because you would not have access to the host key in order to issue a revocation certificate, and had stored a revocation certificate offsite... in this situation, whoever had stolen the machine could use the host key as issued. If you've specified "person X is allowed to revoke the host key" already, then in the event of such a loss, X can issue a revocation certificate on the host's behalf. One of the benefits of using add-revoker is that you can tailor your revocation certificate to the actual circumstances.

Q. Why would I use add-revoker on myself when I have the private key

Because you might not have access to the host's secret key in the future, many of the situations where you lose access to the host's secret key (e.g. hardware theft or failure) are also situations where you want to revoke the host key.

Q. Is there another way to invalidate the host key if I cannot revoke it?

You can get everyone who had initially (correctly) certified the host key to revoke their own certifications.

Q. Should I create a revocation certificate?

Yes! We highly encourage you create and store one off-site! A pre-generated revocation certificate is by necessity vague about why the revocation certificate is being issued. So if you do need to revoke the key, and still have access to the secret key for the host, it is better to use add-revoker to explicitly specify the revocation circumstance, rather than use the generic revocation certificate. If you do not have access to the host's secret key, then you should use the generic revocation certificate.

Q. Do you plan on implementing server-side HTTPS client authentication?

Currently, only client-side authentication of remote servers is available for HTTPS, with a plan for eventual server-side authentication of clients. Monkeysphere currently supports authenticating both client and server in OpenSSH communications.

Q. X.509 PKI actually offers things like key transitions, revocations and expirations, why can't you just use X.509 which seems to be pretty widely adopted?

While it is true that PKI based around X.509 does offer these properties, it does so in an unsatisfactory way, via CRLs for example, which are rarely used in practice. See more on the rationale for monkeysphere

Q. When did you start this project?

We started discussions sometime in 2008, and initial code came soon after that. We didn't feel like anything was mature enough to put out there until March of 2009.

Q. I am changing the hostname on my server, how should I handle the Monkeysphere parts?

You can use monkeysphere-host revoke-servicename, and then add-servicename

Q. What does the '=' in gpg --search '=ssh://server.example.net' mean exactly, I saw it on your getting-started-admin page.

'=' is a keyserver query prefix meaning "do a literal, exact match", you can find more in gpg(1), if you search for "By exact match", in the "HOW TO SPECIFY A USER ID" section

Q. How do I "verify" the identity of a server, I want to sign my host key, but I'm used to doing this with people, not servers.

Have a look at our documentation on signing service keys for a discussion about this.

Q. How do I debug the Monkeysphere?

You can change the debug level by passing an environment variable to the command you are working on, e.g. MONKEYSPHERE_LOG_LEVEL=debug monkeysphere update-known_hosts. You can also edit your own personal ~/.monkeysphere/monkeysphere.conf to change the debug level, or the system-wide configurations in /etc/monkeysphere.

Q. Should I set trust on my host key?

You probably shouldn't be "trusting" any host key ever. "Trust" in this context indicates that you expect the host key to make reasonable certifications, but host are not people, and should therefore not be making OpenPGP certifications (ie. they don't sign other keys).

Q. Why use an OpenPGP authentication-capable subkey instead of just marking my OpenPGP primary key to be authentication-capable?

There are many reasons. Most importantly for the Monkeysphere, gpg refuses to emit the secret key material for a primary key in cleartext form, but it is willing to emit a subkey in cleartext, provided you give it the right password and tickle it with the right options. monkeysphere subkey-to-ssh-agent knows how to do this (prompting the user for the password), and then can transform this into an OpenSSH-formatted key, which can then be handed to the agent. So if you were to use your primary key, you would have to find a way to make it usable by ssh, because we do not have a way to have direct access to the primary key. Another good reason to create a new authentication-capable subkey instead of marking your primary key authentication-capable is just to avoid tampering with your primary key. Also, using a subkey makes it easier to put your primary key (the most sensitive bit of an OpenPGP key) in offline storage, brought out only for special uses (like adding a subkey, or following up on a keysigning). If you decide that you'd prefer to rotate your ssh key on a regular basis (because it's in heavy use, because you don't trust the machines you are using very much, etc), you can do that much easier with a subkey. When you did this rotation, you would just create a new subkey, mark it as authentication-capable, publish it to the public keyservers, and then revoke the subkey binding signature for the old one.

similar and related projects

Q. What do you think about firegpg?

FireGPG may likely be an important componant to our overall goals. However, we are currently not convinced it is safe, and like to keep scary browsers away from our private keyrings. In the past (firegpg 0.5) did some very unpleasant things, like writing, in clear text, your gpg password to a file on the disk, and also writing the decrypted text to a file on the disk as well. These have been fixed in newer versions. We don't ascribe any fault to the firegpg developers, this problem is not trivial to resolve (primarily because Mozilla, by default, doesn't have an easy way to talk to a process on stdio). We hope that the firegpg folks adopt more caution in the future.

Q. What do you think about enigform?

It's also writing the user's passphrase to a file :(

keyserver questions

Q. Do you have a keyserver you can recommend?

The Monkeysphere developers currently recommend the SKS pool hkp://pool.sks-keyservers.net. The SKS pool isn't perfect: there is currently no encrypted transport between SKS servers, they don't yet authenticate the gossip peers or integrity check the data streams, and they sadly chew up a lot of ram in the face of connections with an AWOL server. However, in our experience of trying other keyservers, SKS so far is the best and it has good momentum behind it. Right now it doesn't have gnutls bindings, but if you know ocaml, we'd love to talk to you so that SKS (which is written in ocaml) can use gnutls for OpenPGP certificates for TLS authentication, which would be a nice thing to have.

Q. How do I get encrypted transport to a keyserver?

Encrypted keyserver communication is now available with the "hkps" (hkp-over-TLS) keyserver protocol, supported in gnupg since 1.4.10. To use hkps, you must specify a CA certificate for use in authentication, ie: gpg --keyserver-options ca-cert-file=/tmp/mfpl.crt --keyserver hkps://keys.mayfirst.org ...

Of course using encrypted keyserver communication requires a keyserver that knows how to speak hkps. The Monkeysphere project runs a keyserver, as part of the SKS gossip pool, that provides this transport: hkps://keys.mayfirst.org. As far as we know, this is the only keyserver out there that supports encrypted communication.

In addition, this project being what it is, there is now also a Monkeysphere-enabled hkps ("hkpms") module provided with the Monkeysphere validation agent package (msva-perl in Debian). This uses the users monkeysphere validation agent, if running, to confirm the identify of the keyserver. The Monkeysphere developers have signed the host key of keys.mayfirst.org¸ so if you have a trust path to the Monkeysphere developers you can try using hkpms://keys.mayfirst.org.

Q. Why would you want to have encrypted queries to keyservers? Isn't the data that they hold essentially public anyways?

The point is to stop the leakage of key query information that could otherwise tell you interesting data about someone. we'd like to find ways to provide encrypted transport to the keyservers, and get the other encrypted keyservers (and the clients, such as gpg) to provide this missing feature.

OpenPGP questions

Q. How do you move an lsignature from one place to another?

On the side that has the lsign do this: gpg --export-options export-local-sigs --export $gpgid

On the side that is going to import it, do this: gpg --import-options import-local --import

Q. How do I find all the lsigned ids that I have?

gpg --list-sigs --with-colons --fixed-list-mode |cut -d: -f1,5,11 |awk -F: '/^pub/{PUB=$2} /^sig:.*l$/{print PUB ":" $2 ":" $3}'|sort -u

will give you something like this:

093AC8BA4C2028E9:F67E2A5D1CG2361C:10l

The first field is the keyid that was lsigned by the second, the last field is the signature type, as referenced in RFC 4880, section 5.2.1, where the 'l' means local.