e4c6ad0c36d1098dec65a8796b259a9a2f509d04
[akaros.git] / kern / include / crypto / 2api.h
1 /* Copyright (c) 2013 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
6 /* APIs between calling firmware and vboot_reference
7  *
8  * General notes:
9  *
10  * TODO: split this file into a vboot_entry_points.h file which contains the
11  * entry points for the firmware to call vboot_reference, and a
12  * vboot_firmware_exports.h which contains the APIs to be implemented by the
13  * calling firmware and exported to vboot_reference.
14  *
15  * Notes:
16  *    * Assumes this code is never called in the S3 resume path.  TPM resume
17  *      must be done elsewhere, and VB2_NV_DEBUG_RESET_MODE is ignored.
18  */
19
20 #ifndef VBOOT_2_API_H_
21 #define VBOOT_2_API_H_
22 #include <stdint.h>
23
24 #include "2common.h"
25 #include "2crypto.h"
26 #include "2fw_hash_tags.h"
27 #include "2id.h"
28 #include "2recovery_reasons.h"
29 #include "2return_codes.h"
30
31 /* Size of non-volatile data used by vboot */
32 #define VB2_NVDATA_SIZE 16
33
34 /* Size of secure data spaces used by vboot */
35 #define VB2_SECDATA_SIZE 10
36 #define VB2_SECDATAK_SIZE 14
37
38 /*
39  * Recommended size of work buffer for firmware verification stage
40  *
41  * TODO: The recommended size really depends on which key algorithms are
42  * used.  Should have a better / more accurate recommendation than this.
43  */
44 #define VB2_WORKBUF_RECOMMENDED_SIZE (12 * 1024)
45
46 /*
47  * Recommended size of work buffer for kernel verification stage
48  *
49  * This is bigger because vboot 2.0 kernel preambles are usually padded to
50  * 64 KB.
51  *
52  * TODO: The recommended size really depends on which key algorithms are
53  * used.  Should have a better / more accurate recommendation than this.
54  */
55 #define VB2_KERNEL_WORKBUF_RECOMMENDED_SIZE (80 * 1024)
56
57 /* Recommended buffer size for vb2api_get_pcr_digest */
58 #define VB2_PCR_DIGEST_RECOMMENDED_SIZE 32
59
60 /* Flags for vb2_context.
61  *
62  * Unless otherwise noted, flags are set by verified boot and may be read (but
63  * not set or cleared) by the caller.
64  */
65 enum vb2_context_flags {
66
67         /*
68          * Verified boot has changed nvdata[].  Caller must save nvdata[] back
69          * to its underlying storage, then may clear this flag.
70          */
71         VB2_CONTEXT_NVDATA_CHANGED = (1 << 0),
72
73         /*
74          * Verified boot has changed secdata[].  Caller must save secdata[]
75          * back to its underlying storage, then may clear this flag.
76          */
77         VB2_CONTEXT_SECDATA_CHANGED = (1 << 1),
78
79         /* Recovery mode is requested this boot */
80         VB2_CONTEXT_RECOVERY_MODE = (1 << 2),
81
82         /* Developer mode is requested this boot */
83         VB2_CONTEXT_DEVELOPER_MODE = (1 << 3),
84
85         /*
86          * Force recovery mode due to physical user request.  Caller may set
87          * this flag when initializing the context.
88          */
89         VB2_CONTEXT_FORCE_RECOVERY_MODE = (1 << 4),
90
91         /*
92          * Force developer mode enabled.  Caller may set this flag when
93          * initializing the context.
94          */
95         VB2_CONTEXT_FORCE_DEVELOPER_MODE = (1 << 5),
96
97         /* Using firmware slot B.  If this flag is clear, using slot A. */
98         VB2_CONTEXT_FW_SLOT_B = (1 << 6),
99
100         /* RAM should be cleared by caller this boot */
101         VB2_CONTEXT_CLEAR_RAM = (1 << 7),
102
103         /* Wipeout by the app should be requested. */
104         VB2_CONTEXT_FORCE_WIPEOUT_MODE = (1 << 8),
105
106         /* Erase TPM developer mode state if it is enabled. */
107         VB2_DISABLE_DEVELOPER_MODE = (1 << 9),
108
109         /*
110          * Verified boot has changed secdatak[].  Caller must save secdatak[]
111          * back to its underlying storage, then may clear this flag.
112          */
113         VB2_CONTEXT_SECDATAK_CHANGED = (1 << 10),
114
115         /*
116          * Allow kernel verification to roll forward the version in secdatak[].
117          * Caller may set this flag before calling vb2api_kernel_phase3().
118          */
119         VB2_CONTEXT_ALLOW_KERNEL_ROLL_FORWARD = (1 << 11),
120
121         /* Boot optimistically: don't touch failure counters */
122         VB2_CONTEXT_NOFAIL_BOOT = (1 << 12),
123
124         /*
125          * Secdata is not ready this boot, but should be ready next boot.  It
126          * would like to reboot.  The decision whether to reboot or not must be
127          * deferred until vboot, because rebooting all the time before then
128          * could cause a device with malfunctioning secdata to get stuck in an
129          * unrecoverable crash loop.
130          */
131         VB2_CONTEXT_SECDATA_WANTS_REBOOT = (1 << 13),
132
133         /* Boot is S3->S0 resume, not S5->S0 normal boot */
134         VB2_CONTEXT_S3_RESUME = (1 << 14),
135 };
136
137 /*
138  * Context for firmware verification.  Pass this to all vboot APIs.
139  *
140  * Caller may relocate this between calls to vboot APIs.
141  */
142 struct vb2_context {
143         /**********************************************************************
144          * Fields which must be initialized by caller.
145          */
146
147         /*
148          * Flags; see vb2_context_flags.  Some flags may only be set by caller
149          * prior to calling vboot functions.
150          */
151         uint32_t flags;
152
153         /*
154          * Work buffer, and length in bytes.  Caller may relocate this between
155          * calls to vboot APIs; it contains no internal pointers.  Caller must
156          * not examine the contents of this work buffer directly.
157          */
158         uint8_t *workbuf;
159         uint32_t workbuf_size;
160
161         /*
162          * Non-volatile data.  Caller must fill this from some non-volatile
163          * location.  If the VB2_CONTEXT_NVDATA_CHANGED flag is set when a
164          * vb2api function returns, caller must save the data back to the
165          * non-volatile location and then clear the flag.
166          */
167         uint8_t nvdata[VB2_NVDATA_SIZE];
168
169         /*
170          * Secure data for firmware verification stage.  Caller must fill this
171          * from some secure non-volatile location.  If the
172          * VB2_CONTEXT_SECDATA_CHANGED flag is set when a function returns,
173          * caller must save the data back to the secure non-volatile location
174          * and then clear the flag.
175          */
176         uint8_t secdata[VB2_SECDATA_SIZE];
177
178         /*
179          * Context pointer for use by caller.  Verified boot never looks at
180          * this.  Put context here if you need it for APIs that verified boot
181          * may call (vb2ex_...() functions).
182          */
183         void *non_vboot_context;
184
185         /**********************************************************************
186          * Fields caller may examine after calling vb2api_fw_phase1().  Caller
187          * must set these fields to 0 before calling any vboot functions.
188          */
189
190         /*
191          * Amount of work buffer used so far.  Verified boot sub-calls use
192          * this to know where the unused work area starts.  Caller may use
193          * this between calls to vboot APIs to know how much data must be
194          * copied when relocating the work buffer.
195          */
196         uint32_t workbuf_used;
197
198         /**********************************************************************
199          * Fields caller must initialize before calling vb2api_kernel_phase1().
200          */
201
202         /*
203          * Secure data for kernel verification stage.  Caller must fill this
204          * from some secure non-volatile location.  If the
205          * VB2_CONTEXT_SECDATAK_CHANGED flag is set when a function returns,
206          * caller must save the data back to the secure non-volatile location
207          * and then clear the flag.
208          */
209         uint8_t secdatak[VB2_SECDATAK_SIZE];
210 };
211
212 /* Resource index for vb2ex_read_resource() */
213 enum vb2_resource_index {
214
215         /* Google binary block */
216         VB2_RES_GBB,
217
218         /*
219          * Firmware verified boot block (keyblock+preamble).  Use
220          * VB2_CONTEXT_FW_SLOT_B to determine whether this refers to slot A or
221          * slot B; vboot will set that flag to the proper state before reading
222          * the vblock.
223          */
224         VB2_RES_FW_VBLOCK,
225
226         /*
227          * Kernel verified boot block (keyblock+preamble) for the current
228          * kernel partition.  Used only by vb2api_kernel_load_vblock().
229          * Contents are allowed to change between calls to that function (to
230          * allow multiple kernels to be examined).
231          */
232         VB2_RES_KERNEL_VBLOCK,
233 };
234
235 /* Digest ID for vbapi_get_pcr_digest() */
236 enum vb2_pcr_digest {
237         /* Digest based on current developer and recovery mode flags */
238         BOOT_MODE_PCR,
239
240         /* SHA-256 hash digest of HWID, from GBB */
241         HWID_DIGEST_PCR,
242 };
243
244 /******************************************************************************
245  * APIs provided by verified boot.
246  *
247  * At a high level, call functions in the order described below.  After each
248  * call, examine vb2_context.flags to determine whether nvdata or secdata
249  * needs to be written.
250  *
251  * If you need to cause the boot process to fail at any point, call
252  * vb2api_fail().  Then check vb2_context.flags to see what data needs to be
253  * written.  Then reboot.
254  *
255  *      Load nvdata from wherever you keep it.
256  *
257  *      Load secdata from wherever you keep it.
258  *
259  *              If it wasn't there at all (for example, this is the first boot
260  *              of a new system in the factory), call vb2api_secdata_create()
261  *              to initialize the data.
262  *
263  *              If access to your storage is unreliable (reads/writes may
264  *              contain corrupt data), you may call vb2api_secdata_check() to
265  *              determine if the data was valid, and retry reading if it
266  *              wasn't.  (In that case, you should also read back and check the
267  *              data after any time you write it, to make sure it was written
268  *              correctly.)
269  *
270  *      Call vb2api_fw_phase1().  At present, this nominally decides whether
271  *      recovery mode is needed this boot.
272  *
273  *      Call vb2api_fw_phase2().  At present, this nominally decides which
274  *      firmware slot will be attempted (A or B).
275  *
276  *      Call vb2api_fw_phase3().  At present, this nominally verifies the
277  *      firmware keyblock and preamble.
278  *
279  *      Lock down wherever you keep secdata.  It should no longer be writable
280  *      this boot.
281  *
282  *      Verify the hash of each section of code/data you need to boot the RW
283  *      firmware.  For each section:
284  *
285  *              Call vb2_init_hash() to see if the hash exists.
286  *
287  *              Load the data for the section.  Call vb2_extend_hash() on the
288  *              data as you load it.  You can load it all at once and make one
289  *              call, or load and hash-extend a block at a time.
290  *
291  *              Call vb2_check_hash() to see if the hash is valid.
292  *
293  *                      If it is valid, you may use the data and/or execute
294  *                      code from that section.
295  *
296  *                      If the hash was invalid, you must reboot.
297  *
298  * At this point, firmware verification is done, and vb2_context contains the
299  * kernel key needed to verify the kernel.  That context should be preserved
300  * and passed on to kernel selection.  The kernel selection process may be
301  * done by the same firmware image, or may be done by the RW firmware.  The
302  * recommended order is:
303  *
304  *      Load secdatak from wherever you keep it.
305  *
306  *              If it wasn't there at all (for example, this is the first boot
307  *              of a new system in the factory), call vb2api_secdatak_create()
308  *              to initialize the data.
309  *
310  *              If access to your storage is unreliable (reads/writes may
311  *              contain corrupt data), you may call vb2api_secdatak_check() to
312  *              determine if the data was valid, and retry reading if it
313  *              wasn't.  (In that case, you should also read back and check the
314  *              data after any time you write it, to make sure it was written
315  *              correctly.)
316  *
317  *      Call vb2api_kernel_phase1().  At present, this decides which key to
318  *      use to verify kernel data - the recovery key from the GBB, or the
319  *      kernel subkey from the firmware verification stage.
320  *
321  *      Kernel phase 2 is finding loading, and verifying the kernel partition.
322  *
323  *      Find a boot device (you're on your own here).
324  *
325  *      Call vb2api_load_kernel_vblock() for each kernel partition on the
326  *      boot device, until one succeeds.
327  *
328  *      When that succeeds, call vb2api_get_kernel_size() to determine where
329  *      the kernel is located in the stream and how big it is.  Load or map
330  *      the kernel.  (Again, you're on your own.  This is the responsibility of
331  *      the caller so that the caller can choose whether to allocate a buffer,
332  *      load the kernel data into a predefined area of RAM, or directly map a
333  *      kernel file into the address space.  Note that technically it doesn't
334  *      matter whether the kernel data is even in the same file or stream as
335  *      the vblock, as long as the caller loads the right data.
336  *
337  *      Call vb2api_verify_kernel_data() on the kernel data.
338  *
339  *      If you ran out of kernels before finding a good one, call vb2api_fail()
340  *      with an appropriate recovery reason.
341  *
342  *      Set the VB2_CONTEXT_ALLOW_KERNEL_ROLL_FORWARD flag if the current
343  *      kernel partition has the successful flag (that is, it's already known
344  *      or assumed to be a functional kernel partition).
345  *
346  *      Call vb2api_kernel_phase3().  This cleans up from kernel verification
347  *      and updates the secure data if needed.
348  *
349  *      Lock down wherever you keep secdatak.  It should no longer be writable
350  *      this boot.
351  */
352
353 /**
354  * Sanity-check the contents of the secure storage context.
355  *
356  * Use this if reading from secure storage may be flaky, and you want to retry
357  * reading it several times.
358  *
359  * This may be called before vb2api_phase1().
360  *
361  * @param ctx           Context pointer
362  * @return VB2_SUCCESS, or non-zero error code if error.
363  */
364 int vb2api_secdata_check(const struct vb2_context *ctx);
365
366 /**
367  * Create fresh data in the secure storage context.
368  *
369  * Use this only when initializing the secure storage context on a new machine
370  * the first time it boots.  Do NOT simply use this if vb2api_secdata_check()
371  * (or any other API in this library) fails; that could allow the secure data
372  * to be rolled back to an insecure state.
373  *
374  * This may be called before vb2api_phase1().
375  *
376  * @param ctx           Context pointer
377  * @return VB2_SUCCESS, or non-zero error code if error.
378  */
379 int vb2api_secdata_create(struct vb2_context *ctx);
380
381 /**
382  * Sanity-check the contents of the kernel version secure storage context.
383  *
384  * Use this if reading from secure storage may be flaky, and you want to retry
385  * reading it several times.
386  *
387  * This may be called before vb2api_phase1().
388  *
389  * @param ctx           Context pointer
390  * @return VB2_SUCCESS, or non-zero error code if error.
391  */
392 int vb2api_secdatak_check(const struct vb2_context *ctx);
393
394 /**
395  * Create fresh data in the kernel version secure storage context.
396  *
397  * Use this only when initializing the secure storage context on a new machine
398  * the first time it boots.  Do NOT simply use this if vb2api_secdatak_check()
399  * (or any other API in this library) fails; that could allow the secure data
400  * to be rolled back to an insecure state.
401  *
402  * This may be called before vb2api_phase1().
403  *
404  * @param ctx           Context pointer
405  * @return VB2_SUCCESS, or non-zero error code if error.
406  */
407 int vb2api_secdatak_create(struct vb2_context *ctx);
408
409 /**
410  * Report firmware failure to vboot.
411  *
412  * This may be called before vb2api_phase1() to indicate errors in the boot
413  * process prior to the start of vboot.
414  *
415  * If this is called after vb2api_phase1(), on return, the calling firmware
416  * should check for updates to secdata and/or nvdata, then reboot.
417  *
418  * @param reason        Recovery reason
419  * @param subcode       Recovery subcode
420  */
421 void vb2api_fail(struct vb2_context *ctx, uint8_t reason, uint8_t subcode);
422
423 /**
424  * Firmware selection, phase 1.
425  *
426  * If the returned error is VB2_ERROR_API_PHASE1_RECOVERY, the calling firmware
427  * should jump directly to recovery-mode firmware without rebooting.
428  *
429  * For other errors, the calling firmware should check for updates to secdata
430  * and/or nvdata, then reboot.
431  *
432  * @param ctx           Vboot context
433  * @return VB2_SUCCESS, or error code on error.
434  */
435 int vb2api_fw_phase1(struct vb2_context *ctx);
436
437 /**
438  * Firmware selection, phase 2.
439  *
440  * On error, the calling firmware should check for updates to secdata and/or
441  * nvdata, then reboot.
442  *
443  * @param ctx           Vboot context
444  * @return VB2_SUCCESS, or error code on error.
445  */
446 int vb2api_fw_phase2(struct vb2_context *ctx);
447
448 /**
449  * Firmware selection, phase 3.
450  *
451  * On error, the calling firmware should check for updates to secdata and/or
452  * nvdata, then reboot.
453  *
454  * On success, the calling firmware should lock down secdata before continuing
455  * with the boot process.
456  *
457  * @param ctx           Vboot context
458  * @return VB2_SUCCESS, or error code on error.
459  */
460 int vb2api_fw_phase3(struct vb2_context *ctx);
461
462 /**
463  * Same, but for new-style structs.
464  */
465 int vb21api_fw_phase3(struct vb2_context *ctx);
466
467 /**
468  * Initialize hashing data for the specified tag.
469  *
470  * @param ctx           Vboot context
471  * @param tag           Tag to start hashing (enum vb2_hash_tag)
472  * @param size          If non-null, expected size of data for tag will be
473  *                      stored here on output.
474  * @return VB2_SUCCESS, or error code on error.
475  */
476 int vb2api_init_hash(struct vb2_context *ctx, uint32_t tag, uint32_t *size);
477
478 /**
479  * Same, but for new-style structs.
480  */
481 int vb21api_init_hash(struct vb2_context *ctx,
482                       const struct vb2_id *id,
483                       uint32_t *size);
484
485 /**
486  * Extend the hash started by vb2api_init_hash() with additional data.
487  *
488  * (This is the same for both old and new style structs.)
489  *
490  * @param ctx           Vboot context
491  * @param buf           Data to hash
492  * @param size          Size of data in bytes
493  * @return VB2_SUCCESS, or error code on error.
494  */
495 int vb2api_extend_hash(struct vb2_context *ctx,
496                        const void *buf,
497                        uint32_t size);
498
499 /**
500  * Check the hash value started by vb2api_init_hash().
501  *
502  * @param ctx           Vboot context
503  * @return VB2_SUCCESS, or error code on error.
504  */
505 int vb2api_check_hash(struct vb2_context *ctx);
506
507 /**
508  * Same, but for new-style structs.
509  */
510 int vb21api_check_hash(struct vb2_context *ctx);
511
512 /**
513  * Check the hash value started by vb2api_init_hash() while retrieving
514  * calculated digest.
515  *
516  * @param ctx                   Vboot context
517  * @param digest_out            optional pointer to buffer to store digest
518  * @param digest_out_size       optional size of buffer to store digest
519  * @return VB2_SUCCESS, or error code on error.
520  */
521 int vb2api_check_hash_get_digest(struct vb2_context *ctx, void *digest_out,
522                                  uint32_t digest_out_size);
523
524 /**
525  * Get a PCR digest
526  *
527  * @param ctx           Vboot context
528  * @param which_digest  PCR index of the digest
529  * @param dest          Destination where the digest is copied.
530  *                      Recommended size is VB2_PCR_DIGEST_RECOMMENDED_SIZE.
531  * @param dest_size     IN: size of the buffer pointed by dest
532  *                      OUT: size of the copied digest
533  * @return VB2_SUCCESS, or error code on error
534  */
535 int vb2api_get_pcr_digest(struct vb2_context *ctx,
536                           enum vb2_pcr_digest which_digest,
537                           uint8_t *dest,
538                           uint32_t *dest_size);
539
540 /**
541  * Prepare for kernel verification stage.
542  *
543  * Must be called before other vb2api kernel functions.
544  *
545  * @param ctx           Vboot context
546  * @return VB2_SUCCESS, or error code on error.
547  */
548 int vb2api_kernel_phase1(struct vb2_context *ctx);
549
550 /**
551  * Load the verified boot block (vblock) for a kernel.
552  *
553  * This function may be called multiple times, to load and verify the
554  * vblocks from multiple kernel partitions.
555  *
556  * @param ctx           Vboot context
557  * @param stream        Kernel stream
558  * @return VB2_SUCCESS, or error code on error.
559  */
560 int vb2api_load_kernel_vblock(struct vb2_context *ctx);
561
562 /**
563  * Get the size and offset of the kernel data for the most recent vblock.
564  *
565  * Valid after a successful call to vb2api_load_kernel_vblock().
566  *
567  * @param ctx           Vboot context
568  * @param offset_ptr    Destination for offset in bytes of kernel data as
569  *                      reported by vblock.
570  * @param size_ptr      Destination for size of kernel data in bytes.
571  * @return VB2_SUCCESS, or error code on error.
572  */
573 int vb2api_get_kernel_size(struct vb2_context *ctx,
574                            uint32_t *offset_ptr,
575                            uint32_t *size_ptr);
576
577 /**
578  * Verify kernel data using the previously loaded kernel vblock.
579  *
580  * Valid after a successful call to vb2api_load_kernel_vblock().  This allows
581  * the caller to load or map the kernel data, as appropriate, and pass the
582  * pointer to the kernel data into vboot.
583  *
584  * @param ctx           Vboot context
585  * @param buf           Pointer to kernel data
586  * @param size          Size of kernel data in bytes
587  * @return VB2_SUCCESS, or error code on error.
588  */
589 int vb2api_verify_kernel_data(struct vb2_context *ctx,
590                               const void *buf,
591                               uint32_t size);
592
593 /**
594  * Clean up after kernel verification.
595  *
596  * Call this after successfully loading a vblock and verifying kernel data,
597  * or if you've run out of boot devices and/or kernel partitions.
598  *
599  * This cleans up intermediate data structures in the vboot context, and
600  * updates the version in the secure data if necessary.
601  */
602 int vb2api_kernel_phase3(struct vb2_context *ctx);
603
604 /*****************************************************************************/
605 /* APIs provided by the caller to verified boot */
606
607 /**
608  * Clear the TPM owner.
609  *
610  * @param ctx           Vboot context
611  * @return VB2_SUCCESS, or error code on error.
612  */
613 int vb2ex_tpm_clear_owner(struct vb2_context *ctx);
614
615 /**
616  * Read a verified boot resource.
617  *
618  * @param ctx           Vboot context
619  * @param index         Resource index to read
620  * @param offset        Byte offset within resource to start at
621  * @param buf           Destination for data
622  * @param size          Amount of data to read
623  * @return VB2_SUCCESS, or error code on error.
624  */
625 int vb2ex_read_resource(struct vb2_context *ctx,
626                         enum vb2_resource_index index,
627                         uint32_t offset,
628                         void *buf,
629                         uint32_t size);
630
631 void vb2ex_printf(const char *func, const char *fmt, ...);
632
633 /**
634  * Initialize the hardware crypto engine to calculate a block-style digest.
635  *
636  * @param hash_alg      Hash algorithm to use
637  * @param data_size     Expected total size of data to hash
638  * @return VB2_SUCCESS, or non-zero error code (HWCRYPTO_UNSUPPORTED not fatal).
639  */
640 int vb2ex_hwcrypto_digest_init(enum vb2_hash_algorithm hash_alg,
641                                uint32_t data_size);
642
643 /**
644  * Extend the hash in the hardware crypto engine with another block of data.
645  *
646  * @param buf           Next data block to hash
647  * @param size          Length of data block in bytes
648  * @return VB2_SUCCESS, or non-zero error code.
649  */
650 int vb2ex_hwcrypto_digest_extend(const uint8_t *buf, uint32_t size);
651
652 /**
653  * Finalize the digest in the hardware crypto engine and extract the result.
654  *
655  * @param digest        Destination buffer for resulting digest
656  * @param digest_size   Length of digest buffer in bytes
657  * @return VB2_SUCCESS, or non-zero error code.
658  */
659 int vb2ex_hwcrypto_digest_finalize(uint8_t *digest, uint32_t digest_size);
660
661 #endif  /* VBOOT_2_API_H_ */