source: trunk/libtransmission/crypto-utils.h

Last change on this file was 14726, checked in by jordan, 5 years ago

crypto.h and crypto-utils.h can't use #pragma once, it breaks our name munging in crypto-test-ref.h

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