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 | |
226 | /* |
227 | * crypto_kernel_alloc_auth(id, ap, key_len, tag_len); |
228 | * |
229 | * allocates an auth function of type id at location *ap, with key |
230 | * length key_len octets and output tag length of tag_len. Return |
231 | * values are: |
232 | * |
233 | * err_status_ok no problems |
234 | * err_status_alloc_fail an allocation failure occured |
235 | * err_status_fail couldn't find auth with identifier 'id' |
236 | */ |
237 | |
238 | err_status_t |
239 | crypto_kernel_alloc_auth(auth_type_id_t id, |
240 | auth_pointer_t *ap, |
241 | int key_len, |
242 | int tag_len); |
243 | |
244 | |
245 | /* |
246 | * crypto_kernel_set_debug_module(mod_name, v) |
247 | * |
248 | * sets dynamic debugging to the value v (0 for off, 1 for on) for the |
249 | * debug module with the name mod_name |
250 | * |
251 | * returns err_status_ok on success, err_status_fail otherwise |
252 | */ |
253 | |
254 | err_status_t |
255 | crypto_kernel_set_debug_module(char *mod_name, int v); |
256 | |
257 | /** |
258 | * @brief writes a random octet string. |
259 | * |
260 | * The function call crypto_get_random(dest, len) writes len octets of |
261 | * random data to the location to which dest points, and returns an |
262 | * error code. This error code @b must be checked, and if a failure is |
263 | * reported, the data in the buffer @b must @b not be used. |
264 | * |
265 | * @warning If the return code is not checked, then non-random |
266 | * data may be in the buffer. This function will fail |
267 | * unless it is called after crypto_kernel_init(). |
268 | * |
269 | * @return |
270 | * - err_status_ok if no problems occured. |
271 | * - [other] a problem occured, and no assumptions should |
272 | * be made about the contents of the destination |
273 | * buffer. |
274 | * |
275 | * @ingroup SRTP |
276 | */ |
277 | err_status_t |
278 | crypto_get_random(unsigned char *buffer, unsigned int length); |
279 | |
280 | #endif /* CRYPTO_KERNEL */ |
281 | |