1 /*
2  * Copyright (C) 2017 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 
18 package android.security.keystore;
19 
20 import java.security.KeyStore.Entry;
21 import java.security.spec.AlgorithmParameterSpec;
22 
23 /**
24  * An {@link Entry} that holds a wrapped key. Wrapped keys contain encrypted key data and
25  * description information that can be used to securely import key material into a hardware-backed
26  * Keystore.
27  *
28  * <p>
29  *   The wrapped key is in DER-encoded ASN.1 format, specified by the following schema:
30  * </p>
31  *
32  * <pre>
33  *     KeyDescription ::= SEQUENCE(
34  *         keyFormat INTEGER,                   # Values from KeyFormat enum.
35  *         keyParams AuthorizationList,
36  *     )
37  *
38  *     SecureKeyWrapper ::= SEQUENCE(
39  *         version INTEGER,                     # Contains value 0
40  *         encryptedTransportKey OCTET_STRING,
41  *         initializationVector OCTET_STRING,
42  *         keyDescription KeyDescription,
43  *         encryptedKey OCTET_STRING,
44  *         tag OCTET_STRING
45  *     )
46  * </pre>
47  * <ul>
48  *     <li>keyFormat is an integer from the KeyFormat enum, defining the format of the plaintext
49  *       key material.
50  *     </li>
51  *     <li>keyParams is the characteristics of the key to be imported (as with generateKey or
52  *       importKey).  If the secure import is successful, these characteristics must be
53  *       associated with the key exactly as if the key material had been insecurely imported
54  *       with importKey. See <a href="https://developer.android.com/training/articles/security-key-attestation.html#certificate_schema">Key Attestation</a> for the AuthorizationList format.
55  *     </li>
56  *     <li>encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted
57  *       in RSA-OAEP mode (SHA-256 digest, SHA-1 MGF1 digest) with the wrapping key specified by
58  *       wrappingKeyBlob.
59  *     </li>
60  *     <li>keyDescription is a KeyDescription, above.
61  *     </li>
62  *     <li>encryptedKey is the key material of the key to be imported, in format keyFormat, and
63  *       encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded
64  *       representation of keyDescription provided as additional authenticated data.
65  *     </li>
66  *     <li>tag is the tag produced by the AES-GCM encryption of encryptedKey.
67  *     </li>
68  *</ul>
69  *
70  * <p>
71  *     Imported wrapped keys will have KeymasterDefs.KM_ORIGIN_SECURELY_IMPORTED
72  * </p>
73  */
74 public class WrappedKeyEntry implements Entry {
75 
76     private final byte[] mWrappedKeyBytes;
77     private final String mWrappingKeyAlias;
78     private final String mTransformation;
79     private final AlgorithmParameterSpec mAlgorithmParameterSpec;
80 
81     /**
82      * Constructs a {@link WrappedKeyEntry} with a binary wrapped key.
83      *
84      * @param wrappedKeyBytes ASN.1 DER encoded wrapped key
85      * @param wrappingKeyAlias identifies the private key that can unwrap the wrapped key
86      * @param transformation used to unwrap the key. ex: "RSA/ECB/OAEPPadding"
87      * @param algorithmParameterSpec spec for the private key used to unwrap the wrapped key
88      */
WrappedKeyEntry(byte[] wrappedKeyBytes, String wrappingKeyAlias, String transformation, AlgorithmParameterSpec algorithmParameterSpec)89     public WrappedKeyEntry(byte[] wrappedKeyBytes, String wrappingKeyAlias, String transformation,
90             AlgorithmParameterSpec algorithmParameterSpec) {
91         mWrappedKeyBytes = wrappedKeyBytes;
92         mWrappingKeyAlias = wrappingKeyAlias;
93         mTransformation = transformation;
94         mAlgorithmParameterSpec = algorithmParameterSpec;
95     }
96 
getWrappedKeyBytes()97     public byte[] getWrappedKeyBytes() {
98         return mWrappedKeyBytes;
99     }
100 
getWrappingKeyAlias()101     public String getWrappingKeyAlias() {
102         return mWrappingKeyAlias;
103     }
104 
getTransformation()105     public String getTransformation() {
106         return mTransformation;
107     }
108 
getAlgorithmParameterSpec()109     public AlgorithmParameterSpec getAlgorithmParameterSpec() {
110         return mAlgorithmParameterSpec;
111     }
112 }
113 
114