lib/libavb/avb_crypto.h

   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_ */