1 /*
2  **
3  ** Copyright 2017, The Android Open Source Project
4  **
5  ** Licensed under the Apache License, Version 2.0 (the "License");
6  ** you may not use this file except in compliance with the License.
7  ** You may obtain a copy of the License at
8  **
9  **     http://www.apache.org/licenses/LICENSE-2.0
10  **
11  ** Unless required by applicable law or agreed to in writing, software
12  ** distributed under the License is distributed on an "AS IS" BASIS,
13  ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  ** See the License for the specific language governing permissions and
15  ** limitations under the License.
16  */
17 
18 #pragma once
19 
20 #include <memory>
21 #include <vector>
22 
23 #include <android/hardware/keymaster/4.1/IKeymasterDevice.h>
24 #include <keymasterV4_1/keymaster_tags.h>
25 
26 namespace android::hardware::keymaster::V4_1::support {
27 
28 /**
29  * Keymaster abstracts the underlying V4_1::IKeymasterDevice.  There are two implementations,
30  * Keymaster3 which wraps a V3_0::IKeymasterDevice and Keymaster4, which wraps either a
31  * V4_0::IKeymasterDevice or a V4_1::IKeymasterDevice.  There is a V3_0::IKeymasterDevice
32  * implementation that is used to wrap pre-HIDL keymaster implementations, and Keymaster3 will wrap
33  * that.
34  *
35  * The reason for adding this additional layer, rather than simply using the latest HAL directly and
36  * subclassing it to wrap any older HAL, is because this provides a place to put additional methods
37  * which clients can use when they need to distinguish between different underlying HAL versions,
38  * while still having to use only the latest interface.  Plus it's a handy place to keep some
39  * convenience methods.
40  */
41 class Keymaster : public IKeymasterDevice {
42   public:
43     using KeymasterSet = std::vector<android::sp<Keymaster>>;
44 
Keymaster(const hidl_string & descriptor,const hidl_string & instanceName)45     Keymaster(const hidl_string& descriptor, const hidl_string& instanceName)
46         : descriptor_(descriptor), instanceName_(instanceName) {}
~Keymaster()47     virtual ~Keymaster() {}
48 
49     struct VersionResult {
50         hidl_string keymasterName;
51         hidl_string authorName;
52         uint8_t majorVersion;
53         uint8_t minorVersion;
54         SecurityLevel securityLevel;
55         bool supportsEc;
56 
57         bool operator>(const VersionResult& other) const {
58             auto lhs = std::tie(securityLevel, majorVersion, minorVersion, supportsEc);
59             auto rhs = std::tie(other.securityLevel, other.majorVersion, other.minorVersion,
60                                 other.supportsEc);
61             return lhs > rhs;
62         }
63     };
64 
65     virtual const VersionResult& halVersion() const = 0;
descriptor()66     const hidl_string& descriptor() const { return descriptor_; }
instanceName()67     const hidl_string& instanceName() const { return instanceName_; }
68 
69     /**
70      * If ec is in the vendor error code range (<-10000), logs the fact to logcat.
71      * There are no side effects otherwise.
72      */
73     void logIfKeymasterVendorError(ErrorCode ec) const;
logIfKeymasterVendorError(V4_0::ErrorCode ec)74     void logIfKeymasterVendorError(V4_0::ErrorCode ec) const {
75         logIfKeymasterVendorError(static_cast<ErrorCode>(ec));
76     }
77 
78     /**
79      * Returns all available Keymaster3 and Keymaster4 instances, in order of most secure to least
80      * secure (as defined by VersionResult::operator<).
81      */
82     static KeymasterSet enumerateAvailableDevices();
83 
84     /**
85      * Ask provided Keymaster instances to compute a shared HMAC key using
86      * getHmacSharingParameters() and computeSharedHmac().  This computation is idempotent as long
87      * as the same set of Keymaster instances is used each time (and if all of the instances work
88      * correctly).  It must be performed once per boot, but should do no harm to be repeated.
89      *
90      * If key agreement fails, this method will crash the process (with CHECK).
91      */
92     static void performHmacKeyAgreement(const KeymasterSet& keymasters);
93 
94   private:
95     hidl_string descriptor_;
96     hidl_string instanceName_;
97 };
98 
99 std::ostream& operator<<(std::ostream& os, const Keymaster& keymaster);
100 
101 }  // namespace android::hardware::keymaster::V4_1::support
102