AndroidKeyStore.java revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7 
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    int 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