src/net/android/java/src/org/chromium/net/AndroidKeyStore.java

   1 // Copyright 2014 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 package org.chromium.net;
   6
   7 import org.chromium.base.CalledByNative;
   8 import org.chromium.base.JNINamespace;
   9
  10 /**
  11  * Specifies all the dependencies from the native OpenSSL engine on an Android KeyStore.
  12  */
  13 @JNINamespace("net::android")
  14 public interface AndroidKeyStore {
  15
  16     /**
  17      * Returns the public modulus of a given RSA private key as a byte
  18      * buffer.
  19      * This can be used by native code to convert the modulus into
  20      * an OpenSSL BIGNUM object. Required to craft a custom native RSA
  21      * object where RSA_size() works as expected.
  22      *
  23      * @param key A PrivateKey instance, must implement RSAKey.
  24      * @return A byte buffer corresponding to the modulus. This is
  25      * big-endian representation of a BigInteger.
  26      */
  27     @CalledByNative
  28     byte[] getRSAKeyModulus(AndroidPrivateKey key);
  29
  30     /**
  31      * Returns the 'Q' parameter of a given DSA private key as a byte
  32      * buffer.
  33      * This can be used by native code to convert it into an OpenSSL BIGNUM
  34      * object where DSA_size() works as expected.
  35      *
  36      * @param key A PrivateKey instance. Must implement DSAKey.
  37      * @return A byte buffer corresponding to the Q parameter. This is
  38      * a big-endian representation of a BigInteger.
  39      */
  40     @CalledByNative
  41     byte[] getDSAKeyParamQ(AndroidPrivateKey key);
  42
  43     /**
  44      * Returns the 'order' parameter of a given ECDSA private key as a
  45      * a byte buffer.
  46      * @param key A PrivateKey instance. Must implement ECKey.
  47      * @return A byte buffer corresponding to the 'order' parameter.
  48      * This is a big-endian representation of a BigInteger.
  49      */
  50     @CalledByNative
  51     byte[] getECKeyOrder(AndroidPrivateKey key);
  52
  53     /**
  54      * Returns the encoded data corresponding to a given PrivateKey.
  55      * Note that this will fail for platform keys on Android 4.0.4
  56      * and higher. It can be used on 4.0.3 and older platforms to
  57      * route around the platform bug described below.
  58      * @param key A PrivateKey instance
  59      * @return encoded key as PKCS#8 byte array, can be null.
  60      */
  61     @CalledByNative
  62     byte[] getPrivateKeyEncodedBytes(AndroidPrivateKey key);
  63
  64     /**
  65      * Sign a given message with a given PrivateKey object. This method
  66      * shall only be used to implement signing in the context of SSL
  67      * client certificate support.
  68      *
  69      * The message will actually be a hash, computed by OpenSSL itself,
  70      * depending on the type of the key. The result should match exactly
  71      * what the vanilla implementations of the following OpenSSL function
  72      * calls do:
  73      *
  74      *  - For a RSA private key, this should be equivalent to calling
  75      *    RSA_private_encrypt(..., RSA_PKCS1_PADDING), i.e. it must
  76      *    generate a raw RSA signature. The message must be either a
  77      *    combined, 36-byte MD5+SHA1 message digest or a DigestInfo
  78      *    value wrapping a message digest.
  79      *
  80      *  - For a DSA and ECDSA private keys, this should be equivalent to
  81      *    calling DSA_sign(0,...) and ECDSA_sign(0,...) respectively. The
  82      *    message must be a hash and the function shall compute a direct
  83      *    DSA/ECDSA signature for it.
  84      *
  85      * @param key The PrivateKey handle.
  86      * @param message The message to sign.
  87      * @return signature as a byte buffer.
  88      *
  89      * Important: Due to a platform bug, this function will always fail on
  90      *            Android < 4.2 for RSA PrivateKey objects. See the
  91      *            getOpenSSLHandleForPrivateKey() below for work-around.
  92      */
  93     @CalledByNative
  94     byte[] rawSignDigestWithPrivateKey(AndroidPrivateKey key, byte[] message);
  95
  96     /**
  97      * Return the type of a given PrivateKey object. This is an integer
  98      * that maps to one of the values defined by org.chromium.net.PrivateKeyType,
  99      * which is itself auto-generated from net/android/private_key_type_list.h
 100      * @param key The PrivateKey handle
 101      * @return key type, or PrivateKeyType.INVALID if unknown.
 102      */
 103     @CalledByNative
 104     int getPrivateKeyType(AndroidPrivateKey key);
 105
 106     /**
 107      * Return the system EVP_PKEY handle corresponding to a given PrivateKey
 108      * object.
 109      *
 110      * This shall only be used when the "NONEwithRSA" signature is not
 111      * available, as described in rawSignDigestWithPrivateKey(). I.e.
 112      * never use this on Android 4.2 or higher.
 113      *
 114      * This can only work in Android 4.0.4 and higher, for older versions
 115      * of the platform (e.g. 4.0.3), there is no system OpenSSL EVP_PKEY,
 116      * but the private key contents can be retrieved directly with
 117      * the getEncoded() method.
 118      *
 119      * This assumes that the target device uses a vanilla AOSP
 120      * implementation of its java.security classes, which is also
 121      * based on OpenSSL (fortunately, no OEM has apperently changed to
 122      * a different implementation, according to the Android team).
 123      *
 124      * Note that the object returned was created with the platform version
 125      * of OpenSSL, and _not_ the one that comes with Chromium. Whether the
 126      * object can be used safely with the Chromium OpenSSL library depends
 127      * on differences between their actual ABI / implementation details.
 128      *
 129      * To better understand what's going on below, please refer to the
 130      * following source files in the Android 4.0.4 and 4.1 source trees:
 131      * libcore/luni/src/main/java/org/apache/harmony/xnet/provider/jsse/OpenSSLRSAPrivateKey.java
 132      * libcore/luni/src/main/native/org_apache_harmony_xnet_provider_jsse_NativeCrypto.cpp
 133      *
 134      * @param key The PrivateKey handle.
 135      * @return The EVP_PKEY handle, as a 32-bit integer (0 if not available)
 136      */
 137     @CalledByNative
 138     long getOpenSSLHandleForPrivateKey(AndroidPrivateKey key);
 139
 140     /**
 141      * Return the OpenSSLEngine object corresponding to a given PrivateKey
 142      * object.
 143      *
 144      * This shall only be used for Android 4.1 to work around a platform bug.
 145      * See https://crbug.com/381465.
 146      *
 147      * @param key The PrivateKey handle.
 148      * @return The OpenSSLEngine object (or null if not available)
 149      */
 150     @CalledByNative
 151     Object getOpenSSLEngineForPrivateKey(AndroidPrivateKey key);
 152
 153     /**
 154      * Called when the native OpenSSL engine no longer needs access to the underlying key.
 155      */
 156     @CalledByNative
 157     void releaseKey(AndroidPrivateKey key);
 158 }