• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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