net/android/keystore.h

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_ANDROID_KEYSTORE_H
   6 #define NET_ANDROID_KEYSTORE_H
   7
   8 #include <jni.h>
   9
  10 #include <string>
  11 #include <vector>
  12
  13 #include "base/android/scoped_java_ref.h"
  14 #include "base/basictypes.h"
  15 #include "base/strings/string_piece.h"
  16 #include "net/base/net_export.h"
  17 #include "net/ssl/ssl_client_cert_type.h"
  18
  19 // Misc functions to access the Android platform KeyStore.
  20
  21 namespace net {
  22 namespace android {
  23
  24 struct AndroidEVP_PKEY;
  25
  26 // Define a list of constants describing private key types. The
  27 // values are shared with Java through org.chromium.net.PrivateKeyType.
  28 // Example: PRIVATE_KEY_TYPE_RSA.
  29 //
  30 // A Java counterpart will be generated for this enum.
  31 // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.net
  32 enum PrivateKeyType {
  33   PRIVATE_KEY_TYPE_RSA = 0,
  34   PRIVATE_KEY_TYPE_DSA = 1,
  35   PRIVATE_KEY_TYPE_ECDSA = 2,
  36   PRIVATE_KEY_TYPE_INVALID = 255,
  37 };
  38
  39 // Returns the modulus of a given RSAPrivateKey platform object,
  40 // as a series of bytes, in big-endian representation. This can be
  41 // used with BN_bin2bn() to convert to an OpenSSL BIGNUM.
  42 //
  43 // |private_key| is a JNI reference for the private key.
  44 // |modulus| will receive the modulus bytes on success.
  45 // Returns true on success, or false on failure (e.g. if the key
  46 // is not RSA).
  47 NET_EXPORT bool GetRSAKeyModulus(jobject private_key,
  48                                  std::vector<uint8>* modulus);
  49
  50 // Returns the Q parameter of a given DSAPrivateKey platform object,
  51 // as a series of bytes, in big-endian representation. This can be used
  52 // with BN_bin2bn() to convert to an OpenSSL BIGNUM.
  53 // |private_key| is a JNI reference for the private key.
  54 // |q| will receive the result bytes on success.
  55 // Returns true on success, or false on failure (e.g. if the key is
  56 // not DSA).
  57 NET_EXPORT bool GetDSAKeyParamQ(jobject private_key,
  58                                 std::vector<uint8>* q);
  59
  60 // Returns the order parameter of a given ECPrivateKey platform object,
  61 // as a series of bytes, in big-endian representation. This can be used
  62 // with BN_bin2bn() to convert to an OpenSSL BIGNUM.
  63 // |private_key| is a JNI reference for the private key.
  64 // |order| will receive the result bytes on success.
  65 // Returns true on success, or false on failure (e.g. if the key is
  66 // not EC).
  67 bool GetECKeyOrder(jobject private_key,
  68                    std::vector<uint8>* order);
  69
  70 // Returns the encoded PKCS#8 representation of a private key.
  71 // This only works on Android 4.0.3 and older releases for platform keys
  72 // (i.e. all keys except those explicitely generated by the application).
  73 // |private_key| is a JNI reference for the private key.
  74 // |encoded| will receive the encoded data on success.
  75 // Returns true on success, or false on failure (e.g. on 4.0.4 or higher).
  76 bool GetPrivateKeyEncodedBytes(jobject private_key,
  77                                std::vector<uint8>* encoded);
  78
  79 // Compute the signature of a given message, which is actually a hash,
  80 // using a private key. For more details, please read the comments for the
  81 // rawSignDigestWithPrivateKey method in AndroidKeyStore.java.
  82 //
  83 // |private_key| is a JNI reference for the private key.
  84 // |digest| is the input digest.
  85 // |signature| will receive the signature on success.
  86 // Returns true on success, false on failure.
  87 //
  88 NET_EXPORT bool RawSignDigestWithPrivateKey(
  89     jobject private_key,
  90     const base::StringPiece& digest,
  91     std::vector<uint8>* signature);
  92
  93
  94 // Return the PrivateKeyType of a given private key.
  95 // |private_key| is a JNI reference for the private key.
  96 // Returns a PrivateKeyType, while will be CLIENT_CERT_INVALID_TYPE
  97 // on error.
  98 NET_EXPORT PrivateKeyType GetPrivateKeyType(jobject private_key);
  99
 100 // Returns a handle to the system AndroidEVP_PKEY object used to back a given
 101 // private_key object. This must *only* be used for RSA private keys on Android
 102 // < 4.2. Technically, this is only guaranteed to work if the system image
 103 // contains a vanilla implementation of the Java API frameworks based on Harmony
 104 // + OpenSSL.
 105 //
 106 // |private_key| is a JNI reference for the private key.
 107 // Returns an AndroidEVP_PKEY* handle, or NULL in case of error.
 108 //
 109 // Note: Despite its name and return type, this function doesn't know
 110 //       anything about OpenSSL, it just type-casts a system pointer that
 111 //       is passed as an int through JNI. As such, it never increments
 112 //       the returned key's reference count.
 113 AndroidEVP_PKEY* GetOpenSSLSystemHandleForPrivateKey(jobject private_key);
 114
 115 // Returns a JNI reference to the OpenSSLEngine object which is used to back a
 116 // given private_key object. This must *only* be used for RSA private keys on
 117 // Android < 4.2. Technically, this is only guaranteed to work if the system
 118 // image contains a vanilla implementation of the Java API frameworks based on
 119 // Harmony + OpenSSL.
 120 base::android::ScopedJavaLocalRef<jobject> GetOpenSSLEngineForPrivateKey(
 121     jobject private_key);
 122
 123 NET_EXPORT void ReleaseKey(jobject private_key);
 124
 125 // Register JNI methods
 126 NET_EXPORT bool RegisterKeyStore(JNIEnv* env);
 127
 128 }  // namespace android
 129 }  // namespace net
 130
 131 #endif  // NET_ANDROID_KEYSTORE_H