1 /* Copyright 2014 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * Host-side functions for verified boot key structures 6 */ 7 8 #ifndef VBOOT_REFERENCE_HOST_KEY2_H_ 9 #define VBOOT_REFERENCE_HOST_KEY2_H_ 10 11 #include "2id.h" 12 #include "2return_codes.h" 13 #include "2struct.h" 14 15 struct pkcs11_key; 16 struct vb2_public_key; 17 struct vb21_packed_key; 18 19 /* Location of private key */ 20 enum private_key_location { 21 PRIVATE_KEY_LOCAL = 0, 22 PRIVATE_KEY_P11, 23 }; 24 25 /* Private key data, in-memory format for use in signing calls. */ 26 struct vb2_private_key { 27 enum private_key_location key_location; /* Key location */ 28 union { 29 struct rsa_st *rsa_private_key; /* Local private key*/ 30 struct pkcs11_key *p11_key; /* PKCS#11 private key */ 31 }; 32 enum vb2_hash_algorithm hash_alg; /* Hash algorithm */ 33 enum vb2_signature_algorithm sig_alg; /* Signature algorithm */ 34 char *desc; /* Description */ 35 struct vb2_id id; /* Key ID */ 36 }; 37 38 struct vb2_packed_private_key { 39 /* Signature algorithm used by the key (enum vb2_crypto_algorithm) */ 40 uint32_t algorithm; 41 uint32_t reserved2; 42 /* Key data formatted for d2i_RSAPrivateKey() */ 43 uint8_t key_data[0]; 44 }; 45 46 /** 47 * Unpack a private key from vb21_packed_private_key format. 48 * 49 * @param key_ptr Destination for newly allocated key; this must be 50 * freed with vb2_free_private_key(). 51 * @param buf Source buffer containing packed key 52 * @param size Size of buffer in bytes 53 * @return VB2_SUCCESS, or non-zero error code if error. 54 */ 55 vb2_error_t vb21_private_key_unpack(struct vb2_private_key **key_ptr, 56 const uint8_t *buf, uint32_t size); 57 58 /** 59 * Unpack a private key from vb21_packed_private_key format. 60 * 61 * @param buf Source buffer containing packed key 62 * @param size Size of buffer in bytes 63 * @param key Unpacked key 64 * @return VB2_SUCCESS, or non-zero error code if error. 65 */ 66 vb2_error_t vb21_private_key_unpack_raw(const uint8_t *buf, uint32_t size, 67 struct vb2_private_key *key); 68 69 /** 70 * Read a private key from a .pem file. 71 * 72 * This only reads the internal data for the key. It does not set any of the 73 * other fields in *key_ptr, since those are not contained in the .pem file. 74 * 75 * @param key_ptr Destination for newly allocated key; this must be 76 * freed with vb2_free_private_key(). 77 * @param filename File to read key data from. 78 * @return VB2_SUCCESS, or non-zero error code if error. 79 */ 80 vb2_error_t vb2_private_key_read_pem(struct vb2_private_key **key_ptr, 81 const char *filename); 82 83 /** 84 * Set the description of a private key. 85 * 86 * @param key Key to set description for 87 * @param desc Description string, or NULL if no description. 88 * @return VB2_SUCCESS, or non-zero error code if error. 89 */ 90 vb2_error_t vb2_private_key_set_desc(struct vb2_private_key *key, 91 const char *desc); 92 93 /** 94 * Write a private key to vb21_packed_private_key format. 95 * 96 * @param key Key to write 97 * @param filename File to write key data to. 98 * @return VB2_SUCCESS, or non-zero error code if error. 99 */ 100 vb2_error_t vb21_private_key_write(const struct vb2_private_key *key, 101 const char *filename); 102 103 /** 104 * Get a private key for an unsigned hash 105 * 106 * @param key_ptr Destination for pointer to key. The key is statically 107 * allocated and must not be freed. 108 * @param hash_alg Hash algorithm to use 109 * @return VB2_SUCCESS, or non-zero error code if error. 110 */ 111 vb2_error_t vb2_private_key_hash(const struct vb2_private_key **key_ptr, 112 enum vb2_hash_algorithm hash_alg); 113 114 /** 115 * Allocate a public key buffer of sufficient size for the signature algorithm. 116 * 117 * This only initializes the sig_alg field and the id field to an empty 118 * id. It does not set any of the other fields in *key_ptr. 119 * 120 * @param key_ptr Destination for newly allocated key; this must be 121 * freed with vb2_public_key_free(). 122 * @param sig_alg Signature algorithm for key. 123 * @return VB2_SUCCESS, or non-zero error code if error. 124 */ 125 vb2_error_t vb2_public_key_alloc(struct vb2_public_key **key_ptr, 126 enum vb2_signature_algorithm sig_alg); 127 128 /** 129 * Return the packed data for a key allocated with vb2_public_key_alloc(). 130 * 131 * The packed data is in the same buffer, following the key struct and ID. 132 */ 133 uint8_t *vb2_public_key_packed_data(struct vb2_public_key *key); 134 135 /** 136 * Free a public key allocated by one of the functions below. 137 * 138 * Note that this should ONLY be called for public keys allocated via one 139 * of those functions; public keys created or filled in other ways (such as 140 * vb21_unpack_key()) do not allocate memory for sub-fields in the same way. 141 * 142 * @param key Key to free 143 */ 144 void vb2_public_key_free(struct vb2_public_key *key); 145 146 /** 147 * Read a public key from a .keyb file. 148 * 149 * Guesses the signature algorithm based on the size of the .keyb file. Does 150 * not set the hash_alg, id, or desc fields, since those are not contained in 151 * the .keyb file. 152 * 153 * @param key_ptr Destination for newly allocated key; this must be 154 * freed with vb2_public_key_free(). 155 * @param filename File to read key from. 156 * @return VB2_SUCCESS, or non-zero error code if error. 157 */ 158 159 vb2_error_t vb2_public_key_read_keyb(struct vb2_public_key **key_ptr, 160 const char *filename); 161 162 /** 163 * Set the description of a public key. 164 * 165 * @param key Key to set description for 166 * @param desc Description string, or NULL if no description. 167 * @return VB2_SUCCESS, or non-zero error code if error. 168 */ 169 vb2_error_t vb2_public_key_set_desc(struct vb2_public_key *key, 170 const char *desc); 171 172 /** 173 * Read a public key in vb21_packed_key format. 174 * 175 * @param key_ptr On success, points to the newly allocated key buffer. 176 * Caller is responsible for calling free() on this. 177 * @return VB2_SUCCESS, or non-zero if error. 178 */ 179 vb2_error_t vb21_packed_key_read(struct vb21_packed_key **key_ptr, 180 const char *filename); 181 182 /** 183 * Pack a public key into vb21_packed_key format. 184 * 185 * @param pubk Public key to pack 186 * @param key_ptr On success, points to a newly allocated packed key 187 * buffer. Caller is responsible for calling free() on 188 * this. 189 * @return VB2_SUCCESS, or non-zero if error. 190 */ 191 vb2_error_t vb21_public_key_pack(struct vb21_packed_key **key_ptr, 192 const struct vb2_public_key *pubk); 193 194 /** 195 * Get a public key for an unsigned hash. 196 * 197 * @param key Destination for key data. 198 * @param hash_alg Hash algorithm to use 199 * @return VB2_SUCCESS, or non-zero error code if error. 200 */ 201 vb2_error_t vb2_public_key_hash(struct vb2_public_key *key, 202 enum vb2_hash_algorithm hash_alg); 203 204 205 /** 206 * Return the signature algorithm implied by the bit length of an RSA key 207 * 208 * @param rsa RSA key 209 * @return vb2 signature algorithm 210 */ 211 enum vb2_signature_algorithm vb2_rsa_sig_alg(struct rsa_st *rsa); 212 213 /** 214 * Write a public key to the vb21_packed_key format. 215 * 216 * @param key Key to write 217 * @param filename File to write key data to. 218 * @return VB2_SUCCESS, or non-zero error code if error. 219 */ 220 vb2_error_t vb21_public_key_write(const struct vb2_public_key *key, 221 const char *filename); 222 223 /** 224 * Unpack a key for use in verification 225 * 226 * The elements of the unpacked key will point into the source buffer, so don't 227 * free the source buffer until you're done with the key. 228 * 229 * @param key Destintion for unpacked key 230 * @param buf Source buffer containing packed key 231 * @param size Size of buffer in bytes 232 * @return VB2_SUCCESS, or non-zero error code if error. 233 */ 234 vb2_error_t vb21_unpack_key(struct vb2_public_key *key, const uint8_t *buf, 235 uint32_t size); 236 237 #endif /* VBOOT_REFERENCE_HOST_KEY2_H_ */ 238