Certificate Selection

Common certificate/key selection widget — allows someone to select an X.509 SSL certificate or key from either a file or a a PKCS#11 token such as gnome-keyring or USB crypto devices.

This is part of a Google Summer of Code project for 2016, being developed at https://github.com/tyagi-prashant/gcr (run ,/gcr-certificate-chooser-test to see it.)




  • Allow the user to pick a single or certificate or key
  • Consistent with GtkFileChooser UI when choosing files

  • Allow selection of objects from PKCS#11 tokens
  • Allow passphrase/PIN entry
  • Provide good defaults
  • Provide useful and consistent previews
  • Compatible with touch


  • Selection of multiple certificates
  • Importing certificates from files into PKCS#11


  • Focused on picking

Use Cases

The primary use case is from within a dialog for selecting a personal certificate + key, as discussed in bug 679860. It would be invoked twice there; once for choosing the user's certificate, and then a second time for choosing the corresponding key if it isn't in the same place as the cert. This would be used for:

  • VPN/802.1x/etc client certificate (NetworkManager)

  • S/MIME certificate (Evolution, etc.)
  • Other authentication (gtk-vnc, vinagre, etc.)


  • Frequent filers
  • Spring cleaners
  • No filers


  • How do we prompt for passwords/PINs when required?
  • How do we show a 'preview' of the selected certificate/key?
  • How does the user select file vs. PKCS#11 for browsing?
  • How do we handle filtering / supported formats?

Tentative Design

Files vs PKCS#11 "Locations"

Red Hat performed a User study at Devconf 2016, using mockups similar to this one: https://bug679860.bugzilla-attachments.gnome.org/attachment.cgi?id=322663

It is basically a file chooser, but the PKCS#11 tokens available in the system are visible as additional 'Locations', which seems intuitive for the user.

This is, unfortunately, non-trivial to implement with the existing GtkFileChooser implementations — because when we choose a PKCS#11 Location, we don't have files in it; we need a browser which looks more like the one shown in the Seahorse screenshot further down.

There is a GtkStack within the file chooser widget, and theoretically it could be possible to allow a new child of the browse_files_stack to be inserted to handle specific URI types or specific locations, vaguely parallel to the way the preview widget is already handled. You could possibly even disguise this feature addition as a "cleanup" of the existing special-cases like the "Other locations" handling. But there is understandable resistance to "opening up" the internal details for public consumption.

For now, our mockup (as shown below) has an explicit choice of 'Choose from file' vs. 'Choose from PKCS#11 token' — which is extremely suboptimal for the user especially if they have no idea what 'PKCS#11' means, but it allows us to make progress with the rest of the implementation, for now.

PIN/passphrase handling

The other interesting aspect of the design is requesting a PIN or passphrase.

For files, it's relatively simple — when a file is selected, we can even use a preview window in the file chooser to ask for its password. Our current mockup does this, as shown here:


For PKCS#11 tokens the PIN handling is slightly more complicated. Sometimes you can't even browse the objects within a token until you unlock it. Or you can browse, but some objects just aren't visible until you unlock it.

Seahorse shows this with a subtle open/closed padlock against the token in its 'location' pane on the left-hand side. We do not believe this is sufficient — when a token is locked, we probably need something in the browsed list of items, suggesting that the user might unlock the token if they want to see more.

Prior Art

There is no prior art which completely addresses this need. In various places, NetworkManager configuration allows the individual selection of files for certificate and private key, but PKCS#11 objects must be handled on the command line with nmcli or by manually editing config files.

NetworkManager dialogs

nm-8021x-cert.png nm-openconnect-cert.png nm-openvpn-cert.png

Chrome on Windows requiring client auth cert


Seahorse browsing PKCS#11 tokens




See Also

Design/OS/CertSelection (last edited 2016-06-09 09:24:28 by dwmw2)