1 /* SPDX-License-Identifier: MIT */
2 /*
3  * Copyright (C) 2016 The Android Open Source Project
4  */
5 
6 #if !defined(AVB_INSIDE_LIBAVB_H) && !defined(AVB_COMPILATION)
7 #error "Never include this file directly, include libavb.h instead."
8 #endif
9 
10 #ifndef AVB_CRYPTO_H_
11 #define AVB_CRYPTO_H_
12 
13 #include "avb_sysdeps.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /* Size of a RSA-2048 signature. */
20 #define AVB_RSA2048_NUM_BYTES 256
21 
22 /* Size of a RSA-4096 signature. */
23 #define AVB_RSA4096_NUM_BYTES 512
24 
25 /* Size of a RSA-8192 signature. */
26 #define AVB_RSA8192_NUM_BYTES 1024
27 
28 /* Size in bytes of a SHA-1 digest. */
29 #define AVB_SHA1_DIGEST_SIZE 20
30 
31 /* Size in bytes of a SHA-256 digest. */
32 #define AVB_SHA256_DIGEST_SIZE 32
33 
34 /* Size in bytes of a SHA-512 digest. */
35 #define AVB_SHA512_DIGEST_SIZE 64
36 
37 /* Possible digest types supported by libavb routines. */
38 typedef enum {
39   AVB_DIGEST_TYPE_SHA256,
40   AVB_DIGEST_TYPE_SHA512,
41 } AvbDigestType;
42 
43 /* Algorithms that can be used in the vbmeta image for
44  * verification. An algorithm consists of a hash type and a signature
45  * type.
46  *
47  * The data used to calculate the hash is the three blocks mentioned
48  * in the documentation for |AvbVBMetaImageHeader| except for the data
49  * in the "Authentication data" block.
50  *
51  * For signatures with RSA keys, PKCS v1.5 padding is used. The public
52  * key data is stored in the auxiliary data block, see
53  * |AvbRSAPublicKeyHeader| for the serialization format.
54  *
55  * Each algorithm type is described below:
56  *
57  * AVB_ALGORITHM_TYPE_NONE: There is no hash, no signature of the
58  * data, and no public key. The data cannot be verified. The fields
59  * |hash_size|, |signature_size|, and |public_key_size| must be zero.
60  *
61  * AVB_ALGORITHM_TYPE_SHA256_RSA2048: The hash function used is
62  * SHA-256, resulting in 32 bytes of hash digest data. This hash is
63  * signed with a 2048-bit RSA key. The field |hash_size| must be 32,
64  * |signature_size| must be 256, and the public key data must have
65  * |key_num_bits| set to 2048.
66  *
67  * AVB_ALGORITHM_TYPE_SHA256_RSA4096: Like above, but only with
68  * a 4096-bit RSA key and |signature_size| set to 512.
69  *
70  * AVB_ALGORITHM_TYPE_SHA256_RSA8192: Like above, but only with
71  * a 8192-bit RSA key and |signature_size| set to 1024.
72  *
73  * AVB_ALGORITHM_TYPE_SHA512_RSA2048: The hash function used is
74  * SHA-512, resulting in 64 bytes of hash digest data. This hash is
75  * signed with a 2048-bit RSA key. The field |hash_size| must be 64,
76  * |signature_size| must be 256, and the public key data must have
77  * |key_num_bits| set to 2048.
78  *
79  * AVB_ALGORITHM_TYPE_SHA512_RSA4096: Like above, but only with
80  * a 4096-bit RSA key and |signature_size| set to 512.
81  *
82  * AVB_ALGORITHM_TYPE_SHA512_RSA8192: Like above, but only with
83  * a 8192-bit RSA key and |signature_size| set to 1024.
84  */
85 typedef enum {
86   AVB_ALGORITHM_TYPE_NONE,
87   AVB_ALGORITHM_TYPE_SHA256_RSA2048,
88   AVB_ALGORITHM_TYPE_SHA256_RSA4096,
89   AVB_ALGORITHM_TYPE_SHA256_RSA8192,
90   AVB_ALGORITHM_TYPE_SHA512_RSA2048,
91   AVB_ALGORITHM_TYPE_SHA512_RSA4096,
92   AVB_ALGORITHM_TYPE_SHA512_RSA8192,
93   _AVB_ALGORITHM_NUM_TYPES
94 } AvbAlgorithmType;
95 
96 /* Holds algorithm-specific data. The |padding| is needed by avb_rsa_verify. */
97 typedef struct {
98   const uint8_t* padding;
99   size_t padding_len;
100   size_t hash_len;
101 } AvbAlgorithmData;
102 
103 /* Provides algorithm-specific data for a given |algorithm|. Returns NULL if
104  * |algorithm| is invalid.
105  */
106 const AvbAlgorithmData* avb_get_algorithm_data(AvbAlgorithmType algorithm)
107     AVB_ATTR_WARN_UNUSED_RESULT;
108 
109 /* The header for a serialized RSA public key.
110  *
111  * The size of the key is given by |key_num_bits|, for example 2048
112  * for a RSA-2048 key. By definition, a RSA public key is the pair (n,
113  * e) where |n| is the modulus (which can be represented in
114  * |key_num_bits| bits) and |e| is the public exponent. The exponent
115  * is not stored since it's assumed to always be 65537.
116  *
117  * To optimize verification, the key block includes two precomputed
118  * values, |n0inv| (fits in 32 bits) and |rr| and can always be
119  * represented in |key_num_bits|.
120 
121  * The value |n0inv| is the value -1/n[0] (mod 2^32). The value |rr|
122  * is (2^key_num_bits)^2 (mod n).
123  *
124  * Following this header is |key_num_bits| bits of |n|, then
125  * |key_num_bits| bits of |rr|. Both values are stored with most
126  * significant bit first. Each serialized number takes up
127  * |key_num_bits|/8 bytes.
128  *
129  * All fields in this struct are stored in network byte order when
130  * serialized.  To generate a copy with fields swapped to native byte
131  * order, use the function avb_rsa_public_key_header_validate_and_byteswap().
132  *
133  * The avb_rsa_verify() function expects a key in this serialized
134  * format.
135  *
136  * The 'avbtool extract_public_key' command can be used to generate a
137  * serialized RSA public key.
138  */
139 typedef struct AvbRSAPublicKeyHeader {
140   uint32_t key_num_bits;
141   uint32_t n0inv;
142 } AVB_ATTR_PACKED AvbRSAPublicKeyHeader;
143 
144 /* Copies |src| to |dest| and validates, byte-swapping fields in the
145  * process if needed. Returns true if valid, false if invalid.
146  */
147 bool avb_rsa_public_key_header_validate_and_byteswap(
148     const AvbRSAPublicKeyHeader* src,
149     AvbRSAPublicKeyHeader* dest) AVB_ATTR_WARN_UNUSED_RESULT;
150 
151 #ifdef __cplusplus
152 }
153 #endif
154 
155 #endif /* AVB_CRYPTO_H_ */
156