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 */
24const 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 */
35int 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 */
50int 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 */
73int 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 */
88int 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 */
102int 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 */
112int 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 */
124int 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 */
140int 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 */
158int 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 */
174int 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