auth_token_table.h revision bbc7648d285f67b898d24d307b011fb676ba6643 
1/*
2 * Copyright (C) 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#include <memory>
18#include <vector>
19
20#include <hardware/hw_auth_token.h>
21#include <keymaster/authorization_set.h>
22#include <keymaster/key_blob.h>
23
24#ifndef SYSTEM_KEYMASTER_AUTH_TOKEN_TABLE_H
25#define SYSTEM_KEYMASTER_AUTH_TOKEN_TABLE_H
26
27namespace keymaster {
28
29namespace test {
30class AuthTokenTableTest;
31}  // namespace test
32
33time_t clock_gettime_raw();
34
35/**
36 * AuthTokenTable manages a set of received authorization tokens and can provide the appropriate
37 * token for authorizing a key operation.
38 *
39 * To keep the table from growing without bound, superseded entries are removed when possible, and
40 * least recently used entries are automatically pruned when when the table exceeds a size limit,
41 * which is expected to be relatively small, since the implementation uses a linear search.
42 */
43class AuthTokenTable {
44  public:
45    AuthTokenTable(size_t max_entries = 32, time_t (*clock_function)() = clock_gettime_raw)
46        : max_entries_(max_entries), clock_function_(clock_function) {}
47
48    enum Error {
49        OK,
50        AUTH_NOT_REQUIRED = -1,
51        AUTH_TOKEN_EXPIRED = -2,    // Found a matching token, but it's too old.
52        AUTH_TOKEN_WRONG_SID = -3,  // Found a token with the right challenge, but wrong SID.  This
53                                    // most likely indicates that the authenticator was updated
54                                    // (e.g. new fingerprint enrolled).
55        OP_HANDLE_REQUIRED = -4,    // The key requires auth per use but op_handle was zero.
56        AUTH_TOKEN_NOT_FOUND = -5,
57    };
58
59    /**
60     * Add an authorization token to the table.  The table takes ownership of the argument.
61     */
62    void AddAuthenticationToken(const hw_auth_token_t* token);
63
64    /**
65     * Find an authorization token that authorizes the operation specified by \p operation_handle on
66     * a key with the characteristics specified in \p key_info.
67     *
68     * This method is O(n * m), where n is the number of KM_TAG_USER_SECURE_ID entries in key_info
69     * and m is the number of entries in the table.  It could be made better, but n and m should
70     * always be small.
71     *
72     * The table retains ownership of the returned object.
73     */
74    Error FindAuthorization(const AuthorizationSet& key_info,
75                            keymaster_operation_handle_t op_handle, const hw_auth_token_t** found);
76
77    /**
78     * Find an authorization token that authorizes the operation specified by \p operation_handle on
79     * a key with the characteristics specified in \p key_info.
80     *
81     * This method is O(n * m), where n is the number of KM_TAG_USER_SECURE_ID entries in key_info
82     * and m is the number of entries in the table.  It could be made better, but n and m should
83     * always be small.
84     *
85     * The table retains ownership of the returned object.
86     */
87    Error FindAuthorization(const keymaster_key_param_t* params, size_t params_count,
88                            keymaster_operation_handle_t op_handle, const hw_auth_token_t** found) {
89        return FindAuthorization(AuthorizationSet(params, params_count), op_handle, found);
90    }
91
92    /**
93     * Mark operation completed.  This allows tokens associated with the specified operation to be
94     * superseded by new tokens.
95     */
96    void MarkCompleted(const keymaster_operation_handle_t op_handle);
97
98    void Clear();
99
100    size_t size() { return entries_.size(); }
101
102  private:
103    friend class AuthTokenTableTest;
104
105    class Entry {
106      public:
107        Entry(const hw_auth_token_t* token, time_t current_time);
108        Entry(Entry&& entry) { *this = std::move(entry); }
109
110        void operator=(Entry&& rhs) {
111            token_ = std::move(rhs.token_);
112            time_received_ = rhs.time_received_;
113            last_use_ = rhs.last_use_;
114            operation_completed_ = rhs.operation_completed_;
115        }
116
117        bool operator<(const Entry& rhs) const { return last_use_ < rhs.last_use_; }
118
119        void UpdateLastUse(time_t time);
120
121        bool Supersedes(const Entry& entry) const;
122        bool SatisfiesAuth(const std::vector<uint64_t>& sids, hw_authenticator_type_t auth_type);
123
124        bool is_newer_than(const Entry* entry) {
125            if (!entry)
126                return true;
127            return timestamp_host_order() > entry->timestamp_host_order();
128        }
129
130        void mark_completed() { operation_completed_ = true; }
131
132        const hw_auth_token_t* token() { return token_.get(); }
133        time_t time_received() const { return time_received_; }
134        bool completed() const { return operation_completed_; }
135        uint32_t timestamp_host_order() const;
136        hw_authenticator_type_t authenticator_type() const;
137
138      private:
139        std::unique_ptr<const hw_auth_token_t> token_;
140        time_t time_received_;
141        time_t last_use_;
142        bool operation_completed_;
143    };
144
145    Error FindAuthPerOpAuthorization(const std::vector<uint64_t>& sids,
146                                     hw_authenticator_type_t auth_type,
147                                     keymaster_operation_handle_t op_handle,
148                                     const hw_auth_token_t** found);
149    Error FindTimedAuthorization(const std::vector<uint64_t>& sids,
150                                 hw_authenticator_type_t auth_type,
151                                 const AuthorizationSet& key_info, const hw_auth_token_t** found);
152    void ExtractSids(const AuthorizationSet& key_info, std::vector<uint64_t>* sids);
153    void RemoveEntriesSupersededBy(const Entry& entry);
154    bool IsSupersededBySomeEntry(const Entry& entry);
155
156    std::vector<Entry> entries_;
157    size_t max_entries_;
158    time_t (*clock_function_)();
159};
160
161}  // namespace keymaster
162
163#endif  // SYSTEM_KEYMASTER_AUTH_TOKEN_TABLE_H
164