1ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales/* 2ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Copyright 2015 The Android Open Source Project 3ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * 4ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Licensed under the Apache License, Version 2.0 (the "License"); 5ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * you may not use this file except in compliance with the License. 6ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * You may obtain a copy of the License at 7ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * 8ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * http://www.apache.org/licenses/LICENSE-2.0 9ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * 10ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Unless required by applicable law or agreed to in writing, software 11ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * distributed under the License is distributed on an "AS IS" BASIS, 12ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * See the License for the specific language governing permissions and 14ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * limitations under the License. 15ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 16ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 177d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales#ifndef GATEKEEPER_H_ 187d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales#define GATEKEEPER_H_ 19ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 20ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales#include <stdint.h> 21b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales#include <UniquePtr.h> 22fa104e1a3bb5e8fed1235b16e64aa88049ecb18aAndres Morales#include <hardware/hw_auth_token.h> 23ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 247d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales#include "gatekeeper_messages.h" 2594b201ee929de7ca8ee01c5b5aac5495ba749a30Andres Morales#include "password_handle.h" 26ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 277d0f0406314df47b7502c3cd72dcefb83ead7132Andres Moralesnamespace gatekeeper { 28ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 2969e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Moralesstruct __attribute__((packed)) failure_record_t { 3069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales uint64_t secure_user_id; 3169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales uint64_t last_checked_timestamp; 3269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales uint32_t failure_counter; 3369e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales}; 3469e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 35ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales/** 367d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales * Base class for gatekeeper implementations. Provides all functionality except 37ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * the ability to create/access keys and compute signatures. These are left up 38ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * to the platform-specific implementation. 39ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 407d0f0406314df47b7502c3cd72dcefb83ead7132Andres Moralesclass GateKeeper { 41ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralespublic: 427d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales GateKeeper() {} 437d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales virtual ~GateKeeper() {} 44ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 45ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales void Enroll(const EnrollRequest &request, EnrollResponse *response); 46ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales void Verify(const VerifyRequest &request, VerifyResponse *response); 47ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 48ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralesprotected: 49ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 50ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales // The following methods are intended to be implemented by concrete subclasses 51ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 52ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 537d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales * Retrieves the key used by GateKeeper::MintAuthToken to sign the payload 54ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * of the AuthToken. This is not cached as is may have changed due to an event such 55ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * as a password change. 56b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 57b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Writes the length in bytes of the returned key to length if it is not null. 58b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 59f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales * Ownership of the auth_token_key pointer is maintained by the implementor. 60f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales * 6158bb246744cf767c3d4aeb65a4fae1207fc4e86bAndres Morales * Returns true if the key was successfully fetched. 6258bb246744cf767c3d4aeb65a4fae1207fc4e86bAndres Morales * 63b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 6458bb246744cf767c3d4aeb65a4fae1207fc4e86bAndres Morales virtual bool GetAuthTokenKey(const uint8_t **auth_token_key, uint32_t *length) 6558bb246744cf767c3d4aeb65a4fae1207fc4e86bAndres Morales const = 0; 6658bb246744cf767c3d4aeb65a4fae1207fc4e86bAndres Morales 67edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 68edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * The key used to sign and verify password data. 69edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 70edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * MUST be different from the AuthTokenKey. 71edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 72edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * GetPasswordKey is not const because unlike AuthTokenKey, 73f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales * this value can be cached. 74f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales * 75f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales * Ownership of the password_key pointer is maintained by the implementor. 76edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 77edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 7811ed52a7139a6c867850113aa19293c05581fcfcAndres Morales virtual void GetPasswordKey(const uint8_t **password_key, uint32_t *length) = 0; 79b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 80b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 81b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Uses platform-specific routines to compute a signature on the provided password. 82b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 83b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * This can be implemented as a simple pass-through to ComputeSignature, but is 84b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * available in case handling for password signatures is different from general 85b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * purpose signatures. 86b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 87edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Writes the signature_length size signature to the 'signature' pointer. 88b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 8911ed52a7139a6c867850113aa19293c05581fcfcAndres Morales virtual void ComputePasswordSignature(uint8_t *signature, uint32_t signature_length, 9011ed52a7139a6c867850113aa19293c05581fcfcAndres Morales const uint8_t *key, uint32_t key_length, const uint8_t *password, 9111ed52a7139a6c867850113aa19293c05581fcfcAndres Morales uint32_t password_length, salt_t salt) const = 0; 92b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 93b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 94edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Retrieves a unique, cryptographically randomly generated buffer for use in password 95edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * hashing, etc. 96b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 97edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Assings the random to the random UniquePtr, relinquishing ownership to the caller 98ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 9911ed52a7139a6c867850113aa19293c05581fcfcAndres Morales virtual void GetRandom(void *random, uint32_t requested_size) const = 0; 100ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 101ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 102ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Uses platform-specific routines to compute a signature on the provided message. 103b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 104edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Writes the signature_length size signature to the 'signature' pointer. 105ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 10611ed52a7139a6c867850113aa19293c05581fcfcAndres Morales virtual void ComputeSignature(uint8_t *signature, uint32_t signature_length, 10711ed52a7139a6c867850113aa19293c05581fcfcAndres Morales const uint8_t *key, uint32_t key_length, const uint8_t *message, 10811ed52a7139a6c867850113aa19293c05581fcfcAndres Morales const uint32_t length) const = 0; 109ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 110ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 111ec9fd1d44227dc0e8538153214eae9e7cedb66abAndres Morales * Get the time since boot in milliseconds. 11211c2a51cab5e4e13590022720b3f8391128ce9d3Andres Morales * 11311c2a51cab5e4e13590022720b3f8391128ce9d3Andres Morales * Should return 0 on error. 11411c2a51cab5e4e13590022720b3f8391128ce9d3Andres Morales */ 115ec9fd1d44227dc0e8538153214eae9e7cedb66abAndres Morales virtual uint64_t GetMillisecondsSinceBoot() const = 0; 116f10e2890fd223d37c024ec2d1b3b89aec8d72d76Andres Morales 11769e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 11869e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns the value of the current failure record for the user. 119b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 12069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * The failure record should be written to hardware-backed secure storage, such as 121b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * RPMB, if the target device supports it. 122b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 123b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * If 'secure' is false, password is operating in a fallback mode. Implementations 124b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * may store the failure record in memory or in non-secure storage if this value is false. 12569e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * 12669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns true on success, false if failure record cannot be retrieved. 12769e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 128b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales virtual bool GetFailureRecord(uint32_t uid, secure_id_t user_id, failure_record_t *record, 129b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales bool secure) = 0; 13069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 13169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 132b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * Initializes or reinitializes the failure record for the current user. 133b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 134b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * Must be persisted in secure storage if the target device supports it. 135b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 136b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * If 'secure' is false, password is operating in a fallback mode. Implementations 137b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * may store the failure record in memory or in non-secure storage if this value is false. 138b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 139b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * Returns true if the failure record was successfully persisted. 14069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 141b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales virtual bool ClearFailureRecord(uint32_t uid, secure_id_t user_id, bool secure) = 0; 14269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 14369e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /* 144b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * Writes the provided failure record to persistent storage. 145b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 146b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * Must be persisted in secure storage if the target device supports it. 147b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 148b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * If 'secure' is false, password is operating in a fallback mode. Implementations 149b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * may store the failure record in memory or in non-secure storage if this value is false. 150b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales * 15169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns true if record was successfully written. 15269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 153b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales virtual bool WriteFailureRecord(uint32_t uid, failure_record_t *record, bool secure) = 0; 15469e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 15569e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 15669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Computes the amount of time to throttle the user due to the current failure_record 15769e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * counter. An implementation is provided by the generic GateKeeper, but may be 15869e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * overriden. 15969e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 16069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales virtual uint32_t ComputeRetryTimeout(const failure_record_t *record); 16169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 16269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 16369e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns whether the GateKeeper implementation is backed by hardware. 16469e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 16569e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales virtual bool IsHardwareBacked() const = 0; 16669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 167e547f93b0089f12c78d33b83e5f49fdb0e0c85bcAndres Morales /** 168e547f93b0089f12c78d33b83e5f49fdb0e0c85bcAndres Morales * Verifies that handle matches password HMAC'ed with the password_key 169e547f93b0089f12c78d33b83e5f49fdb0e0c85bcAndres Morales */ 170e547f93b0089f12c78d33b83e5f49fdb0e0c85bcAndres Morales virtual bool DoVerify(const password_handle_t *expected_handle, const SizedBuffer &password); 171e547f93b0089f12c78d33b83e5f49fdb0e0c85bcAndres Morales 172b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Moralesprivate: 173b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 174b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Generates a signed attestation of an authentication event and assings 175b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * to auth_token UniquePtr. 176fa104e1a3bb5e8fed1235b16e64aa88049ecb18aAndres Morales * The format is consistent with that of hw_auth_token_t. 177b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Also returns the length in length if it is not null. 178b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 179652f076f7fab74dc3159e3f9122ff17eb689dbc2Andres Morales void MintAuthToken(UniquePtr<uint8_t> *auth_token, uint32_t *length, uint64_t timestamp, 1806034309d9caa185c406def66bd4a7b71ea4b6409Andres Morales secure_id_t user_id, secure_id_t authenticator_id, uint64_t challenge); 181b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 182edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 183edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Populates password_handle with the data provided and computes HMAC. 184edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 185edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales bool CreatePasswordHandle(SizedBuffer *password_handle, salt_t salt, 18669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales secure_id_t secure_id, secure_id_t authenticator_id, uint8_t handle_version, 18769e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales const uint8_t *password, uint32_t password_length); 18869e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 18969e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 19069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Increments the counter on the current failure record for the provided user id. 19169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Sets the last_checked_timestamp to timestamp. Writes the updated record 19269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * to *record if not null. 19369e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * 19469e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns true if failure record was successfully incremented. 19569e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 19669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales bool IncrementFailureRecord(uint32_t uid, secure_id_t user_id, uint64_t timestamp, 197b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales failure_record_t *record, bool secure); 19869e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales 19969e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales /** 20069e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Determines whether the request is within the current throttle window. 20169e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * 20269e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * If the system timer has been reset due to a reboot or otherwise, resets 20369e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * the throttle window with a base at the current time. 20469e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * 20569e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales * Returns true if the request is in the throttle window. 20669e7394c569c24f5c6eb81a96ca86e03ac2292efAndres Morales */ 2072c8c44ff73baf019ab5713566517527143ef7608Andres Morales bool ThrottleRequest(uint32_t uid, uint64_t timestamp, 208b6fc8937b2f44e534053dc016a08e59eaba4bfe9Andres Morales failure_record_t *record, bool secure, GateKeeperMessage *response); 209ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales}; 210edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales 211ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales} 212ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 2137d0f0406314df47b7502c3cd72dcefb83ead7132Andres Morales#endif // GATEKEEPER_H_ 214