1 /*
2  * Copyright 2015 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_KEYMASTER_CONTEXT_H_
18 #define SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_
19 
20 #include <assert.h>
21 
22 #include <hardware/keymaster_defs.h>
23 #include <keymaster/android_keymaster_utils.h>
24 #include <keymaster/keymaster_enforcement.h>
25 
26 namespace keymaster {
27 
28 class AuthorizationSet;
29 class KeyFactory;
30 class OperationFactory;
31 template <typename BlobType> struct TKeymasterBlob;
32 typedef TKeymasterBlob<keymaster_key_blob_t> KeymasterKeyBlob;
33 class Key;
34 
35 /**
36  * KeymasterContext provides a singleton abstract interface that encapsulates various
37  * environment-dependent elements of AndroidKeymaster.
38  *
39  * AndroidKeymaster runs in multiple contexts.  Primarily:
40  *
41  * - In a trusted execution environment (TEE) as a "secure hardware" implementation.  In this
42  *   context keys are wrapped with an master key that never leaves the TEE, TEE-specific routines
43  *   are used for random number generation, all AndroidKeymaster-enforced authorizations are
44  *   considered hardware-enforced, and there's a bootloader-provided root of trust.
45  *
46  * - In the non-secure world as a software-only implementation.  In this context keys are not
47  *   encrypted (though they are integrity-checked) because there is no place to securely store a
48  *   key, OpenSSL is used for random number generation, no AndroidKeymaster-enforced authorizations
49  *   are considered hardware enforced and the root of trust is a static string.
50  *
51  * - In the non-secure world as a hybrid implementation fronting a less-capable hardware
52  *   implementation.  For example, a keymaster0 hardware implementation.  In this context keys are
53  *   not encrypted by AndroidKeymaster, but some may be opaque blobs provided by the backing
54  *   hardware, but blobs that lack the extended authorization lists of keymaster1.  In addition,
55  *   keymaster0 lacks many features of keymaster1, including modes of operation related to the
56  *   backing keymaster0 keys.  AndroidKeymaster must extend the blobs to add authorization lists,
57  *   and must provide the missing operation mode implementations in software, which means that
58  *   authorization lists are partially hardware-enforced (the bits that are enforced by the
59  *   underlying keymaster0) and partially software-enforced (the rest). OpenSSL is used for number
60  *   generation and the root of trust is a static string.
61  *
62  * More contexts are possible.
63  */
64 class KeymasterContext {
65   public:
KeymasterContext()66     KeymasterContext() {}
~KeymasterContext()67     virtual ~KeymasterContext(){};
68 
69     /**
70      * Sets the system version as reported by the system *itself*.  This is used to verify that the
71      * system believes itself to be running the same version that is reported by the bootloader, in
72      * hardware implementations.  For SoftKeymasterDevice, this sets the version information used.
73      *
74      * If the specified values don't match the bootloader-provided values, this method must return
75      * KM_ERROR_INVALID_ARGUMENT;
76      */
77     virtual keymaster_error_t SetSystemVersion(uint32_t os_version, uint32_t os_patchlevel) = 0;
78 
79     /**
80      * Returns the system version.  For hardware-based implementations this will be the value
81      * reported by the bootloader.  For SoftKeymasterDevice it will be the verion information set by
82      * SetSystemVersion above.
83      */
84     virtual void GetSystemVersion(uint32_t* os_version, uint32_t* os_patchlevel) const = 0;
85 
86     virtual const KeyFactory* GetKeyFactory(keymaster_algorithm_t algorithm) const = 0;
87     virtual const OperationFactory* GetOperationFactory(keymaster_algorithm_t algorithm,
88                                                         keymaster_purpose_t purpose) const = 0;
89     virtual const keymaster_algorithm_t* GetSupportedAlgorithms(size_t* algorithms_count) const = 0;
90 
91     /**
92      * UpgradeKeyBlob takes an existing blob, parses out key material and constructs a new blob with
93      * the current format and OS version info.
94      */
95     virtual keymaster_error_t UpgradeKeyBlob(const KeymasterKeyBlob& key_to_upgrade,
96                                              const AuthorizationSet& upgrade_params,
97                                              KeymasterKeyBlob* upgraded_key) const = 0;
98 
99     /**
100      * ParseKeyBlob takes a blob and extracts authorization sets and key material, returning an
101      * error if the blob fails integrity checking or decryption.  Note that the returned key
102      * material may itself be an opaque blob usable only by secure hardware (in the hybrid case).
103      *
104      * This method is called by AndroidKeymaster.
105      */
106     virtual keymaster_error_t ParseKeyBlob(const KeymasterKeyBlob& blob,
107                                            const AuthorizationSet& additional_params,
108                                            UniquePtr<Key>* key) const = 0;
109 
110     /**
111      * Take whatever environment-specific action is appropriate (if any) to delete the specified
112      * key.
113      */
DeleteKey(const KeymasterKeyBlob &)114     virtual keymaster_error_t DeleteKey(const KeymasterKeyBlob& /* blob */) const {
115         return KM_ERROR_OK;
116     }
117 
118     /**
119      * Take whatever environment-specific action is appropriate to delete all keys.
120      */
DeleteAllKeys()121     virtual keymaster_error_t DeleteAllKeys() const { return KM_ERROR_OK; }
122 
123     /**
124      * Adds entropy to the Cryptographic Pseudo Random Number Generator used to generate key
125      * material, and other cryptographic protocol elements.  Note that if the underlying CPRNG
126      * tracks the size of its entropy pool, it should not assume that the provided data contributes
127      * any entropy, and it should also ensure that data provided through this interface cannot
128      * "poison" the CPRNG outputs, making them predictable.
129      */
130     virtual keymaster_error_t AddRngEntropy(const uint8_t* buf, size_t length) const = 0;
131 
132     /**
133      * Return the enforcement policy for this context, or null if no enforcement should be done.
134      */
135     virtual KeymasterEnforcement* enforcement_policy() = 0;
136 
137     virtual keymaster_error_t GenerateAttestation(const Key& key,
138                                                   const AuthorizationSet& attest_params,
139                                                   CertChainPtr* cert_chain) const = 0;
140 
141     virtual keymaster_error_t
142     UnwrapKey(const KeymasterKeyBlob& wrapped_key_blob, const KeymasterKeyBlob& wrapping_key_blob,
143               const AuthorizationSet& wrapping_key_params, const KeymasterKeyBlob& masking_key,
144               AuthorizationSet* wrapped_key_params, keymaster_key_format_t* wrapped_key_format,
145               KeymasterKeyBlob* wrapped_key_material) const = 0;
146 
147   private:
148     // Uncopyable.
149     KeymasterContext(const KeymasterContext&);
150     void operator=(const KeymasterContext&);
151 };
152 
153 }  // namespace keymaster
154 
155 #endif  // SYSTEM_KEYMASTER_KEYMASTER_CONTEXT_H_
156