src/lib/crypt_ops/crypto_digest.h

   1 /* Copyright (c) 2001, Matej Pfajfar.
   2  * Copyright (c) 2001-2004, Roger Dingledine.
   3  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   4  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   5 /* See LICENSE for licensing information */
   6
   7 /**
   8  * \file crypto_digest.h
   9  *
  10  * \brief Headers for crypto_digest.c
  11  **/
  12
  13 #ifndef TOR_CRYPTO_DIGEST_H
  14 #define TOR_CRYPTO_DIGEST_H
  15
  16 #include "lib/cc/torint.h"
  17 #include "lib/defs/digest_sizes.h"
  18 #include "lib/malloc/malloc.h"
  19 #include "lib/testsupport/testsupport.h"
  20
  21 /** Length of a sha1 message digest when encoded in base32 with trailing =
  22  * signs removed. */
  23 #define BASE32_DIGEST_LEN 32
  24 /** Length of a sha1 message digest when encoded in base64 with trailing =
  25  * signs removed. */
  26 #define BASE64_DIGEST_LEN 27
  27 /** Length of a sha256 message digest when encoded in base64 with trailing =
  28  * signs removed. */
  29 #define BASE64_DIGEST256_LEN 43
  30 /** Length of a sha512 message digest when encoded in base64 with trailing =
  31  * signs removed. */
  32 #define BASE64_DIGEST512_LEN 86
  33
  34 /** Length of hex encoding of SHA1 digest, not including final NUL. */
  35 #define HEX_DIGEST_LEN 40
  36 /** Length of hex encoding of SHA256 digest, not including final NUL. */
  37 #define HEX_DIGEST256_LEN 64
  38 /** Length of hex encoding of SHA512 digest, not including final NUL. */
  39 #define HEX_DIGEST512_LEN 128
  40
  41 /**
  42  * An identifier for a cryptographic digest algorithm.
  43  **/
  44 typedef enum {
  45   DIGEST_SHA1 = 0,
  46   DIGEST_SHA256 = 1,
  47   DIGEST_SHA512 = 2,
  48   DIGEST_SHA3_256 = 3,
  49   DIGEST_SHA3_512 = 4,
  50 } digest_algorithm_t;
  51 /** Number of digest algorithms that we know */
  52 #define  N_DIGEST_ALGORITHMS (DIGEST_SHA3_512+1)
  53 /** Number of digest algorithms to compute when computing "all the
  54  * commonly used digests."
  55  *
  56  * (This is used in common_digests_t and related functions.)
  57  */
  58 #define  N_COMMON_DIGEST_ALGORITHMS (DIGEST_SHA256+1)
  59
  60 /**
  61  * Bytes of storage needed to record the state of an in-progress SHA-1 digest.
  62  *
  63  * This is a deliberate overestimate.
  64  **/
  65 #define DIGEST_CHECKPOINT_BYTES (SIZEOF_VOID_P + 512)
  66
  67 /** Structure used to temporarily save the a digest object. Only implemented
  68  * for SHA1 digest for now. */
  69 typedef struct crypto_digest_checkpoint_t {
  70 #ifdef ENABLE_NSS
  71   /** The number of bytes used in <b>mem</b>. */
  72   unsigned int bytes_used;
  73 #endif
  74   /** A buffer to store the SHA1 state. Its contents are unspecified, and
  75    * are managed by the underlying crypto library.*/
  76   uint8_t mem[DIGEST_CHECKPOINT_BYTES];
  77 } crypto_digest_checkpoint_t;
  78
  79 /** A set of all the digests we commonly compute, taken on a single
  80  * string.  Any digests that are shorter than 512 bits are right-padded
  81  * with 0 bits.
  82  *
  83  * Note that this representation wastes 44 bytes for the SHA1 case, so
  84  * don't use it for anything where we need to allocate a whole bunch at
  85  * once.
  86  **/
  87 typedef struct {
  88   /** An array of digest outputs, one for each "common" digest algorithm. */
  89   char d[N_COMMON_DIGEST_ALGORITHMS][DIGEST256_LEN];
  90 } common_digests_t;
  91
  92 /**
  93  * State for computing a digest over a stream of data.
  94  **/
  95 typedef struct crypto_digest_t crypto_digest_t;
  96
  97 /**
  98  * State for computing an "extendable-output function" (like SHAKE) over a
  99  * stream of data, and/or streaming the output.
 100  **/
 101 typedef struct crypto_xof_t crypto_xof_t;
 102
 103 struct smartlist_t;
 104
 105 /* SHA-1 and other digests */
 106 MOCK_DECL(int, crypto_digest,(char *digest, const char *m, size_t len));
 107 int crypto_digest256(char *digest, const char *m, size_t len,
 108                      digest_algorithm_t algorithm);
 109 int crypto_digest512(char *digest, const char *m, size_t len,
 110                      digest_algorithm_t algorithm);
 111 int crypto_common_digests(common_digests_t *ds_out, const char *m, size_t len);
 112 void crypto_digest_smartlist_prefix(char *digest_out, size_t len_out,
 113                                     const char *prepend,
 114                                     const struct smartlist_t *lst,
 115                                     const char *append,
 116                                     digest_algorithm_t alg);
 117 void crypto_digest_smartlist(char *digest_out, size_t len_out,
 118                              const struct smartlist_t *lst, const char *append,
 119                              digest_algorithm_t alg);
 120 const char *crypto_digest_algorithm_get_name(digest_algorithm_t alg);
 121 size_t crypto_digest_algorithm_get_length(digest_algorithm_t alg);
 122 int crypto_digest_algorithm_parse_name(const char *name);
 123 crypto_digest_t *crypto_digest_new(void);
 124 crypto_digest_t *crypto_digest256_new(digest_algorithm_t algorithm);
 125 crypto_digest_t *crypto_digest512_new(digest_algorithm_t algorithm);
 126 void crypto_digest_free_(crypto_digest_t *digest);
 127 /**
 128  * Release all storage held in <b>d</b>, and set it to NULL.
 129  **/
 130 #define crypto_digest_free(d) \
 131   FREE_AND_NULL(crypto_digest_t, crypto_digest_free_, (d))
 132 void crypto_digest_add_bytes(crypto_digest_t *digest, const char *data,
 133                              size_t len);
 134 void crypto_digest_get_digest(crypto_digest_t *digest,
 135                               char *out, size_t out_len);
 136 crypto_digest_t *crypto_digest_dup(const crypto_digest_t *digest);
 137 void crypto_digest_checkpoint(crypto_digest_checkpoint_t *checkpoint,
 138                               const crypto_digest_t *digest);
 139 void crypto_digest_restore(crypto_digest_t *digest,
 140                            const crypto_digest_checkpoint_t *checkpoint);
 141 void crypto_digest_assign(crypto_digest_t *into,
 142                           const crypto_digest_t *from);
 143 void crypto_hmac_sha256(char *hmac_out,
 144                         const char *key, size_t key_len,
 145                         const char *msg, size_t msg_len);
 146 void crypto_mac_sha3_256(uint8_t *mac_out, size_t len_out,
 147                          const uint8_t *key, size_t key_len,
 148                          const uint8_t *msg, size_t msg_len);
 149
 150 /* xof functions*/
 151 crypto_xof_t *crypto_xof_new(void);
 152 void crypto_xof_add_bytes(crypto_xof_t *xof, const uint8_t *data, size_t len);
 153 void crypto_xof_squeeze_bytes(crypto_xof_t *xof, uint8_t *out, size_t len);
 154 void crypto_xof_free_(crypto_xof_t *xof);
 155 /**
 156  * Release all storage held in <b>xof</b>, and set it to NULL.
 157  **/
 158 #define crypto_xof_free(xof) \
 159   FREE_AND_NULL(crypto_xof_t, crypto_xof_free_, (xof))
 160 void crypto_xof(uint8_t *output, size_t output_len,
 161                 const uint8_t *input, size_t input_len);
 162
 163 #ifdef TOR_UNIT_TESTS
 164 digest_algorithm_t crypto_digest_get_algorithm(crypto_digest_t *digest);
 165 #endif
 166
 167 #endif /* !defined(TOR_CRYPTO_DIGEST_H) */