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 
~KeyBlob()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      */
error()107     inline keymaster_error_t error() { return error_; }
108 
nonce()109     inline const uint8_t* nonce() const { return nonce_.get(); }
key_material()110     inline const uint8_t* key_material() const { return key_material_.get(); }
encrypted_key_material()111     inline const uint8_t* encrypted_key_material() const { return encrypted_key_material_.get(); }
key_material_length()112     inline size_t key_material_length() const { return key_material_length_; }
tag()113     inline const uint8_t* tag() const { return tag_.get(); }
114 
enforced()115     inline const AuthorizationSet& enforced() const { return enforced_; }
unenforced()116     inline const AuthorizationSet& unenforced() const { return unenforced_; }
hidden()117     inline const AuthorizationSet& hidden() const { return hidden_; }
algorithm()118     inline keymaster_algorithm_t algorithm() const { return algorithm_; }
key_size_bits()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