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
31namespace 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 */
38class 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