Pinned Certificate Widget

Underlying Concepts

Pinning a certificate is the concept of assigning a certificate explicitly to a TLS connection. This overrides the usual building of a PKI certificate verification path. Pinned certificates can be stored using the gcr library, and are supported by glib-networking's TLS database code.

In general we want to *avoid popping up dialogs saying the certificate is untrusted* or could not be verified. These dialogs have little or no context in which to make the decision. In addition an active attack looks exactly the same as a configuration problem to the user. Could go on and on, but suffice it to say these dialogs are bad.

Most software should treat a certificate failing to verify as a "fatal" connection error, and not throw up a dialog asking the user whether to continue.

In the cases where an override of this is necessary, then the program can make an advanced setting available in its account settings dialog to set a "pinned certificate". This pinned certificate is associated with the account, and is not installed as a general trusted CA or anything like that.

Use Cases

XMPP Server

  • Steve sets up an XMPP account using the empathy account settings for a custom XMPP server.
  • The corporate XMPP server uses a certificate signed by a self-signed CA not in the standard trusted list.
  • Steve clicks on "Advanced" and inspects, and approves the unusual certificate in this widget.
  • Steve doesn't get a random certificate confirmation dialog later when choosing "Available" as his status.

Proxy usage

  • Manuels machine is behind a corporate proxy.
  • The corporate proxy uses a certificate signed by a self-signed CA not in the standard trusted list.
  • Manuel tries to use an application that needs to access the internet (Ubuntu One).
  • Manuel clicks on "Advanced" inspects the proxy settings and approves the proxy certificate.
  • No random out of context confirmation dialogs are shown.

This use case could be applied to the case in witch the user wants to set up the system proxy settings via the gnome-control-center.


  • This is an advanced feature.
  • Corporate admin should still install custom CA's.
  • Pinned certificates are a work around for coorporate CA's not installed, but it's not the main use case.
  • This is a replacement for the random popup dialogs asking for approval of a non-verifiable or invalid certificate.

Mock up

Idea for widget. Default state:

Verify server's identity          [Change...]

If the user clicks 'Change' then a dialog pops up which might look like:

TODO: Work this out.

This is what the widget looks like once a certificate is approved.

Verify server's identity matches this certificate [Change...]

=====  Certificate name
|  o|  Fingerprint: AAAA BBBB CCCC DDDD
=====  Issued on: 2012-12-32

This is what the widget looks like if the user chooses not to verify.

Don't verify server's identity    [Change...]

Projects/Gcr/Widgets/PinnedCertificate (last edited 2013-12-02 20:33:42 by WilliamJonMcCann)