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 * 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 "2struct.h" 12 13 struct vb2_public_key; 14 15 /* Private key data, in-memory format for use in signing calls. */ 16 struct vb2_private_key { 17 struct rsa_st *rsa_private_key; /* Private key data */ 18 enum vb2_hash_algorithm hash_alg; /* Hash algorithm */ 19 enum vb2_signature_algorithm sig_alg; /* Signature algorithm */ 20 char *desc; /* Description */ 21 struct vb2_guid guid; /* Key GUID */ 22 }; 23 24 /* Convert between enums and human-readable form. Terminated with {0, 0}. */ 25 struct vb2_text_vs_enum { 26 const char *name; 27 unsigned int num; 28 }; 29 30 /** 31 * @param table Table to search 32 * @param num Enum value to search for 33 * @return pointer to table entry or NULL if no match 34 */ 35 const struct vb2_text_vs_enum *vb2_lookup_by_num( 36 const struct vb2_text_vs_enum *table, 37 const unsigned int num); 38 39 /** 40 * @param table Table to search 41 * @param name String value to search for 42 * @return pointer to table entry or NULL if no match 43 */ 44 const struct vb2_text_vs_enum *vb2_lookup_by_name( 45 const struct vb2_text_vs_enum *table, 46 const char *name); 47 48 extern struct vb2_text_vs_enum vb2_text_vs_algorithm[]; 49 extern struct vb2_text_vs_enum vb2_text_vs_sig[]; 50 extern struct vb2_text_vs_enum vb2_text_vs_hash[]; 51 52 /** 53 * Free a private key. 54 * 55 * @param key Key containing internal data to free. 56 */ 57 void vb2_private_key_free(struct vb2_private_key *key); 58 59 /** 60 * Unpack a private key from vb2_packed_private_key format. 61 * 62 * @param key_ptr Destination for newly allocated key; this must be 63 * freed with vb2_private_key_free(). 64 * @param buf Source buffer containing packed key 65 * @param size Size of buffer in bytes 66 * @return VB2_SUCCESS, or non-zero error code if error. 67 */ 68 int vb2_private_key_unpack(struct vb2_private_key **key_ptr, 69 const uint8_t *buf, 70 uint32_t size); 71 72 /** 73 * Read a private key from vb2_packed_private_key format. 74 * 75 * @param key_ptr Destination for newly allocated key; this must be 76 * freed with vb2_private_key_free(). 77 * @param filename File to read key data from. 78 * @return VB2_SUCCESS, or non-zero error code if error. 79 */ 80 int vb2_private_key_read(struct vb2_private_key **key_ptr, 81 const char *filename); 82 83 /** 84 * Read a private key from a .pem file. 85 * 86 * This only reads the internal data for the key. It does not set any of the 87 * other fields in *key_ptr, since those are not contained in the .pem file. 88 * 89 * @param key_ptr Destination for newly allocated key; this must be 90 * freed with vb2_private_key_free(). 91 * @param filename File to read key data from. 92 * @return VB2_SUCCESS, or non-zero error code if error. 93 */ 94 int vb2_private_key_read_pem(struct vb2_private_key **key_ptr, 95 const char *filename); 96 97 /** 98 * Set the description of a private key. 99 * 100 * @param key Key to set description for 101 * @param desc Description string, or NULL if no description. 102 * @return VB2_SUCCESS, or non-zero error code if error. 103 */ 104 int vb2_private_key_set_desc(struct vb2_private_key *key, const char *desc); 105 106 /** 107 * Write a private key to vb2_packed_private_key format. 108 * 109 * @param key Key to write 110 * @param filename File to write key data to. 111 * @return VB2_SUCCESS, or non-zero error code if error. 112 */ 113 int vb2_private_key_write(const struct vb2_private_key *key, 114 const char *filename); 115 116 /** 117 * Get a private key for an unsigned hash 118 * 119 * @param key_ptr Destination for pointer to key. The key is statically 120 * allocated and must not be freed. 121 * @param hash_alg Hash algorithm to use 122 * @return VB2_SUCCESS, or non-zero error code if error. 123 */ 124 int vb2_private_key_hash(const struct vb2_private_key **key_ptr, 125 enum vb2_hash_algorithm hash_alg); 126 127 /** 128 * Allocate a public key buffer of sufficient size for the signature algorithm. 129 * 130 * This only initializes the sig_alg field and the guid field to an empty 131 * guid. It does not set any of the other fields in *key_ptr. 132 * 133 * @param key_ptr Destination for newly allocated key; this must be 134 * freed with vb2_public_key_free(). 135 * @param sig_alg Signature algorithm for key. 136 * @return VB2_SUCCESS, or non-zero error code if error. 137 */ 138 int vb2_public_key_alloc(struct vb2_public_key **key_ptr, 139 enum vb2_signature_algorithm sig_alg); 140 141 /** 142 * Return the packed data for a key allocated with vb2_public_key_alloc(). 143 * 144 * The packed data is in the same buffer, following the key struct and GUID. 145 */ 146 uint8_t *vb2_public_key_packed_data(struct vb2_public_key *key); 147 148 /** 149 * Free a public key allocated by one of the functions below. 150 * 151 * Note that this should ONLY be called for public keys allocated via one 152 * of those functions; public keys created or filled in other ways (such as 153 * vb2_unpack_key()) do not allocate memory for sub-fields in the same way. 154 * 155 * @param key Key to free 156 */ 157 void vb2_public_key_free(struct vb2_public_key *key); 158 159 /** 160 * Read a public key from a .keyb file. 161 * 162 * Guesses the signature algorithm based on the size of the .keyb file. Does 163 * not set the hash_alg, guid, or desc fields, since those are not contained in 164 * the .keyb file. 165 * 166 * @param key_ptr Destination for newly allocated key; this must be 167 * freed with vb2_public_key_free(). 168 * @param filename File to read key from. 169 * @return VB2_SUCCESS, or non-zero error code if error. 170 */ 171 172 int vb2_public_key_read_keyb(struct vb2_public_key **key_ptr, 173 const char *filename); 174 175 /** 176 * Set the description of a public key. 177 * 178 * @param key Key to set description for 179 * @param desc Description string, or NULL if no description. 180 * @return VB2_SUCCESS, or non-zero error code if error. 181 */ 182 int vb2_public_key_set_desc(struct vb2_public_key *key, const char *desc); 183 184 /** 185 * Read a public key in vb2_packed_key format. 186 * 187 * @param key_ptr On success, points to the newly allocated key buffer. 188 * Caller is responsible for calling free() on this. 189 * @return VB2_SUCCESS, or non-zero if error. 190 */ 191 int vb2_packed_key_read(struct vb2_packed_key **key_ptr, 192 const char *filename); 193 194 /** 195 * Pack a public key into vb2_packed_key format. 196 * 197 * @param pubk Public key to pack 198 * @param key_ptr On success, points to a newly allocated packed key 199 * buffer. Caller is responsible for calling free() on 200 * this. 201 * @return VB2_SUCCESS, or non-zero if error. 202 */ 203 int vb2_public_key_pack(struct vb2_packed_key **key_ptr, 204 const struct vb2_public_key *pubk); 205 206 /** 207 * Get a public key for an unsigned hash. 208 * 209 * @param key Destination for key data. 210 * @param hash_alg Hash algorithm to use 211 * @return VB2_SUCCESS, or non-zero error code if error. 212 */ 213 int vb2_public_key_hash(struct vb2_public_key *key, 214 enum vb2_hash_algorithm hash_alg); 215 216 217 /** 218 * Return the signature algorithm implied by the bit length of an RSA key 219 * 220 * @param rsa RSA key 221 * @return vb2 signature algorithm 222 */ 223 enum vb2_signature_algorithm vb2_rsa_sig_alg(struct rsa_st *rsa); 224 225 /** 226 * Write a public key to the vb2_packed_key format. 227 * 228 * @param key Key to write 229 * @param filename File to write key data to. 230 * @return VB2_SUCCESS, or non-zero error code if error. 231 */ 232 int vb2_public_key_write(const struct vb2_public_key *key, 233 const char *filename); 234 235 #endif /* VBOOT_REFERENCE_HOST_KEY2_H_ */ 236