AndroidKeyStore.java revision a1401311d1ab56c4ed0a474bd38c108f75cb0cd9
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 5package org.chromium.net; 6 7import org.chromium.base.CalledByNative; 8import 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") 14public 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 * Called when the native OpenSSL engine no longer needs access to the underlying key. 142 */ 143 @CalledByNative 144 void releaseKey(AndroidPrivateKey key); 145} 146