OLD | NEW |
| (Empty) |
1 /* | |
2 * cipher.h | |
3 * | |
4 * common interface to ciphers | |
5 * | |
6 * David A. McGrew | |
7 * Cisco Systems, Inc. | |
8 */ | |
9 /* | |
10 * | |
11 * Copyright (c) 2001-2006,2013 Cisco Systems, Inc. | |
12 * All rights reserved. | |
13 * | |
14 * Redistribution and use in source and binary forms, with or without | |
15 * modification, are permitted provided that the following conditions | |
16 * are met: | |
17 * | |
18 * Redistributions of source code must retain the above copyright | |
19 * notice, this list of conditions and the following disclaimer. | |
20 * | |
21 * Redistributions in binary form must reproduce the above | |
22 * copyright notice, this list of conditions and the following | |
23 * disclaimer in the documentation and/or other materials provided | |
24 * with the distribution. | |
25 * | |
26 * Neither the name of the Cisco Systems, Inc. nor the names of its | |
27 * contributors may be used to endorse or promote products derived | |
28 * from this software without specific prior written permission. | |
29 * | |
30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
31 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
32 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS | |
33 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE | |
34 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
35 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |
36 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |
37 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
41 * OF THE POSSIBILITY OF SUCH DAMAGE. | |
42 * | |
43 */ | |
44 | |
45 | |
46 #ifndef CIPHER_H | |
47 #define CIPHER_H | |
48 | |
49 #include "datatypes.h" | |
50 #include "rdbx.h" /* for xtd_seq_num_t */ | |
51 #include "err.h" /* for error codes */ | |
52 #include "crypto.h" /* for cipher_type_id_t */ | |
53 #include "crypto_types.h" /* for values of cipher_type_id_t */ | |
54 | |
55 | |
56 /** | |
57 * @brief cipher_direction_t defines a particular cipher operation. | |
58 * | |
59 * A cipher_direction_t is an enum that describes a particular cipher | |
60 * operation, i.e. encryption or decryption. For some ciphers, this | |
61 * distinction does not matter, but for others, it is essential. | |
62 */ | |
63 | |
64 typedef enum { | |
65 direction_encrypt, /**< encryption (convert plaintext to ciphertext) */ | |
66 direction_decrypt, /**< decryption (convert ciphertext to plaintext) */ | |
67 direction_any /**< encryption or decryption */ | |
68 } cipher_direction_t; | |
69 | |
70 /* | |
71 * the cipher_pointer and cipher_type_pointer definitions are needed | |
72 * as cipher_t and cipher_type_t are not yet defined | |
73 */ | |
74 | |
75 typedef struct cipher_type_t *cipher_type_pointer_t; | |
76 typedef struct cipher_t *cipher_pointer_t; | |
77 | |
78 /* | |
79 * a cipher_alloc_func_t allocates (but does not initialize) a cipher_t | |
80 */ | |
81 | |
82 typedef err_status_t (*cipher_alloc_func_t) | |
83 (cipher_pointer_t *cp, int key_len, int tag_len); | |
84 | |
85 /* | |
86 * a cipher_init_func_t [re-]initializes a cipher_t with a given key | |
87 */ | |
88 | |
89 typedef err_status_t (*cipher_init_func_t) | |
90 (void *state, const uint8_t *key, int key_len); | |
91 | |
92 /* a cipher_dealloc_func_t de-allocates a cipher_t */ | |
93 | |
94 typedef err_status_t (*cipher_dealloc_func_t)(cipher_pointer_t cp); | |
95 | |
96 /* a cipher_set_segment_func_t sets the segment index of a cipher_t */ | |
97 | |
98 typedef err_status_t (*cipher_set_segment_func_t) | |
99 (void *state, xtd_seq_num_t idx); | |
100 | |
101 /* | |
102 * a cipher_set_aad_func_t processes the AAD data for AEAD ciphers | |
103 */ | |
104 typedef err_status_t (*cipher_set_aad_func_t) | |
105 (void *state, uint8_t *aad, unsigned int aad_len); | |
106 | |
107 | |
108 /* a cipher_encrypt_func_t encrypts data in-place */ | |
109 | |
110 typedef err_status_t (*cipher_encrypt_func_t) | |
111 (void *state, uint8_t *buffer, unsigned int *octets_to_encrypt); | |
112 | |
113 /* a cipher_decrypt_func_t decrypts data in-place */ | |
114 | |
115 typedef err_status_t (*cipher_decrypt_func_t) | |
116 (void *state, uint8_t *buffer, unsigned int *octets_to_decrypt); | |
117 | |
118 /* | |
119 * a cipher_set_iv_func_t function sets the current initialization vector | |
120 */ | |
121 | |
122 typedef err_status_t (*cipher_set_iv_func_t) | |
123 (cipher_pointer_t cp, void *iv, cipher_direction_t direction); | |
124 | |
125 /* | |
126 * a cipher_get_tag_funct_t function is used to get the authentication | |
127 * tag that was calculated by an AEAD cipher. | |
128 */ | |
129 typedef err_status_t (*cipher_get_tag_func_t) | |
130 (void *state, void *tag, int *len); | |
131 | |
132 | |
133 /* | |
134 * cipher_test_case_t is a (list of) key, salt, xtd_seq_num_t, | |
135 * plaintext, and ciphertext values that are known to be correct for a | |
136 * particular cipher. this data can be used to test an implementation | |
137 * in an on-the-fly self test of the correcness of the implementation. | |
138 * (see the cipher_type_self_test() function below) | |
139 */ | |
140 | |
141 typedef struct cipher_test_case_t { | |
142 int key_length_octets; /* octets in key */ | |
143 uint8_t *key; /* key */ | |
144 uint8_t *idx; /* packet index */ | |
145 int plaintext_length_octets; /* octets in plaintext */ | |
146 uint8_t *plaintext; /* plaintext */ | |
147 int ciphertext_length_octets; /* octets in plaintext */ | |
148 uint8_t *ciphertext; /* ciphertext */ | |
149 int aad_length_octets; /* octets in AAD */ | |
150 uint8_t *aad; /* AAD */ | |
151 int tag_length_octets; /* Length of AEAD tag */ | |
152 struct cipher_test_case_t *next_test_case; /* pointer to next testcase */ | |
153 } cipher_test_case_t; | |
154 | |
155 /* cipher_type_t defines the 'metadata' for a particular cipher type */ | |
156 | |
157 typedef struct cipher_type_t { | |
158 cipher_alloc_func_t alloc; | |
159 cipher_dealloc_func_t dealloc; | |
160 cipher_init_func_t init; | |
161 cipher_set_aad_func_t set_aad; | |
162 cipher_encrypt_func_t encrypt; | |
163 cipher_encrypt_func_t decrypt; | |
164 cipher_set_iv_func_t set_iv; | |
165 cipher_get_tag_func_t get_tag; | |
166 char *description; | |
167 int ref_count; | |
168 cipher_test_case_t *test_data; | |
169 debug_module_t *debug; | |
170 cipher_type_id_t id; | |
171 } cipher_type_t; | |
172 | |
173 /* | |
174 * cipher_t defines an instantiation of a particular cipher, with fixed | |
175 * key length, key and salt values | |
176 */ | |
177 | |
178 typedef struct cipher_t { | |
179 cipher_type_t *type; | |
180 void *state; | |
181 int key_len; | |
182 int algorithm; | |
183 } cipher_t; | |
184 | |
185 /* some syntactic sugar on these function types */ | |
186 | |
187 #define cipher_type_alloc(ct, c, klen, tlen) ((ct)->alloc((c), (klen), (tlen))) | |
188 | |
189 #define cipher_dealloc(c) (((c)->type)->dealloc(c)) | |
190 | |
191 #define cipher_init(c, k) (((c)->type)->init(((c)->state), (k), ((c)->key_len))) | |
192 | |
193 #define cipher_encrypt(c, buf, len) \ | |
194 (((c)->type)->encrypt(((c)->state), (buf), (len))) | |
195 | |
196 #define cipher_get_tag(c, buf, len) \ | |
197 (((c)->type)->get_tag(((c)->state), (buf), (len))) | |
198 | |
199 #define cipher_decrypt(c, buf, len) \ | |
200 (((c)->type)->decrypt(((c)->state), (buf), (len))) | |
201 | |
202 #define cipher_set_iv(c, n, dir) \ | |
203 ((c) ? (((c)->type)->set_iv(((cipher_pointer_t)(c)->state), (n), (dir))) : \ | |
204 err_status_no_such_op) | |
205 #define cipher_set_aad(c, a, l) \ | |
206 (((c) && (((c)->type)->set_aad)) ? \ | |
207 (((c)->type)->set_aad(((c)->state), (a), (l))) : \ | |
208 err_status_no_such_op) | |
209 | |
210 err_status_t | |
211 cipher_output(cipher_t *c, uint8_t *buffer, int num_octets_to_output); | |
212 | |
213 | |
214 /* some bookkeeping functions */ | |
215 | |
216 int | |
217 cipher_get_key_length(const cipher_t *c); | |
218 | |
219 | |
220 /* | |
221 * cipher_type_self_test() tests a cipher against test cases provided in | |
222 * an array of values of key/xtd_seq_num_t/plaintext/ciphertext | |
223 * that is known to be good | |
224 */ | |
225 | |
226 err_status_t | |
227 cipher_type_self_test(const cipher_type_t *ct); | |
228 | |
229 | |
230 /* | |
231 * cipher_type_test() tests a cipher against external test cases provided in | |
232 * an array of values of key/xtd_seq_num_t/plaintext/ciphertext | |
233 * that is known to be good | |
234 */ | |
235 | |
236 err_status_t | |
237 cipher_type_test(const cipher_type_t *ct, const cipher_test_case_t *test_data); | |
238 | |
239 | |
240 /* | |
241 * cipher_bits_per_second(c, l, t) computes (and estimate of) the | |
242 * number of bits that a cipher implementation can encrypt in a second | |
243 * | |
244 * c is a cipher (which MUST be allocated and initialized already), l | |
245 * is the length in octets of the test data to be encrypted, and t is | |
246 * the number of trials | |
247 * | |
248 * if an error is encountered, then the value 0 is returned | |
249 */ | |
250 | |
251 uint64_t | |
252 cipher_bits_per_second(cipher_t *c, int octets_in_buffer, int num_trials); | |
253 | |
254 #endif /* CIPHER_H */ | |
OLD | NEW |