avb_crypto.h 5.1 KB

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