1 /* 2 * Copyright (C) 2021 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 #pragma once 18 19 #include <stdint.h> 20 21 /** 22 * DOC: Theory of operation 23 * 24 * The Hardware wrapped Storage Key IPC interface (HWWSK) is designed to 25 * operate in conjunction with Keymaster application implementing support for 26 * AES keys having TAG_STORAGE_KEY attribute set. 27 * 28 * This interface provides a facility to implement such support in a hardware 29 * dependant way without making modification to Keymaster app itself. When 30 * support for HWWSK service is enabled for Keymaster app, the Keymaster 31 * requests to generate/import/export AES key with TAG_STORAGE_KEY will be 32 * redirected to this interface to produce opaque key blob which will be in 33 * turn wrapped by Keymaster. 34 * 35 * This interface supports the following commands: 36 * 37 * @HWWSK_GENERATE_KEY: to create a new hardware wrapped key blob containing 38 * HWWSK key. The resulting key blob must be persistent, it is suitable to be 39 * stored offline and should reusable across reset. 40 * 41 * @HWWSK_EXPORT_KEY: convert the persistent HWWSK key obtained by invoking 42 * %HWWSK_GENERATE_KEY command to format suitable for loading into some sort of 43 * HW key slot by appropriate SW component. It is beyond the scope of this 44 * interface how such transformation is performed or how the resulting key blob 45 * is delivered to SW component that is capable to load it into HW block. It is 46 * not expected that resulting key blob has persistent property, as a matter of 47 * fact it is highly desirable to design this format and transformation in such 48 * way that it is only good for current session and becomes invalid across 49 * reboots. 50 * 51 * The client interact with service implementing this interface by sending IPC 52 * message over connection opened to %HWWSK_PORT then waiting for and receiving 53 * response message. All commands defined by this interface follow the same 54 * structure. The message starts with common &struct hwwsk_req_hdr header, 55 * followed by (optional depending on command) request specific header, 56 * followed by request specific data. The server sends reply message started 57 * with &struct hwwsk_rsp_hdr header followed by command specify opaque key 58 * blob. 59 */ 60 61 /* Port name for HWWSK service */ 62 #define HWWSK_PORT "com.android.trusty.hwwsk" 63 64 /* Max message size supported by this service */ 65 #define HWWSK_MAX_MSG_SIZE 1024 66 67 /** 68 * enum hwwsk_cmd - command ID 69 * 70 * @HWWSK_CMD_RESP: added to cmd field of &struct hwwsk_rsp_hdr structure 71 * when sending response message. 72 * 73 * @HWWSK_CMD_GENERATE_KEY: creates new persistent hardware wrapped storage key 74 * by either creating new random key or importing (mostly for test purpose) 75 * caller specified raw key data. The server should expect a request message in 76 * the following format: the message starts with &struct hwwsk_req_hdr header 77 * followed by &struct hwwsk_generate_key_req header followed by raw key 78 * data for import operation or no data for create operation. The server shall 79 * send a response message in the following format: the message starts with 80 * &struct hwwsk_rsp_hdr header followed by created blob. The server should 81 * only send blob if operation is successful. 82 * 83 * @HWWSK_CMD_EXPORT_KEY: converts specified persistent HWWSK key to format 84 * suitable for loading into underlying hardware block. The server should 85 * expect a request in the following format: the message starts with &struct 86 * hwwsk_req_hdr header followed by blob of data previously obtained by 87 * @HWWSK_CMD_GENERATE_KEY command. The server shall send a response message 88 * in the following format: the message starts with &struct hwwsk_rsp_hdr 89 * header followed by created blob. 90 */ 91 enum hwwsk_cmd { 92 HWWSK_CMD_RESP = (1U << 31), 93 HWWSK_CMD_GENERATE_KEY = 1, 94 HWWSK_CMD_EXPORT_KEY = 2, 95 }; 96 97 /** 98 * enum hwwsk_err - error codes for HWWSK protocol 99 * @HWWSK_NO_ERROR: no error 100 * @HWWSK_ERR_GENERIC: unknown error. Can occur when there's an internal 101 * server error, e.g. the server runs out of memory or is 102 * in a bad state. 103 * @HWWSK_ERR_INVALID_ARGS: an invalid command or command parameter specified 104 * @HWWSK_ERR_BAD_LEN: unexpected or unaccepted buffer or data length. 105 * @HWWSK_ERR_NOT_SUPPORTED: requested command or specified parameter is not 106 * supported 107 */ 108 enum hwwsk_err { 109 HWWSK_NO_ERROR = 0, 110 HWWSK_ERR_GENERIC = 1, 111 HWWSK_ERR_INVALID_ARGS = 2, 112 HWWSK_ERR_BAD_LEN = 3, 113 HWWSK_ERR_NOT_SUPPORTED = 4, 114 }; 115 116 /** 117 * enum hwwsk_key_flags - additional key attributes 118 * @HWWSK_FLAGS_ROLLBACK_RESISTANCE: indicates that resulting key must be 119 * rollback resistant 120 * 121 * A combinations of flags defined here can be passed to @HWWSK_GENERATE_KEY 122 * request to specify additional properties of generated key blob. The 123 * underlying implementation must return an error if specified property is not 124 * supported. 125 */ 126 enum hwwsk_key_flags { 127 HWWSK_FLAGS_ROLLBACK_RESISTANCE = (0x1 << 0), 128 }; 129 130 /** 131 * struct hwwsk_req_hdr - common header for all HWWSK requests 132 * @cmd: one of @enum hwwsk_cmd values (excluding HWWSK_CMD_RESP) 133 * @flags: reserved should be 0 134 */ 135 struct hwwsk_req_hdr { 136 uint32_t cmd; 137 uint32_t flags; 138 }; 139 140 /** 141 * struct hwwsk_rsp_hdr - common header for all HWWSK responses 142 * @cmd: command server is replying to with HWWSK_CMD_RESP bit set 143 * @status: one of &enum hwwsk_err value indicating command execution result 144 */ 145 struct hwwsk_rsp_hdr { 146 uint32_t cmd; 147 uint32_t status; 148 }; 149 150 /** 151 * struct hwwsk_generate_key_req - generate HWWSK key request 152 * @key_size: underlying key size (in bits) to generate 153 * @key_flags: a combination of &enum hwwsk_key_flags specifying 154 * additional properties of generated key. 155 */ 156 struct hwwsk_generate_key_req { 157 uint32_t key_size; 158 uint32_t key_flags; 159 }; 160