Home | History | Annotate | Download | only in keymasterV4_0 
      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 #ifndef HARDWARE_INTERFACES_KEYMASTER_40_SUPPORT_KEYMASTER_H_
     19 #define HARDWARE_INTERFACES_KEYMASTER_40_SUPPORT_KEYMASTER_H_
     20 
     21 #include <android/hardware/keymaster/4.0/IKeymasterDevice.h>
     22 
     23 #include <memory>
     24 #include <vector>
     25 
     26 namespace android {
     27 namespace hardware {
     28 namespace keymaster {
     29 namespace V4_0 {
     30 namespace support {
     31 
     32 /**
     33  * Keymaster abstracts the underlying V4_0::IKeymasterDevice.  There is one implementation
     34  * (Keymaster4) which is a trivial passthrough and one that wraps a V3_0::IKeymasterDevice.
     35  *
     36  * The reason for adding this additional layer, rather than simply using the latest HAL directly and
     37  * subclassing it to wrap any older HAL, is because this provides a place to put additional methods
     38  * which clients can use when they need to distinguish between different underlying HAL versions,
     39  * while still having to use only the latest interface.
     40  */
     41 class Keymaster : public IKeymasterDevice {
     42    public:
     43     using KeymasterSet = std::vector<std::unique_ptr<Keymaster>>;
     44 
     45     Keymaster(const hidl_string& descriptor, const hidl_string& instanceName)
     46         : descriptor_(descriptor), instanceName_(instanceName) {}
     47     virtual ~Keymaster() {}
     48 
     49     struct VersionResult {
     50         hidl_string keymasterName;
     51         hidl_string authorName;
     52         uint8_t majorVersion;
     53         SecurityLevel securityLevel;
     54         bool supportsEc;
     55 
     56         bool operator>(const VersionResult& other) const {
     57             auto lhs = std::tie(securityLevel, majorVersion, supportsEc);
     58             auto rhs = std::tie(other.securityLevel, other.majorVersion, other.supportsEc);
     59             return lhs > rhs;
     60         }
     61     };
     62 
     63     virtual const VersionResult& halVersion() const = 0;
     64     const hidl_string& descriptor() const { return descriptor_; }
     65     const hidl_string& instanceName() const { return instanceName_; }
     66 
     67     /**
     68      * If ec is in the vendor error code range (<-10000), logs the fact to logcat.
     69      * There are no side effects otherwise.
     70      */
     71     void logIfKeymasterVendorError(ErrorCode ec) const;
     72 
     73     /**
     74      * Returns all available Keymaster3 and Keymaster4 instances, in order of most secure to least
     75      * secure (as defined by VersionResult::operator<).
     76      */
     77     static KeymasterSet enumerateAvailableDevices();
     78 
     79     /**
     80      * Ask provided Keymaster instances to compute a shared HMAC key using
     81      * getHmacSharingParameters() and computeSharedHmac().  This computation is idempotent as long
     82      * as the same set of Keymaster instances is used each time (and if all of the instances work
     83      * correctly).  It must be performed once per boot, but should do no harm to be repeated.
     84      *
     85      * If key agreement fails, this method will crash the process (with CHECK).
     86      */
     87     static void performHmacKeyAgreement(const KeymasterSet& keymasters);
     88 
     89    private:
     90     hidl_string descriptor_;
     91     hidl_string instanceName_;
     92 };
     93 
     94 std::ostream& operator<<(std::ostream& os, const Keymaster& keymaster);
     95 
     96 }  // namespace support
     97 }  // namespace V4_0
     98 }  // namespace keymaster
     99 }  // namespace hardware
    100 }  // namespace android
    101 
    102 #endif  // HARDWARE_INTERFACES_KEYMASTER_40_SUPPORT_KEYMASTER_H_
    103