1 /*
2  * This file Copyright (C) 2007-2014 Mnemosyne LLC
3  *
4  * It may be used under the GNU GPL versions 2 or 3
5  * or any future license endorsed by Mnemosyne LLC.
6  *
7  */
8 
9 #ifndef TR_CRYPTO_UTILS_H
10 #define TR_CRYPTO_UTILS_H
11 
12 #include <inttypes.h>
13 #include <stddef.h>
14 
15 #include "transmission.h" /* SHA_DIGEST_LENGTH */
16 #include "utils.h" /* TR_GNUC_MALLOC, TR_GNUC_NULL_TERMINATED */
17 
18 #ifdef __cplusplus
19 extern "C"
20 {
21 #endif
22 
23 /**
24 *** @addtogroup utils Utilities
25 *** @{
26 **/
27 
28 /** @brief Opaque SHA1 context type. */
29 typedef void* tr_sha1_ctx_t;
30 /** @brief Opaque RC4 context type. */
31 typedef void* tr_rc4_ctx_t;
32 /** @brief Opaque DH context type. */
33 typedef void* tr_dh_ctx_t;
34 /** @brief Opaque DH secret key type. */
35 typedef void* tr_dh_secret_t;
36 /** @brief Opaque SSL context type. */
37 typedef void* tr_ssl_ctx_t;
38 /** @brief Opaque X509 certificate store type. */
39 typedef void* tr_x509_store_t;
40 /** @brief Opaque X509 certificate type. */
41 typedef void* tr_x509_cert_t;
42 
43 /**
44  * @brief Generate a SHA1 hash from one or more chunks of memory.
45  */
46 bool tr_sha1(uint8_t* hash, void const* data1, int data1_length, ...) TR_GNUC_NULL_TERMINATED;
47 
48 /**
49  * @brief Allocate and initialize new SHA1 hasher context.
50  */
51 tr_sha1_ctx_t tr_sha1_init(void);
52 
53 /**
54  * @brief Update SHA1 hash.
55  */
56 bool tr_sha1_update(tr_sha1_ctx_t handle, void const* data, size_t data_length);
57 
58 /**
59  * @brief Finalize and export SHA1 hash, free hasher context.
60  */
61 bool tr_sha1_final(tr_sha1_ctx_t handle, uint8_t* hash);
62 
63 /**
64  * @brief Allocate and initialize new RC4 cipher context.
65  */
66 tr_rc4_ctx_t tr_rc4_new(void);
67 
68 /**
69  * @brief Free RC4 cipher context.
70  */
71 void tr_rc4_free(tr_rc4_ctx_t handle);
72 
73 /**
74  * @brief Set RC4 cipher key.
75  */
76 void tr_rc4_set_key(tr_rc4_ctx_t handle, uint8_t const* key, size_t key_length);
77 
78 /**
79  * @brief Process memory block with RC4 cipher.
80  */
81 void tr_rc4_process(tr_rc4_ctx_t handle, void const* input, void* output, size_t length);
82 
83 /**
84  * @brief Allocate and initialize new Diffie-Hellman (DH) key exchange context.
85  */
86 tr_dh_ctx_t tr_dh_new(uint8_t const* prime_num, size_t prime_num_length, uint8_t const* generator_num,
87     size_t generator_num_length);
88 
89 /**
90  * @brief Free DH key exchange context.
91  */
92 void tr_dh_free(tr_dh_ctx_t handle);
93 
94 /**
95  * @brief Generate private and public DH keys, export public key.
96  */
97 bool tr_dh_make_key(tr_dh_ctx_t handle, size_t private_key_length, uint8_t* public_key, size_t* public_key_length);
98 
99 /**
100  * @brief Perform DH key exchange, generate secret key.
101  */
102 tr_dh_secret_t tr_dh_agree(tr_dh_ctx_t handle, uint8_t const* other_public_key, size_t other_public_key_length);
103 
104 /**
105  * @brief Calculate SHA1 hash of DH secret key, prepending and/or appending
106  *        given data to the key during calculation.
107  */
108 bool tr_dh_secret_derive(tr_dh_secret_t handle, void const* prepend_data, size_t prepend_data_size, void const* append_data,
109     size_t append_data_size, uint8_t* hash);
110 
111 /**
112  * @brief Free DH secret key returned by @ref tr_dh_agree.
113  */
114 void tr_dh_secret_free(tr_dh_secret_t handle);
115 
116 /**
117  * @brief Align DH key (big-endian number) to required length (internal, do not use).
118  */
119 void tr_dh_align_key(uint8_t* key_buffer, size_t key_size, size_t buffer_size);
120 
121 /**
122  * @brief Get X509 certificate store from SSL context.
123  */
124 tr_x509_store_t tr_ssl_get_x509_store(tr_ssl_ctx_t handle);
125 
126 /**
127  * @brief Add certificate to X509 certificate store.
128  */
129 bool tr_x509_store_add(tr_x509_store_t handle, tr_x509_cert_t cert);
130 
131 /**
132  * @brief Allocate and initialize new X509 certificate from DER-encoded buffer.
133  */
134 tr_x509_cert_t tr_x509_cert_new(void const* der_data, size_t der_data_size);
135 
136 /**
137  * @brief Free X509 certificate returned by @ref tr_x509_cert_new.
138  */
139 void tr_x509_cert_free(tr_x509_cert_t handle);
140 
141 /**
142  * @brief Returns a random number in the range of [0...upper_bound).
143  */
144 int tr_rand_int(int upper_bound);
145 
146 /**
147  * @brief Returns a pseudorandom number in the range of [0...upper_bound).
148  *
149  * This is faster, BUT WEAKER, than tr_rand_int() and never be used in sensitive cases.
150  * @see tr_rand_int()
151  */
152 int tr_rand_int_weak(int upper_bound);
153 
154 /**
155  * @brief Fill a buffer with random bytes.
156  */
157 bool tr_rand_buffer(void* buffer, size_t length);
158 
159 /**
160  * @brief Generate a SSHA password from its plaintext source.
161  */
162 char* tr_ssha1(char const* plain_text) TR_GNUC_MALLOC;
163 
164 /**
165  * @brief Validate a test password against the a ssha1 password.
166  */
167 bool tr_ssha1_matches(char const* ssha1, char const* plain_text);
168 
169 /**
170  * @brief Translate a block of bytes into base64.
171  * @return a newly-allocated null-terminated string that can be freed with tr_free()
172  */
173 void* tr_base64_encode(void const* input, size_t input_length, size_t* output_length) TR_GNUC_MALLOC;
174 
175 /**
176  * @brief Translate null-terminated string into base64.
177  * @return a newly-allocated null-terminated string that can be freed with tr_free()
178  */
179 void* tr_base64_encode_str(char const* input, size_t* output_length) TR_GNUC_MALLOC;
180 
181 /**
182  * @brief Translate a block of bytes from base64 into raw form.
183  * @return a newly-allocated null-terminated string that can be freed with tr_free()
184  */
185 void* tr_base64_decode(void const* input, size_t input_length, size_t* output_length) TR_GNUC_MALLOC;
186 
187 /**
188  * @brief Translate null-terminated string from base64 into raw form.
189  * @return a newly-allocated null-terminated string that can be freed with tr_free()
190  */
191 void* tr_base64_decode_str(char const* input, size_t* output_length) TR_GNUC_MALLOC;
192 
193 /**
194  * @brief Wrapper around tr_binary_to_hex() for SHA_DIGEST_LENGTH.
195  */
tr_sha1_to_hex(char * hex,uint8_t const * sha1)196 static inline void tr_sha1_to_hex(char* hex, uint8_t const* sha1)
197 {
198     tr_binary_to_hex(sha1, hex, SHA_DIGEST_LENGTH);
199 }
200 
201 /**
202  * @brief Wrapper around tr_hex_to_binary() for SHA_DIGEST_LENGTH.
203  */
tr_hex_to_sha1(uint8_t * sha1,char const * hex)204 static inline void tr_hex_to_sha1(uint8_t* sha1, char const* hex)
205 {
206     tr_hex_to_binary(hex, sha1, SHA_DIGEST_LENGTH);
207 }
208 
209 /** @} */
210 
211 #ifdef __cplusplus
212 }
213 #endif
214 
215 #endif /* TR_CRYPTO_UTILS_H */
216