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