1 /* Copyright (c) 2014 The Chromium OS Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * Common functions between firmware and kernel verified boot. 6 */ 7 8 #ifndef VBOOT_REFERENCE_VB2_COMMON_H_ 9 #define VBOOT_REFERENCE_VB2_COMMON_H_ 10 11 #include "2common.h" 12 #include "2return_codes.h" 13 #include "2struct.h" 14 #include "vb2_struct.h" 15 16 /** 17 * Return the description of an object starting with a vb2_struct_common header. 18 * 19 * Does not sanity-check the buffer; merely returns the pointer. 20 * 21 * @param buf Pointer to common object 22 * @return A pointer to description or an empty string if none. 23 */ 24 const char *vb2_common_desc(const void *buf); 25 26 /** 27 * Verify the common struct header is fully contained in its parent data 28 * 29 * Also verifies the description is either zero-length or null-terminated. 30 * 31 * @param parent Parent data 32 * @param parent_size Parent size in bytes 33 * @return VB2_SUCCESS, or non-zero if error. 34 */ 35 int vb2_verify_common_header(const void *parent, uint32_t parent_size); 36 37 /** 38 * Verify a member is within the data for a parent object 39 * 40 * @param parent Parent data (starts with struct vb2_struct_common) 41 * @param min_offset Pointer to minimum offset where member can be located. 42 * If this offset is 0 on input, uses the size of the 43 * fixed header (and description, if any). This will be 44 * updated on return to the end of the passed member. On 45 * error, the value of min_offset is undefined. 46 * @param member_offset Offset of member data from start of parent, in bytes 47 * @param member_size Size of member data, in bytes 48 * @return VB2_SUCCESS, or non-zero if error. 49 */ 50 int vb2_verify_common_member(const void *parent, 51 uint32_t *min_offset, 52 uint32_t member_offset, 53 uint32_t member_size); 54 55 /** 56 * Verify a member which starts with a common header is within the parent 57 * 58 * This does not verify the contents of the member or its header, only that the 59 * member's claimed total size fits within the parent's claimed total size at 60 * the specified offset. 61 * 62 * @param parent Parent data (starts with struct vb2_struct_common) 63 * @param min_offset Pointer to minimum offset where member can be located. 64 * If this offset is 0 on input, uses the size of the 65 * fixed header (and description, if any). This will be 66 * updated on return to the end of the passed member. On 67 * error, the value of min_offset is undefined. 68 * @param member_offset Offset of member data from start of parent, in bytes. 69 * This should be the start of the common header of the 70 * member. 71 * @return VB2_SUCCESS, or non-zero if error. 72 */ 73 int vb2_verify_common_subobject(const void *parent, 74 uint32_t *min_offset, 75 uint32_t member_offset); 76 77 /** 78 * Unpack a key for use in verification 79 * 80 * The elements of the unpacked key will point into the source buffer, so don't 81 * free the source buffer until you're done with the key. 82 * 83 * @param key Destintion for unpacked key 84 * @param buf Source buffer containing packed key 85 * @param size Size of buffer in bytes 86 * @return VB2_SUCCESS, or non-zero error code if error. 87 */ 88 int vb2_unpack_key(struct vb2_public_key *key, 89 const uint8_t *buf, 90 uint32_t size); 91 92 /** 93 * Unpack the RSA data fields for a public key 94 * 95 * This is called by vb2_unpack_key() to extract the arrays from a packed key. 96 * These elements of *key will point inside the key_data buffer. 97 * 98 * @param key Destination key for RSA data fields 99 * @param key_data Packed key data (from inside a packed key buffer) 100 * @param key_size Size of packed key data in bytes 101 */ 102 int vb2_unpack_key_data(struct vb2_public_key *key, 103 const uint8_t *key_data, 104 uint32_t key_size); 105 106 /** 107 * Verify the integrity of a signature struct 108 * @param sig Signature struct 109 * @param size Size of buffer containing signature struct 110 * @return VB2_SUCCESS, or non-zero if error. 111 */ 112 int vb2_verify_signature(const struct vb2_signature *sig, 113 uint32_t size); 114 115 /** 116 * Verify a signature against an expected hash digest. 117 * 118 * @param key Key to use in signature verification 119 * @param sig Signature to verify (may be destroyed in process) 120 * @param digest Digest of signed data 121 * @param wb Work buffer 122 * @return VB2_SUCCESS, or non-zero if error. 123 */ 124 int vb2_verify_digest(const struct vb2_public_key *key, 125 struct vb2_signature *sig, 126 const uint8_t *digest, 127 const struct vb2_workbuf *wb); 128 129 /** 130 * Verify data matches signature. 131 * 132 * @param data Data to verify 133 * @param size Size of data buffer. Note that amount of data to 134 * actually validate is contained in sig->data_size. 135 * @param sig Signature of data (destroyed in process) 136 * @param key Key to use to validate signature 137 * @param wb Work buffer 138 * @return VB2_SUCCESS, or non-zero error code if error. 139 */ 140 int vb2_verify_data(const void *data, 141 uint32_t size, 142 struct vb2_signature *sig, 143 const struct vb2_public_key *key, 144 const struct vb2_workbuf *wb); 145 146 /** 147 * Check the sanity of a key block using a public key. 148 * 149 * Header fields are also checked for sanity. Does not verify key index or key 150 * block flags. Signature inside block is destroyed during check. 151 * 152 * @param block Key block to verify 153 * @param size Size of key block buffer 154 * @param key Key to use to verify block 155 * @param wb Work buffer 156 * @return VB2_SUCCESS, or non-zero error code if error. 157 */ 158 int vb2_verify_keyblock(struct vb2_keyblock *block, 159 uint32_t size, 160 const struct vb2_public_key *key, 161 const struct vb2_workbuf *wb); 162 163 /** 164 * Check the sanity of a firmware preamble using a public key. 165 * 166 * The signature in the preamble is destroyed during the check. 167 * 168 * @param preamble Preamble to verify 169 * @param size Size of preamble buffer 170 * @param key Key to use to verify preamble 171 * @param wb Work buffer 172 * @return VB2_SUCCESS, or non-zero error code if error. 173 */ 174 int vb2_verify_fw_preamble(struct vb2_fw_preamble *preamble, 175 uint32_t size, 176 const struct vb2_public_key *key, 177 const struct vb2_workbuf *wb); 178 179 #endif /* VBOOT_REFERENCE_VB2_COMMON_H_ */ 180
