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 err_status_t 186 crypto_kernel_load_debug_module(debug_module_t *new_dm); 187 188 /* 189 * crypto_kernel_alloc_cipher(id, cp, key_len); 190 * 191 * allocates a cipher of type id at location *cp, with key length 192 * key_len octets. Return values are: 193 * 194 * err_status_ok no problems 195 * err_status_alloc_fail an allocation failure occured 196 * err_status_fail couldn't find cipher with identifier 'id' 197 */ 198 199 err_status_t 200 crypto_kernel_alloc_cipher(cipher_type_id_t id, 201 cipher_pointer_t *cp, 202 int key_len); 203 204 /* 205 * crypto_kernel_alloc_auth(id, ap, key_len, tag_len); 206 * 207 * allocates an auth function of type id at location *ap, with key 208 * length key_len octets and output tag length of tag_len. Return 209 * values are: 210 * 211 * err_status_ok no problems 212 * err_status_alloc_fail an allocation failure occured 213 * err_status_fail couldn't find auth with identifier 'id' 214 */ 215 216 err_status_t 217 crypto_kernel_alloc_auth(auth_type_id_t id, 218 auth_pointer_t *ap, 219 int key_len, 220 int tag_len); 221 222 223 /* 224 * crypto_kernel_set_debug_module(mod_name, v) 225 * 226 * sets dynamic debugging to the value v (0 for off, 1 for on) for the 227 * debug module with the name mod_name 228 * 229 * returns err_status_ok on success, err_status_fail otherwise 230 */ 231 232 err_status_t 233 crypto_kernel_set_debug_module(char *mod_name, int v); 234 235 /** 236 * @brief writes a random octet string. 237 * 238 * The function call crypto_get_random(dest, len) writes len octets of 239 * random data to the location to which dest points, and returns an 240 * error code. This error code @b must be checked, and if a failure is 241 * reported, the data in the buffer @b must @b not be used. 242 * 243 * @warning If the return code is not checked, then non-random 244 * data may be in the buffer. This function will fail 245 * unless it is called after crypto_kernel_init(). 246 * 247 * @return 248 * - err_status_ok if no problems occured. 249 * - [other] a problem occured, and no assumptions should 250 * be made about the contents of the destination 251 * buffer. 252 * 253 * @ingroup SRTP 254 */ 255 err_status_t 256 crypto_get_random(unsigned char *buffer, unsigned int length); 257 258 #endif /* CRYPTO_KERNEL */ 259