For Developers‎ > ‎Design Documents‎ > ‎Network Stack‎ > ‎

SSL client authentication


SSL client authentication is supported for Windows only on all three release channels (Stable channel release or later, Beta channel release or later, or Dev channel release or later). Please help us by testing it and filing bug reports on any issues you find.

jsorianopastor contributed a patch for basic SSL client authentication support on Linux. The patch has been checked in, but requires using the --auto-ssl-client-auth command-line option until the certificate selection UI is implemented.

Certificate enrollment will be implemented later. Until then, users need to use another browser or a special program for certificate enrollment. For example, Windows users can use Internet Explorer to enroll for a certificate, and this certificate will be available to Chromium automatically because Chromium uses the Windows system certificate store.

Bug Reports

Issue 318 is the primary bug report tracking the work on SSL client authentication. Issue 16830 tracks the backend of the Linux implementation, issue 25241 tracks the UI of the Linux implementation, and issue 16831 tracks the Mac implementation.

Issue 148 covers certificate enrollment. We decided to implement the HTML <keygen> tag first because WebKit already supports it. Initially we will only implement what's specified in draft HTML 5.

Design Document

We will use the system certificate store. On the Mac, this is the Keychain. On Linux, this is the shared NSS databases in the ~/.pki/nssdb directory, following the proposal of the NSS team.

UI Issues

  1. We need a dialog to tell the user that the server is requesting a client certificate, and to let the user select a certificate if he has multiple certificates that meet the server's criteria. I suggest we use the Windows built-in certificate selection dialog.
  2. IE pops up a certificate selection dialog even when the user has no personal certificates. This dialog with no certificates is confusing. We should avoid that.
  3. Firefox has an option that allows the browser to send a suitable certificate to a server automatically. This feature is now considered a privacy issue (see Mozilla bug 295922). I suggest that we not implement this option. To improve usability, I suggest that we remember temporarily the certificate chosen by the user so that the user doesn't need to select a certificate again when he goes back to the same server for the rest of the browsing session.  However, when the browser restarts, the user will need to select a certificate again.

Privacy Issues

  1. On the first visit to a server that requests a client certificate, the user must be notified and approve the sending of a client certificate.
  2. The browser should verify the server's certificate before sending the client certificate to the server.  Due to a limitation of the Windows SSL library (the Schannel), this is impossible, and we will need to go out of our way to work around the limitation. See issue 13934. Details: the Schannel doesn't give us the server's certificate until the handshake is complete. By that time, we will have sent the client certificate to the server. To work around this limitation, we will need to either parse the server's SSL packets ourselves so we can get the server's certificate sooner, or we will need to perform two handshakes -- the first handshake is for getting the server's certificate only, and we send the client certificate in the second handshake.

Test Plan

New unit tests for SSL client authentication should cover the following variables.
  1. Initial handshake vs. renegotiation: SSL client authentication may be performed in either the initial handshake or a renegotiation.
  2. Acceptable certificate authorities: empty (which means any CA is acceptable), one CA, and multiple CAs.
  3. Requested certificate types (optional): we support rsa_sign only. Discover how Chrome reacts if other certificate types are requested.
  4. Acceptable client certificates: none, one, and multiple.
  5. Expired client certificates: should not be used for SSL client authentication (a design decision of Chrome).
  6. SSL session resumption: client certificate should not be requested again because it is part of the session state.
  7. SSL client authentication certificate cache:
    • The client certificate selected by the client certificate selection callback should be added to the cache.
    • The cache should short-circuit the client certificate selection callback if the same server requests a client certificate again during the same browsing session.
    • Bad client certificate should be removed from the cache.
  8. Error conditions
    • No private key for the chosen client certificate.
    • User denied permission to use private key (Windows only). Not sure if this can be tested without user intervention.
    • Wrong password for private key (Linux/NSS only, not implemented yet).