Home | History | Annotate | Download | only in keymaster 
      1 /*
      2  * Copyright 2014 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 #ifndef SYSTEM_KEYMASTER_KEY_BLOB_H_
     18 #define SYSTEM_KEYMASTER_KEY_BLOB_H_
     19 
     20 #include <cstddef>
     21 
     22 #include <stdint.h>
     23 
     24 #include <UniquePtr.h>
     25 
     26 #include <keymaster/authorization_set.h>
     27 #include <keymaster/google_keymaster_utils.h>
     28 #include <keymaster/keymaster_defs.h>
     29 #include <keymaster/serializable.h>
     30 
     31 namespace keymaster {
     32 
     33 /**
     34  * This class represents a Keymaster key blob, including authorization sets and key material, both
     35  * encrypted and unencrypted.  It's primary purpose is to serialize and deserialize blob arrays, and
     36  * provide access to the data in the blob.
     37  */
     38 class KeyBlob : public Serializable {
     39   public:
     40     static const size_t NONCE_LENGTH = 12;
     41     static const size_t TAG_LENGTH = 128 / 8;
     42 
     43     /**
     44      * Create a KeyBlob containing the specified authorization data and key material.  The copy of
     45      * \p key will be encrypted with key derived from \p master_key, using OCB authenticated
     46      * encryption with \p nonce.  It is critically important that nonces NEVER be reused.  The most
     47      * convenient way to accomplish that is to choose them randomly (assuming good randomness, that
     48      * means there's a probability of reuse of one in 2^96).
     49      *
     50      * Note that this interface abuses \p keymaster_key_blob_t a bit.  Normally, that struct is used
     51      * to contain a full Keymaster blob, i.e. what KeyBlob is designed to create and manage.  In
     52      * this case we're using it to hold pure key material without any of the additional structure
     53      * needed for a true Keymaster key.
     54      *
     55      * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable.
     56      */
     57     KeyBlob(const AuthorizationSet& enforced, const AuthorizationSet& unenforced,
     58             const AuthorizationSet& hidden, const keymaster_key_blob_t& key,
     59             const keymaster_key_blob_t& master_key, const uint8_t nonce[NONCE_LENGTH]);
     60 
     61     /**
     62      * Create a KeyBlob, reconstituting it from the encrypted material in \p encrypted_key,
     63      * decrypted with key derived from \p master_key.  The KeyBlob takes ownership of the \p
     64      * keymaster_blob.key_material.
     65      *
     66      * Note, again, that \p master_key here is an abuse of \p keymaster_key_blob_t, since it
     67      * is just key material, not a full Keymaster blob.
     68      *
     69      * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable.
     70      */
     71     KeyBlob(const keymaster_key_blob_t& keymaster_blob, const AuthorizationSet& hidden,
     72             const keymaster_key_blob_t& master_key);
     73 
     74     /**
     75      * Create a KeyBlob, extracting the enforced and unenforced sets, but not decrypting the key, or
     76      * even keeping it.  The KeyBlob does *not* take ownership of key_blob.
     77      *
     78      * IMPORTANT: After constructing a KeyBlob, call error() to verify that the blob is usable.
     79      */
     80     KeyBlob(const uint8_t* key_blob, size_t blob_size);
     81 
     82     ~KeyBlob() {
     83         memset_s(key_material_.get(), 0, key_material_length_);
     84         // The following aren't sensitive, but clear them anyway.
     85         memset_s(encrypted_key_material_.get(), 0, key_material_length_);
     86         memset_s(nonce_.get(), 0, NONCE_LENGTH);
     87         memset_s(tag_.get(), 0, TAG_LENGTH);
     88         // AuthorizationSets clear themselves.
     89     }
     90 
     91     size_t SerializedSize() const;
     92     uint8_t* Serialize(uint8_t* buf, const uint8_t* end) const;
     93     bool Deserialize(const uint8_t** buf_ptr, const uint8_t* end);
     94 
     95     /**
     96      * Decrypt encrypted key.  Call this after calling "Deserialize". Until it's called,
     97      * key_material() will return a pointer to an uninitialized buffer.  Sets error if there is a
     98      * problem.
     99      */
    100     void DecryptKey(const keymaster_key_blob_t& master_key);
    101 
    102     /**
    103      * Returns KM_ERROR_OK if all is well, or an appropriate error code if there is a problem.  This
    104      * error code should be checked after constructing or deserializing/decrypting, and if it does
    105      * not return KM_ERROR_OK, then don't call any other methods.
    106      */
    107     inline keymaster_error_t error() { return error_; }
    108 
    109     inline const uint8_t* nonce() const { return nonce_.get(); }
    110     inline const uint8_t* key_material() const { return key_material_.get(); }
    111     inline const uint8_t* encrypted_key_material() const { return encrypted_key_material_.get(); }
    112     inline size_t key_material_length() const { return key_material_length_; }
    113     inline const uint8_t* tag() const { return tag_.get(); }
    114 
    115     inline const AuthorizationSet& enforced() const { return enforced_; }
    116     inline const AuthorizationSet& unenforced() const { return unenforced_; }
    117     inline const AuthorizationSet& hidden() const { return hidden_; }
    118     inline keymaster_algorithm_t algorithm() const { return algorithm_; }
    119     inline size_t key_size_bits() const { return key_size_bits_; }
    120 
    121   private:
    122     void EncryptKey(const keymaster_key_blob_t& master_key);
    123     bool ExtractKeyCharacteristics();
    124 
    125     /**
    126      * Create an AES_OCB context initialized with a key derived using \p master_key and the
    127      * authorizations.
    128      */
    129     class AeCtx;
    130     AeCtx* InitializeKeyWrappingContext(const keymaster_key_blob_t& master_key,
    131                                         keymaster_error_t* error) const;
    132 
    133     const uint8_t* BuildDerivationData(size_t* derivation_data_len) const;
    134 
    135     keymaster_error_t error_;
    136     UniquePtr<uint8_t[]> nonce_;
    137     UniquePtr<uint8_t[]> key_material_;
    138     UniquePtr<uint8_t[]> encrypted_key_material_;
    139     UniquePtr<uint8_t[]> tag_;
    140     size_t key_material_length_;
    141     AuthorizationSet enforced_;
    142     AuthorizationSet unenforced_;
    143     AuthorizationSet hidden_;
    144     keymaster_algorithm_t algorithm_;
    145     uint32_t key_size_bits_;
    146 };
    147 
    148 }  // namespace keymaster
    149 
    150 #endif  // SYSTEM_KEYMASTER_KEY_BLOB_H_
    151