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-2017 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 #ifndef CRYPTO_KERNEL 46 #define CRYPTO_KERNEL 47 48 #include "cipher.h" 49 #include "auth.h" 50 #include "err.h" 51 #include "crypto_types.h" 52 #include "key.h" 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 /* 59 * crypto_kernel_state_t defines the possible states: 60 * 61 * insecure - not yet initialized 62 * secure - initialized and passed self-tests 63 */ 64 typedef enum { 65 srtp_crypto_kernel_state_insecure, 66 srtp_crypto_kernel_state_secure 67 } srtp_crypto_kernel_state_t; 68 69 /* 70 * linked list of cipher types 71 */ 72 typedef struct srtp_kernel_cipher_type { 73 srtp_cipher_type_id_t id; 74 const srtp_cipher_type_t *cipher_type; 75 struct srtp_kernel_cipher_type *next; 76 } srtp_kernel_cipher_type_t; 77 78 /* 79 * linked list of auth types 80 */ 81 typedef struct srtp_kernel_auth_type { 82 srtp_auth_type_id_t id; 83 const srtp_auth_type_t *auth_type; 84 struct srtp_kernel_auth_type *next; 85 } srtp_kernel_auth_type_t; 86 87 /* 88 * linked list of debug modules 89 */ 90 typedef struct srtp_kernel_debug_module { 91 srtp_debug_module_t *mod; 92 struct srtp_kernel_debug_module *next; 93 } srtp_kernel_debug_module_t; 94 95 /* 96 * crypto_kernel_t is the data structure for the crypto kernel 97 * 98 * note that there is *exactly one* instance of this data type, 99 * a global variable defined in crypto_kernel.c 100 */ 101 typedef struct { 102 srtp_crypto_kernel_state_t state; /* current state of kernel */ 103 srtp_kernel_cipher_type_t *cipher_type_list; /* list of all cipher types */ 104 srtp_kernel_auth_type_t *auth_type_list; /* list of all auth func types */ 105 srtp_kernel_debug_module_t 106 *debug_module_list; /* list of all debug modules */ 107 } srtp_crypto_kernel_t; 108 109 /* 110 * srtp_crypto_kernel_t external api 111 */ 112 113 /* 114 * The function srtp_crypto_kernel_init() initialized the crypto kernel and 115 * runs the self-test operations on the random number generators and 116 * crypto algorithms. Possible return values are: 117 * 118 * srtp_err_status_ok initialization successful 119 * <other> init failure 120 * 121 * If any value other than srtp_err_status_ok is returned, the 122 * crypto_kernel MUST NOT be used. 123 */ 124 srtp_err_status_t srtp_crypto_kernel_init(void); 125 126 /* 127 * The function srtp_crypto_kernel_shutdown() de-initializes the 128 * crypto_kernel, zeroizes keys and other cryptographic material, and 129 * deallocates any dynamically allocated memory. Possible return 130 * values are: 131 * 132 * srtp_err_status_ok shutdown successful 133 * <other> shutdown failure 134 * 135 */ 136 srtp_err_status_t srtp_crypto_kernel_shutdown(void); 137 138 /* 139 * The function srtp_crypto_kernel_stats() checks the the crypto_kernel, 140 * running tests on the ciphers, auth funcs, and rng, and prints out a 141 * status report. Possible return values are: 142 * 143 * srtp_err_status_ok all tests were passed 144 * <other> a test failed 145 * 146 */ 147 srtp_err_status_t srtp_crypto_kernel_status(void); 148 149 /* 150 * srtp_crypto_kernel_list_debug_modules() outputs a list of debugging modules 151 * 152 */ 153 srtp_err_status_t srtp_crypto_kernel_list_debug_modules(void); 154 155 /* 156 * srtp_crypto_kernel_load_cipher_type() 157 * 158 */ 159 srtp_err_status_t srtp_crypto_kernel_load_cipher_type( 160 const srtp_cipher_type_t *ct, 161 srtp_cipher_type_id_t id); 162 163 srtp_err_status_t srtp_crypto_kernel_load_auth_type(const srtp_auth_type_t *ct, 164 srtp_auth_type_id_t id); 165 166 srtp_err_status_t srtp_crypto_kernel_load_debug_module( 167 srtp_debug_module_t *new_dm); 168 169 /* 170 * srtp_crypto_kernel_alloc_cipher(id, cp, key_len); 171 * 172 * allocates a cipher of type id at location *cp, with key length 173 * key_len octets. Return values are: 174 * 175 * srtp_err_status_ok no problems 176 * srtp_err_status_alloc_fail an allocation failure occured 177 * srtp_err_status_fail couldn't find cipher with identifier 'id' 178 */ 179 srtp_err_status_t srtp_crypto_kernel_alloc_cipher(srtp_cipher_type_id_t id, 180 srtp_cipher_pointer_t *cp, 181 int key_len, 182 int tag_len); 183 184 /* 185 * srtp_crypto_kernel_alloc_auth(id, ap, key_len, tag_len); 186 * 187 * allocates an auth function of type id at location *ap, with key 188 * length key_len octets and output tag length of tag_len. Return 189 * values are: 190 * 191 * srtp_err_status_ok no problems 192 * srtp_err_status_alloc_fail an allocation failure occured 193 * srtp_err_status_fail couldn't find auth with identifier 'id' 194 */ 195 srtp_err_status_t srtp_crypto_kernel_alloc_auth(srtp_auth_type_id_t id, 196 srtp_auth_pointer_t *ap, 197 int key_len, 198 int tag_len); 199 200 /* 201 * srtp_crypto_kernel_set_debug_module(mod_name, v) 202 * 203 * sets dynamic debugging to the value v (0 for off, 1 for on) for the 204 * debug module with the name mod_name 205 * 206 * returns srtp_err_status_ok on success, srtp_err_status_fail otherwise 207 */ 208 srtp_err_status_t srtp_crypto_kernel_set_debug_module(const char *mod_name, 209 int v); 210 211 #ifdef __cplusplus 212 } 213 #endif 214 215 #endif /* CRYPTO_KERNEL */ 216