gatekeeper.h revision edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3
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 17b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales#ifndef KEYGUARD_H_ 18b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales#define KEYGUARD_H_ 19ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 20ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales#include <memory> 21ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales#include <stdint.h> 22b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales#include <UniquePtr.h> 23ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 24ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales#include "keyguard_messages.h" 25ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 26ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralesnamespace keyguard { 27ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 28edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Moralestypedef uint64_t secure_id_t; 29edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Moralestypedef uint64_t salt_t; 30edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales 31ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales/** 32ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Data format for an authentication record used to prove 33ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * successful password verification. Consumed by KeyStore 34ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * and keymaster to determine CryptoObject availability. 35edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 36edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * All fields are written in network order. 37ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 38edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Moralesconst uint8_t AUTH_TOKEN_VERSION = 0; 39ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralesstruct __attribute__ ((__packed__)) AuthToken { 40edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales uint8_t auth_token_version = AUTH_TOKEN_VERSION; 41edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales secure_id_t root_secure_user_id; 42edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales secure_id_t auxiliary_secure_user_id; 43edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales uint32_t authenticator_id = 0; 44edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales uint32_t timestamp; 45edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales uint8_t hmac[32]; 46ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales}; 47ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 48edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Moralesstruct password_handle_t; 49edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales 50ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales/** 51ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Base class for keyguard implementations. Provides all functionality except 52ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * the ability to create/access keys and compute signatures. These are left up 53ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * to the platform-specific implementation. 54ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 55b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Moralesclass Keyguard { 56ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralespublic: 57b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales Keyguard() {} 58edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual ~Keyguard() {} 59ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 60ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales void Enroll(const EnrollRequest &request, EnrollResponse *response); 61ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales void Verify(const VerifyRequest &request, VerifyResponse *response); 62ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 63ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Moralesprotected: 64ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 65ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales // The following methods are intended to be implemented by concrete subclasses 66ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 67ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 68b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Retrieves the key used by Keyguard::MintAuthToken to sign the payload 69ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * of the AuthToken. This is not cached as is may have changed due to an event such 70ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * as a password change. 71b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 72b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Assigns the auth token to the auth_token_key UniquePtr, relinquishing ownership 73b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * to the caller. 74b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Writes the length in bytes of the returned key to length if it is not null. 75b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 76b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 77b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales virtual void GetAuthTokenKey(UniquePtr<uint8_t> *auth_token_key, size_t *length) 78b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales const = 0; 79edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 80edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * The key used to sign and verify password data. 81edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 82edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * MUST be different from the AuthTokenKey. 83edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 84edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * GetPasswordKey is not const because unlike AuthTokenKey, 85edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * this value can and should be cached in local memory. The 86edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * 87edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 88edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void GetPasswordKey(UniquePtr<uint8_t> *password_key, size_t *length) = 0; 89b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 90b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 91b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Uses platform-specific routines to compute a signature on the provided password. 92b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 93b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * This can be implemented as a simple pass-through to ComputeSignature, but is 94b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * available in case handling for password signatures is different from general 95b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * purpose signatures. 96b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 97edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Writes the signature_length size signature to the 'signature' pointer. 98b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 99edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void ComputePasswordSignature(uint8_t *signature, size_t signature_length, 100edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales const uint8_t *key, size_t key_length, const uint8_t *password, 101edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales size_t password_length, salt_t salt) const = 0; 102b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 103b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 104edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Retrieves a unique, cryptographically randomly generated buffer for use in password 105edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * hashing, etc. 106b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 107edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Assings the random to the random UniquePtr, relinquishing ownership to the caller 108ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 109edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void GetRandom(void *random, size_t requested_size) const = 0; 110ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 111ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 112ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales * Uses platform-specific routines to compute a signature on the provided message. 113b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * 114edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Writes the signature_length size signature to the 'signature' pointer. 115ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 116edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void ComputeSignature(uint8_t *signature, size_t signature_length, 117edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales const uint8_t *key, size_t key_length, const uint8_t *message, 118edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales const size_t length) const = 0; 119ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 120ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales /** 121edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Write the password file to persistent storage. 122ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales */ 123edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void ReadPasswordFile(uint32_t uid, SizedBuffer *password_file) const = 0; 124edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales 125edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 126edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Read the password file from persistent storage. 127edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 128edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales virtual void WritePasswordFile(uint32_t uid, const SizedBuffer &password_file) const = 0; 129b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 130b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Moralesprivate: 131b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales /** 132b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Generates a signed attestation of an authentication event and assings 133b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * to auth_token UniquePtr. 134b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * The format is consistent with that of AuthToken above. 135b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales * Also returns the length in length if it is not null. 136b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales */ 137edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales void MintAuthToken(UniquePtr<uint8_t> *auth_token, size_t *length, uint32_t timestamp, 138edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales secure_id_t user_id, secure_id_t authenticator_id); 139b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 140edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 141edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Verifies that handle matches password HMAC'ed with the password_key 142edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 143edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales bool DoVerify(const password_handle_t *expected_handle, const SizedBuffer &password); 144b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 145edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 146edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Verifies that the provided handle matches byte-by-byte what was previously 147edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * stored as a result of a call to 'Enroll' 148edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 149edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales bool ValidatePasswordFile(uint32_t uid, const SizedBuffer &provided_handle); 150b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales 151edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales /** 152edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales * Populates password_handle with the data provided and computes HMAC. 153edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales */ 154edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales bool CreatePasswordHandle(SizedBuffer *password_handle, salt_t salt, 155edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales secure_id_t secure_id, secure_id_t authenticator_id, const uint8_t *password, 156edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales size_t password_length); 157ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales}; 158edd3e3dc860ff3d99c0320a6ee7d66347b4dd1c3Andres Morales 159ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales} 160ac80818fd9e477d142dd8ed2f3902ba3757855c9Andres Morales 161b2abaa89b8090c7f14048d4404a3eb146f709a6aAndres Morales#endif // KEYGUARD_H_ 162