1b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden/* 2b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Copyright (C) 2014 The Android Open Source Project 3b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * 4b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Licensed under the Apache License, Version 2.0 (the "License"); 5b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * you may not use this file except in compliance with the License. 6b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * You may obtain a copy of the License at 7b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * 8b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * http://www.apache.org/licenses/LICENSE-2.0 9b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * 10b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Unless required by applicable law or agreed to in writing, software 11b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * distributed under the License is distributed on an "AS IS" BASIS, 12b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * See the License for the specific language governing permissions and 14b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * limitations under the License. 15b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 16b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 17b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden#ifndef ANDROID_LIBRARY_KEYMASTER_ENFORCEMENT_H 18b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden#define ANDROID_LIBRARY_KEYMASTER_ENFORCEMENT_H 19b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 20b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden#include <stdio.h> 21b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 22b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden#include <keymaster/authorization_set.h> 23b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 24b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willdennamespace keymaster { 25b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 26b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willdentypedef uint64_t km_id_t; 27b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 28b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willdenclass KeymasterEnforcementContext { 29b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden public: 30b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual ~KeymasterEnforcementContext() {} 31b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 32b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Get current time. 33b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 34b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden}; 35b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 36ada4850659d484dd5ece26dde73072bef16c1517Shawn Willdenclass AccessTimeMap; 37ada4850659d484dd5ece26dde73072bef16c1517Shawn Willdenclass AccessCountMap; 38b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 39ada4850659d484dd5ece26dde73072bef16c1517Shawn Willdenclass KeymasterEnforcement { 40b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden public: 41b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /** 42ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden * Construct a KeymasterEnforcement. 43b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 44ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden KeymasterEnforcement(uint32_t max_access_time_map_size, uint32_t max_access_count_map_size); 45ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden virtual ~KeymasterEnforcement(); 46b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 47b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /** 48b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Iterates through the authorization set and returns the corresponding keymaster error. Will 49b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * return KM_ERROR_OK if all criteria is met for the given purpose in the authorization set with 50b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * the given operation params and handle. Used for encrypt, decrypt sign, and verify. 51b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 52b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden keymaster_error_t AuthorizeOperation(const keymaster_purpose_t purpose, const km_id_t keyid, 53b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden const AuthorizationSet& auth_set, 54b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden const AuthorizationSet& operation_params, 55b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden keymaster_operation_handle_t op_handle, 56b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden bool is_begin_operation); 57b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 58b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /** 59bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * Iterates through the authorization set and returns the corresponding keymaster error. Will 60bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * return KM_ERROR_OK if all criteria is met for the given purpose in the authorization set with 61bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * the given operation params. Used for encrypt, decrypt sign, and verify. 62bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden */ 63bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_error_t AuthorizeBegin(const keymaster_purpose_t purpose, const km_id_t keyid, 64bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden const AuthorizationSet& auth_set, 65bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden const AuthorizationSet& operation_params); 66bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden 67bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden /** 68bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * Iterates through the authorization set and returns the corresponding keymaster error. Will 69bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * return KM_ERROR_OK if all criteria is met for the given purpose in the authorization set with 70bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * the given operation params and handle. Used for encrypt, decrypt sign, and verify. 71bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden */ 72bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_error_t AuthorizeUpdate(const AuthorizationSet& auth_set, 73bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden const AuthorizationSet& operation_params, 74bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_operation_handle_t op_handle) { 75bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden return AuthorizeUpdateOrFinish(auth_set, operation_params, op_handle); 76bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden } 77bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden 78bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden /** 79bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * Iterates through the authorization set and returns the corresponding keymaster error. Will 80bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * return KM_ERROR_OK if all criteria is met for the given purpose in the authorization set with 81bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden * the given operation params and handle. Used for encrypt, decrypt sign, and verify. 82bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden */ 83bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_error_t AuthorizeFinish(const AuthorizationSet& auth_set, 84bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden const AuthorizationSet& operation_params, 85bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_operation_handle_t op_handle) { 86bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden return AuthorizeUpdateOrFinish(auth_set, operation_params, op_handle); 87bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden } 88bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden 89bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden /** 90b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Creates a key ID for use in subsequent calls to AuthorizeOperation. Clients needn't use this 91b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * method of creating key IDs, as long as they use something consistent and unique. This method 92b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * hashes the key blob. 93b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * 94b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Returns false if an error in the crypto library prevents creation of an ID. 95b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 96b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden static bool CreateKeyId(const keymaster_key_blob_t& key_blob, km_id_t* keyid); 97b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 98b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // 99b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // Methods that must be implemented by subclasses 100b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // 101b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // The time-related methods address the fact that different enforcement contexts may have 102b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // different time-related capabilities. In particular: 103b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // 104b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // - They may or may not be able to check dates against real-world clocks. 105b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // 106b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // - They may or may not be able to check timestampls against authentication trustlets (minters 107b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // of hw_auth_token_t structs). 108b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // 109b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // - They must have some time source for relative times, but may not be able to provide more 110b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden // than reliability and monotonicity. 111b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 112b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 113b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Returns true if the specified activation date has passed, or if activation cannot be 114b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * enforced. 115b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 116b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual bool activation_date_valid(uint64_t activation_date) const = 0; 117b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 118b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 119b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Returns true if the specified expiration date has passed. Returns false if it has not, or if 120b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * expiration cannot be enforced. 121b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 122b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual bool expiration_date_passed(uint64_t expiration_date) const = 0; 123b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 124b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 125b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Returns true if the specified auth_token is older than the specified timeout. 126b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 127b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual bool auth_token_timed_out(const hw_auth_token_t& token, uint32_t timeout) const = 0; 128b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 129b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 130b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Get current time in seconds from some starting point. This value is used to compute relative 131b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * times between events. It must be monotonically increasing, and must not skip or lag. It 132b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * need not have any relation to any external time standard (other than the duration of 133b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * "second"). 134b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * 135b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * On POSIX systems, it's recommented to use clock_gettime(CLOCK_MONOTONIC, ...) to implement 136b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * this method. 137b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 138b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual uint32_t get_current_time() const = 0; 139b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 140b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden /* 141b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * Returns true if the specified auth_token has a valid signature, or if signature validation is 142b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden * not available. 143b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden */ 144b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden virtual bool ValidateTokenSignature(const hw_auth_token_t& token) const = 0; 145b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 146b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden private: 147bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_error_t AuthorizeUpdateOrFinish(const AuthorizationSet& auth_set, 148bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden const AuthorizationSet& operation_params, 149bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden keymaster_operation_handle_t op_handle); 150bf9fa99611e64aa797c10d5458624ed93cc4f50bShawn Willden 151b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden bool MinTimeBetweenOpsPassed(uint32_t min_time_between, const km_id_t keyid); 152b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden bool MaxUsesPerBootNotExceeded(const km_id_t keyid, uint32_t max_uses); 153b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden bool AuthTokenMatches(const AuthorizationSet& auth_set, 154b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden const AuthorizationSet& operation_params, const uint64_t user_secure_id, 155b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden const int auth_type_index, const int auth_timeout_index, 156b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden const keymaster_operation_handle_t op_handle, 157b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden bool is_begin_operation) const; 158b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 159ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden AccessTimeMap* access_time_map_; 160ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden AccessCountMap* access_count_map_; 161b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden}; 162ada4850659d484dd5ece26dde73072bef16c1517Shawn Willden 163b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden}; /* namespace keymaster */ 164b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden 165b5508298cdb1d42eaf8c81aa8a6ac2cbfdeef3c7Shawn Willden#endif // ANDROID_LIBRARY_KEYMASTER_ENFORCEMENT_H 166