OLD | NEW |
| (Empty) |
1 /* | |
2 * crypto_kernel.h | |
3 * | |
4 * header for the cryptographic kernel | |
5 * | |
6 * David A. McGrew | |
7 * Cisco Systems, Inc. | |
8 */ | |
9 /* | |
10 * | |
11 * Copyright(c) 2001-2006 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 CRYPTO_KERNEL | |
47 #define CRYPTO_KERNEL | |
48 | |
49 #include "rand_source.h" | |
50 #include "prng.h" | |
51 #include "cipher.h" | |
52 #include "auth.h" | |
53 #include "cryptoalg.h" | |
54 #include "stat.h" | |
55 #include "err.h" | |
56 #include "crypto_types.h" | |
57 #include "key.h" | |
58 #include "crypto.h" | |
59 | |
60 /* | |
61 * crypto_kernel_state_t defines the possible states: | |
62 * | |
63 * insecure - not yet initialized | |
64 * secure - initialized and passed self-tests | |
65 */ | |
66 | |
67 typedef enum { | |
68 crypto_kernel_state_insecure, | |
69 crypto_kernel_state_secure | |
70 } crypto_kernel_state_t; | |
71 | |
72 /* | |
73 * linked list of cipher types | |
74 */ | |
75 | |
76 typedef struct kernel_cipher_type { | |
77 cipher_type_id_t id; | |
78 cipher_type_t *cipher_type; | |
79 struct kernel_cipher_type *next; | |
80 } kernel_cipher_type_t; | |
81 | |
82 /* | |
83 * linked list of auth types | |
84 */ | |
85 | |
86 typedef struct kernel_auth_type { | |
87 auth_type_id_t id; | |
88 auth_type_t *auth_type; | |
89 struct kernel_auth_type *next; | |
90 } kernel_auth_type_t; | |
91 | |
92 /* | |
93 * linked list of debug modules | |
94 */ | |
95 | |
96 typedef struct kernel_debug_module { | |
97 debug_module_t *mod; | |
98 struct kernel_debug_module *next; | |
99 } kernel_debug_module_t; | |
100 | |
101 | |
102 /* | |
103 * crypto_kernel_t is the data structure for the crypto kernel | |
104 * | |
105 * note that there is *exactly one* instance of this data type, | |
106 * a global variable defined in crypto_kernel.c | |
107 */ | |
108 | |
109 typedef struct { | |
110 crypto_kernel_state_t state; /* current state of kernel */ | |
111 kernel_cipher_type_t *cipher_type_list; /* list of all cipher types */ | |
112 kernel_auth_type_t *auth_type_list; /* list of all auth func types */ | |
113 kernel_debug_module_t *debug_module_list; /* list of all debug modules */ | |
114 } crypto_kernel_t; | |
115 | |
116 | |
117 /* | |
118 * crypto_kernel_t external api | |
119 */ | |
120 | |
121 | |
122 /* | |
123 * The function crypto_kernel_init() initialized the crypto kernel and | |
124 * runs the self-test operations on the random number generators and | |
125 * crypto algorithms. Possible return values are: | |
126 * | |
127 * err_status_ok initialization successful | |
128 * <other> init failure | |
129 * | |
130 * If any value other than err_status_ok is returned, the | |
131 * crypto_kernel MUST NOT be used. | |
132 */ | |
133 | |
134 err_status_t | |
135 crypto_kernel_init(void); | |
136 | |
137 | |
138 /* | |
139 * The function crypto_kernel_shutdown() de-initializes the | |
140 * crypto_kernel, zeroizes keys and other cryptographic material, and | |
141 * deallocates any dynamically allocated memory. Possible return | |
142 * values are: | |
143 * | |
144 * err_status_ok shutdown successful | |
145 * <other> shutdown failure | |
146 * | |
147 */ | |
148 | |
149 err_status_t | |
150 crypto_kernel_shutdown(void); | |
151 | |
152 /* | |
153 * The function crypto_kernel_stats() checks the the crypto_kernel, | |
154 * running tests on the ciphers, auth funcs, and rng, and prints out a | |
155 * status report. Possible return values are: | |
156 * | |
157 * err_status_ok all tests were passed | |
158 * <other> a test failed | |
159 * | |
160 */ | |
161 | |
162 err_status_t | |
163 crypto_kernel_status(void); | |
164 | |
165 | |
166 /* | |
167 * crypto_kernel_list_debug_modules() outputs a list of debugging modules | |
168 * | |
169 */ | |
170 | |
171 err_status_t | |
172 crypto_kernel_list_debug_modules(void); | |
173 | |
174 /* | |
175 * crypto_kernel_load_cipher_type() | |
176 * | |
177 */ | |
178 | |
179 err_status_t | |
180 crypto_kernel_load_cipher_type(cipher_type_t *ct, cipher_type_id_t id); | |
181 | |
182 err_status_t | |
183 crypto_kernel_load_auth_type(auth_type_t *ct, auth_type_id_t id); | |
184 | |
185 /* | |
186 * crypto_kernel_replace_cipher_type(ct, id) | |
187 * | |
188 * replaces the crypto kernel's existing cipher for the cipher_type id | |
189 * with a new one passed in externally. The new cipher must pass all the | |
190 * existing cipher_type's self tests as well as its own. | |
191 */ | |
192 err_status_t | |
193 crypto_kernel_replace_cipher_type(cipher_type_t *ct, cipher_type_id_t id); | |
194 | |
195 | |
196 /* | |
197 * crypto_kernel_replace_auth_type(ct, id) | |
198 * | |
199 * replaces the crypto kernel's existing cipher for the auth_type id | |
200 * with a new one passed in externally. The new auth type must pass all the | |
201 * existing auth_type's self tests as well as its own. | |
202 */ | |
203 err_status_t | |
204 crypto_kernel_replace_auth_type(auth_type_t *ct, auth_type_id_t id); | |
205 | |
206 | |
207 err_status_t | |
208 crypto_kernel_load_debug_module(debug_module_t *new_dm); | |
209 | |
210 /* | |
211 * crypto_kernel_alloc_cipher(id, cp, key_len); | |
212 * | |
213 * allocates a cipher of type id at location *cp, with key length | |
214 * key_len octets. Return values are: | |
215 * | |
216 * err_status_ok no problems | |
217 * err_status_alloc_fail an allocation failure occured | |
218 * err_status_fail couldn't find cipher with identifier 'id' | |
219 */ | |
220 | |
221 err_status_t | |
222 crypto_kernel_alloc_cipher(cipher_type_id_t id, | |
223 cipher_pointer_t *cp, | |
224 int key_len, | |
225 int tag_len); | |
226 | |
227 /* | |
228 * crypto_kernel_alloc_auth(id, ap, key_len, tag_len); | |
229 * | |
230 * allocates an auth function of type id at location *ap, with key | |
231 * length key_len octets and output tag length of tag_len. Return | |
232 * values are: | |
233 * | |
234 * err_status_ok no problems | |
235 * err_status_alloc_fail an allocation failure occured | |
236 * err_status_fail couldn't find auth with identifier 'id' | |
237 */ | |
238 | |
239 err_status_t | |
240 crypto_kernel_alloc_auth(auth_type_id_t id, | |
241 auth_pointer_t *ap, | |
242 int key_len, | |
243 int tag_len); | |
244 | |
245 | |
246 /* | |
247 * crypto_kernel_set_debug_module(mod_name, v) | |
248 * | |
249 * sets dynamic debugging to the value v (0 for off, 1 for on) for the | |
250 * debug module with the name mod_name | |
251 * | |
252 * returns err_status_ok on success, err_status_fail otherwise | |
253 */ | |
254 | |
255 err_status_t | |
256 crypto_kernel_set_debug_module(char *mod_name, int v); | |
257 | |
258 /** | |
259 * @brief writes a random octet string. | |
260 * | |
261 * The function call crypto_get_random(dest, len) writes len octets of | |
262 * random data to the location to which dest points, and returns an | |
263 * error code. This error code @b must be checked, and if a failure is | |
264 * reported, the data in the buffer @b must @b not be used. | |
265 * | |
266 * @warning If the return code is not checked, then non-random | |
267 * data may be in the buffer. This function will fail | |
268 * unless it is called after crypto_kernel_init(). | |
269 * | |
270 * @return | |
271 * - err_status_ok if no problems occured. | |
272 * - [other] a problem occured, and no assumptions should | |
273 * be made about the contents of the destination | |
274 * buffer. | |
275 * | |
276 * @ingroup SRTP | |
277 */ | |
278 err_status_t | |
279 crypto_get_random(unsigned char *buffer, unsigned int length); | |
280 | |
281 #endif /* CRYPTO_KERNEL */ | |
OLD | NEW |