Tor  0.4.7.0-alpha-dev
crypto_digest.h
Go to the documentation of this file.
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"
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,
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. */
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.*/
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. */
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);
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);
135  char *out, size_t out_len);
138  const crypto_digest_t *digest);
140  const crypto_digest_checkpoint_t *checkpoint);
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*/
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) */
const char * name
Definition: config.c:2434
void crypto_mac_sha3_256(uint8_t *mac_out, size_t len_out, const uint8_t *key, size_t key_len, const uint8_t *msg, size_t msg_len)
size_t crypto_digest_algorithm_get_length(digest_algorithm_t alg)
Definition: crypto_digest.c:86
void crypto_digest_checkpoint(crypto_digest_checkpoint_t *checkpoint, const crypto_digest_t *digest)
int crypto_digest512(char *digest, const char *m, size_t len, digest_algorithm_t algorithm)
digest_algorithm_t
Definition: crypto_digest.h:44
int crypto_digest256(char *digest, const char *m, size_t len, digest_algorithm_t algorithm)
#define N_COMMON_DIGEST_ALGORITHMS
Definition: crypto_digest.h:58
void crypto_xof(uint8_t *output, size_t output_len, const uint8_t *input, size_t input_len)
#define DIGEST_CHECKPOINT_BYTES
Definition: crypto_digest.h:65
void crypto_hmac_sha256(char *hmac_out, const char *key, size_t key_len, const char *msg, size_t msg_len)
void crypto_digest_restore(crypto_digest_t *digest, const crypto_digest_checkpoint_t *checkpoint)
void crypto_xof_squeeze_bytes(crypto_xof_t *xof, uint8_t *out, size_t len)
void crypto_digest_get_digest(crypto_digest_t *digest, char *out, size_t out_len)
void crypto_digest_assign(crypto_digest_t *into, const crypto_digest_t *from)
int crypto_common_digests(common_digests_t *ds_out, const char *m, size_t len)
Definition: crypto_digest.c:30
crypto_xof_t * crypto_xof_new(void)
void crypto_xof_add_bytes(crypto_xof_t *xof, const uint8_t *data, size_t len)
crypto_digest_t * crypto_digest256_new(digest_algorithm_t algorithm)
crypto_digest_t * crypto_digest_dup(const crypto_digest_t *digest)
int crypto_digest(char *digest, const char *m, size_t len)
const char * crypto_digest_algorithm_get_name(digest_algorithm_t alg)
Definition: crypto_digest.c:44
crypto_digest_t * crypto_digest_new(void)
void crypto_xof_free_(crypto_xof_t *xof)
void crypto_digest_free_(crypto_digest_t *digest)
void crypto_digest_add_bytes(crypto_digest_t *digest, const char *data, size_t len)
int crypto_digest_algorithm_parse_name(const char *name)
Definition: crypto_digest.c:68
crypto_digest_t * crypto_digest512_new(digest_algorithm_t algorithm)
Definitions for common sizes of cryptographic digests.
#define DIGEST256_LEN
Definition: digest_sizes.h:23
Headers for util_malloc.c.
uint8_t mem[DIGEST_CHECKPOINT_BYTES]
Definition: crypto_digest.h:76
Macros to implement mocking and selective exposure for the test code.
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Integer definitions used throughout Tor.