Wire up SSL client authentication for OpenSSL/Android through the net/ stack

net/base/openssl_key_store.h

+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef NET_BASE_OPENSSL_KEY_STORE_H
+#define NET_BASE_OPENSSL_KEY_STORE_H
+
+#include "net/base/net_export.h"
+
+// Avoid including <openssl/evp.h> here.
+typedef struct evp_pkey_st EVP_PKEY;
+
+namespace net {
+
+class X509Certificate;
+
+// Tell the network stack to use a specific OpenSSL private key 'object'
+// to implement signing during a SSL handshake that requires client
+// authentication. Can be called from any thread.
+//
+// Typically, SSL connection handling with client authentication works
+// in several steps:
+//
+//   1/ SSLClientSocket::Connect() is called, and returns with an error
+//      (ERR_SSL_CLIENT_AUTH_CERT_NEEDED) to indicate that client
+//      authentication is required.
+//
+//   2/ The caller then asks the user for a client certificate chain
+//      (i.e. with a UI dialog), and stores it in the |client_cert| field
+//      of the net::SSLConfig used to handle the connection.
+//
+//   3/ The caller invokes SSLClientSocket::Connect() again. This time,
+//      the client certificate chain stored in 2/ is used, as well as the
+//      corresponding private key, to sign the hash in the
+//      "Verify Certificate" message sent to the server.
+//
+// Note that in step 3/, the ::Connect() code only receives a handle to
+// the client certificate, and needs a way to sign a message with the
+// matching private key.
+//
+// OpenSSL doesn't provide a way to do this, because it doesn't implement
+// a key store. And on Android, the keystore platform APIs do not provide
+// a way to do it either.
+//
+// This is solved by using this function in step 2, as follows:
+//
+//    1/ Unchanged.
+//
+//    2/ Let the user select a client certificate, and retrieve both
+//       its certificate chain and a reference to its private key.
+//
+//    2b/ Call net::UseClientCertSigningPrivateKey() to let the network
+//        stack record the association between the client certificate's
+//        public key, and its private key handle.
+//
+//    3/ When Connect() is called the second time, use the certificate
+//       chain from the net::SSLConfig, and use its public key to retrieve
+//       the previously-stored private key reference. See
+//       net::OpenSSLPrivateKeyStore::FetchClientCertPrivateKey(), which
+//       is not exported by the network stack.
+//
+// |client_certificate| is the client certificate.
+// |private_key| holds the corresponding private key.
+// Returns true on success, false otherwise. On success, this increments
+// the reference count of |private_key|.
+bool NET_EXPORT UseOpenSSLClientCertSigningPrivateKey(
+    const X509Certificate& client_certificate, EVP_PKEY* private_key);

[Ryan Sleevi, 2013/02/12 00:25:17]

Is it really necessary to create another file for this - particularly one with
the openssl_ prefix rather than suffix?

Can this not fit anywhere else? I am concerned with the growing number of
seemingly related "one-off" SSL functions, and wonder if there is some logical
way that these should be grouped.

For example, should we just be exporting OpenSSLPrivateKeyStore, and let this
method hang off it? Why or why not?

[digit1, 2013/02/12 15:05:25]

There is a need for a single NET_EXPORT function that implements this feature,
to be called directly from the browser layer.

No other feature of OpenSSLPrivateKeyStore will ever be used from outside the
net/ layer, and I don't think exposing / exporting it would be useful (in other
comments, I've even hinted at the idea of getting rid of the interface
entirely).

I'm open to your suggestions for a better location though. I'm inclined to use a
separate header here because it's such a specialized usage that it doesn't
really fit the typical scope of other headers like x509_certificate.h or
x509_util_openssl.h.

[Ryan Sleevi, 2013/02/12 20:12:58]

While I'm amenable to replacing it, I think having both the helper functions and
the store are confusing for readers both within and external to net/. Having
utility functions for utility functions sake tends to hinder
readability/maintainability, so I'd like to avoid it if at all possible.

It's much easier to refactor calls to a single class than to deal with multiple
layers of indirection, especially when in an early phase of bringup.

[digit1, 2013/02/13 18:24:34]

openssl_util.* and openssl_key_store.* are now gone, and
net::OpenSSLPrivateKeyStore is now NET_EXPORT. This simplifies many things.
Thanks.

+
+}  // namespace net
+
+#endif  // NET_BASE_OPENSSL_KEY_STORE_H