Home | History | Annotate | Download | only in keystore 
      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      */
     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 
     97     public byte[] getWrappedKeyBytes() {
     98         return mWrappedKeyBytes;
     99     }
    100 
    101     public String getWrappingKeyAlias() {
    102         return mWrappingKeyAlias;
    103     }
    104 
    105     public String getTransformation() {
    106         return mTransformation;
    107     }
    108 
    109     public AlgorithmParameterSpec getAlgorithmParameterSpec() {
    110         return mAlgorithmParameterSpec;
    111     }
    112 }
    113 
    114