Add net/android/keystore.h

net/android/keystore.h

+// Copyright (c) 2012 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_ANDROID_KEYSTORE_H
+#define NET_ANDROID_KEYSTORE_H
+
+#include <jni.h>
+#include <openssl/evp.h>
+
+#include <string>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/string_piece.h"
+#include "net/base/net_export.h"
+
+// Misc classes to access the Android platform KeyStore.
+
+namespace net {
+namespace android {
+
+// A ClientCertRequest is used to handle the UI side of a SSL handshake
+// "Certificate Request" message. I.e. the server provides a list of
+// certificate key types and CA distinguished names, and expects a client
+// certificate chain and later a message signed with the corresponding
+// private key.
+//
+// Usage of this class is as follows:
+//
+// 1/ The embedder defines a net::android::ClientCertRequest sub-class,
+//    creates an instance, and call its Start() routine in the main

[palmer, 2013/01/19 01:43:12]

Typo: "calls"

[digit1, 2013/01/21 13:35:35]

Done.

+//    application thread. Start() returns immediately because the whole
+//    operation is asynchronous.
+//
+// 2/ This prompts the user with a dialog to select a pre-installed
+//    client certificate. Once selected, the OnCertificateSelection()
+//    method is called on the main application thread, providing
+//    a "private key alias", which is a simple string used to uniquely

[palmer, 2013/01/19 01:43:12]

How important is that uniqueness? If it is super important, how is uniqueness
guaranteed/enforced?

[digit1, 2013/01/21 13:35:35]

The user / system does that. When you install a private key / public key /
certificate, a UI dialog is prompted asking you for the corresponding name for
it.

The same name is displayed when the user is asked to select a certificate (e.g.
when calling android.KeyStore.choosePrivateKeyAlias()).

The only important thing for us is that a certificate chain and its private key
are stored under the same name (even if in practice they could be installed
separately, e.g. through a <keygen> HTML5 operation).

If you find this comment confusing, I can remove the "uniquely" from the
comment, but it just describes how the system works.

+//    identify the client certificate and its private key.
+//
+// 3/ Later, use GetOpenSSLClientCertificateFromPrivateKeyAlias() to
+//    retrieve the client certificate chain and a "fake" private key
+//    object that can be used for signing.
+//
+class ClientCertRequest {
+public:
+  // Create a new ClientCertRequest. Use Start() to start the request.
+  ClientCertRequest() : request_id_(0) {}
+
+  // Note: The destructor automatically cancels the request
+  // Must be called from the UI thread.
+  virtual ~ClientCertRequest();
+
+  // Return the unique request id for this object.
+  // This number is 0 if the request is not started (or cancelled).
+  int request_id() { return request_id_; }
+
+  // Start a new request from the current activity.
+  // |key_types| is a list of acceptable certificate key types.
+  // |issuers| is the list of certificate issuers accepted by the
+  // server. Each element is a DER-encoded X.509 DistinguishedName.
+  // |host_name| is the server's host name, if available (or empty).
+  // |port| is the server's port if available (or 0).
+  // Returns true on success, or false on error (e.g. if there is no
+  // Chromium activity currently running).
+  // IMPORTANT: Must be called from main application thread.
+  bool Start(const std::vector<std::string>& key_types,
+             const std::vector<std::string>& issuers,
+             const std::string& host,
+             int port);
+
+  // Cancel the current request.
+  // Must be called from main application thread.
+  void Cancel();
+
+  // Called on main application thread when the client certificate
+  // request has completed. This is an abstract method that must be
+  // overriden by client code.
+  //
+  // |private_key_alias| is a string serving as a unique id for the
+  // selected certificate and corresponding private key. Use it for
+  // debugging only.
+  //
+  // |cert_chain| is the client certificate chain, as a list of strings,
+  // where each item is a DER-encoded X.509 certificate.
+  //
+  // |private_key| is a JNI local reference to a Java PrivateKey object
+  // matching the certificate. It is destroyed after the method returns.
+  // If client code wants to keep a reference to the same object, it
+  // shall first copy it into its own local or global JNI reference.
+  // Said saved JNI reference can later be used with SignWithPrivateKey.
+  //
+  virtual void OnCertificateSelection(
+    const std::string& private_key_alias,
+    std::vector<std::string>& cert_chain,
+    jobject private_key) = 0;
+
+private:
+  int request_id_;
+};
+
+// Compute the signature of a given message, using a private key
+// identified by its unique alias.
+//
+// |private_key| is a JNI reference for the private key. Must point
+// to the object returned by ClientCertRequest::OnCertificateSelection.
+// |message| is the input message.
+// |signature| will receive the signature on success.
+// Returns true on success, false on failure.
+//
+bool SignWithPrivateKey(
+    jobject private_key,
+    const base::StringPiece& message,
+    std::vector<uint8>* signature);

[Ryan Sleevi, 2013/01/18 20:05:48]

DESIGN: This is not at all clear what type of signature will be generated. Is it
ECDSA? PKCS#1 v1.5 RSA-SSA? RSA-OAEP? Custom padding here (eg: as used by SSL)?

[palmer, 2013/01/19 01:43:12]

+1

[digit1, 2013/01/21 13:35:35]

Good question. I'm not sure how to best answer this. The goal is to implement
the signature required by OpenSSL's client certificate support code (which will
end up calling this through a custom method, like RSA_METHOD for RSA keys).

From what I've seen in the OpenSSL code, (ssl3_send_client_verify under
third_party/openssl/openssl/ssl/s3_clnt.c), for SSL version < DTLS 1.2, it ends
up calling:

 - RSA_sign() on a tuple of MD5 + SHA1 hashes.
 - DSA_sign() on the SHA1 hash only.
 - ECDA_sign() on the SHA1 hash only.

All these functions seem to have vanilla implementations (i.e. they don't take
parameters for padding or other optional things, only the content of the digest
and the key itself), and in the end that's what this method is supposed to
emulate, by using platform APIs.

If there is a fundamental reason why this can't work, please let me know.

Off-topic note: For DTLS 1.2 support, things may be a bit more tricky to
implement, because the equivalent of RSA_size(), DSA_size(), ECSA_size() is also
needed, because the OpenSSL code path is different, but I'd prefer to leave this
for a future patch.

If you have any suggestion on how to improve this code / comment, please let me
know.

+
+// Register JNI methods
+NET_EXPORT bool RegisterKeyStore(JNIEnv* env);
+
+}  // namespace android
+}  // namespace net
+
+#endif  // NET_ANDROID_KEYSTORE_H