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 67typedef 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 76typedef 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 86typedef 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 96typedef 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 109typedef 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 134err_status_t 135crypto_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 149err_status_t 150crypto_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 162err_status_t 163crypto_kernel_status(void); 164 165 166/* 167 * crypto_kernel_list_debug_modules() outputs a list of debugging modules 168 * 169 */ 170 171err_status_t 172crypto_kernel_list_debug_modules(void); 173 174/* 175 * crypto_kernel_load_cipher_type() 176 * 177 */ 178 179err_status_t 180crypto_kernel_load_cipher_type(cipher_type_t *ct, cipher_type_id_t id); 181 182err_status_t 183crypto_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 */ 192err_status_t 193crypto_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 */ 203err_status_t 204crypto_kernel_replace_auth_type(auth_type_t *ct, auth_type_id_t id); 205 206 207err_status_t 208crypto_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 221err_status_t 222crypto_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 238err_status_t 239crypto_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 254err_status_t 255crypto_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 */ 277err_status_t 278crypto_get_random(unsigned char *buffer, unsigned int length); 279 280#endif /* CRYPTO_KERNEL */ 281