GNOME Keyring Cryptoki Support

NOTE: This is a work in progress. Documentation here is incomplete, and will probably change drastically as time goes on -- Stef Walter <stef@memberwebs.com>

Goals

• Sharing the same key store between all GNOME applications that need to use certificates and/or keys, regardless of underlying crypto library.
• Using a single password, the user's GNOME Keyring master password to protect the user's keys.
• Storing key material in non-swappable memory, and confining it to a single process.
  • We can take precautions like flushing it from memory before hibernate.
• Storing of keys in a non-blackbox and simple format.

Architecture

• Communication between gnome-keyring-daemon and the module is done via unix sockets.
  • The protocol is private, and steps are taken to ensure this.
  • The socket name is: ${GNOME_KEYRING_SOCKET}.cryptoki
• Cryptoki sessions are each mapped to an open socket.
• Any Cryptoki function with a session handle argument is passed through to gnome-keyring-daemon for processing there.
• Any Cryptoki functions without a session handle argument are processed in the module.
• Only one function call active per session at any given time. This is according to PKCS#11

Module Architecture

• No use of external libraries. DBus would have been nice but causes problems with threading, among other things.
• Using pthread mutexes

gnome-keyring-daemon Architecture

• gnome-keyring-daemon handles each Cryptoki session (and socket) in its own thread.
• When storage needs to be read or written to, the session thread queues a message with the main gnome-keyring-daemon thread.
• The daemon cryptoki code is as self contained as possible, with very few entry points from the main gnome-keyring-daemon code.

Certificate/Key Storage

• Not: I'm of the opinion that the certificates/keys shouldn't be stored in the actual gnome-keyring file.
  • The current file format is very brittle.
  • Backwards compatibility, running multiple versions of GNOME in the same home directory...
  • Imagine your precious keys getting lost inside some random undocumented strange file format or DB.
  • There's already plenty of formats for Certificates/Keys.
• I'm thinking of putting each certificate/key in its own file in a directory.
  • This makes backups easy.
  • Deploying certificates by system administrators is easy.
  • The encrypt password on the key files would be setup to be the same as the gnome-keyring master password.
  • These key files would be re-encrypted whenever the user changes the gnome-keyring master password.
  • 'Non-exportable' certificates could be implemented by encrypting them with a random passwords, and storing that password within the normal gnome-keyring password file. This way they wouldn't be used on another computer even if copied out of that directory.

Index Storage

Need some form of index to hold mutable attributes of certificates and keys, as well as certain parts of keys that are stored encrypted on the disk. For example the user configurable label for a certificate or key, or the public part of a private key (so we don't have to decrypt it, possibly prompting the user, in order to use the public part).

• The 'index' files should ideally be kept per certificate or key file, this allows them to move to other media, etc..
• I looked at Berkeley DB, and although it could fit there are too many problems and unknowns for it.
  • For multi-process access (which we need) you have to setup an 'environment' which uses an entire directory of files, instead of just a single file.
  • If the process exits uncleanly we have to 'recover'.

  • Different file formats between different versions. We need both backward and forward compatibility, because the user may use the key store on different computers.

• Decided to use desktop type files, ie: GKeyFile

Closed Issues

• Have to support threads in module. PKCS#11 mandates support.
• Have to use threads in gnome-keyring-daemon. Many operations are too long lived.
• Can't use DBus. Too much danger for threading conflicts with DBus use elsewhere in the application. Also very hard to secure memory usage (ie: non-pageable memory).
• Can't use Glib mutexes and atomic functions in module. Too much danger for threading conflicts with Glib use elsewhere in application.

Code

Code is in gnome-keyring since 2.22 release.

Status

• A proper GNOME SSH agent based on this key support. (Done)
• PKCS#11 module and marshalling protocol. (Done)
• 'Just works' loading of most any key/certificate format. (Done)
• RSA and DSA crypto operations. (Done)
• Certificate trust and key usage.
• Interoperability work with NSS, GnuTLS, OpenSSL.
• RSA and DSA key generation, management of storage.