1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/srtp/src/crypto/include/crypto_kernel.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,280 @@
1.4 +/*
1.5 + * crypto_kernel.h
1.6 + *
1.7 + * header for the cryptographic kernel
1.8 + *
1.9 + * David A. McGrew
1.10 + * Cisco Systems, Inc.
1.11 + */
1.12 +/*
1.13 + *
1.14 + * Copyright(c) 2001-2006 Cisco Systems, Inc.
1.15 + * All rights reserved.
1.16 + *
1.17 + * Redistribution and use in source and binary forms, with or without
1.18 + * modification, are permitted provided that the following conditions
1.19 + * are met:
1.20 + *
1.21 + * Redistributions of source code must retain the above copyright
1.22 + * notice, this list of conditions and the following disclaimer.
1.23 + *
1.24 + * Redistributions in binary form must reproduce the above
1.25 + * copyright notice, this list of conditions and the following
1.26 + * disclaimer in the documentation and/or other materials provided
1.27 + * with the distribution.
1.28 + *
1.29 + * Neither the name of the Cisco Systems, Inc. nor the names of its
1.30 + * contributors may be used to endorse or promote products derived
1.31 + * from this software without specific prior written permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.34 + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.35 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
1.36 + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
1.37 + * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
1.38 + * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1.39 + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1.40 + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.41 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1.42 + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.43 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
1.44 + * OF THE POSSIBILITY OF SUCH DAMAGE.
1.45 + *
1.46 + */
1.47 +
1.48 +
1.49 +#ifndef CRYPTO_KERNEL
1.50 +#define CRYPTO_KERNEL
1.51 +
1.52 +#include "rand_source.h"
1.53 +#include "prng.h"
1.54 +#include "cipher.h"
1.55 +#include "auth.h"
1.56 +#include "cryptoalg.h"
1.57 +#include "stat.h"
1.58 +#include "err.h"
1.59 +#include "crypto_types.h"
1.60 +#include "key.h"
1.61 +#include "crypto.h"
1.62 +
1.63 +/*
1.64 + * crypto_kernel_state_t defines the possible states:
1.65 + *
1.66 + * insecure - not yet initialized
1.67 + * secure - initialized and passed self-tests
1.68 + */
1.69 +
1.70 +typedef enum {
1.71 + crypto_kernel_state_insecure,
1.72 + crypto_kernel_state_secure
1.73 +} crypto_kernel_state_t;
1.74 +
1.75 +/*
1.76 + * linked list of cipher types
1.77 + */
1.78 +
1.79 +typedef struct kernel_cipher_type {
1.80 + cipher_type_id_t id;
1.81 + cipher_type_t *cipher_type;
1.82 + struct kernel_cipher_type *next;
1.83 +} kernel_cipher_type_t;
1.84 +
1.85 +/*
1.86 + * linked list of auth types
1.87 + */
1.88 +
1.89 +typedef struct kernel_auth_type {
1.90 + auth_type_id_t id;
1.91 + auth_type_t *auth_type;
1.92 + struct kernel_auth_type *next;
1.93 +} kernel_auth_type_t;
1.94 +
1.95 +/*
1.96 + * linked list of debug modules
1.97 + */
1.98 +
1.99 +typedef struct kernel_debug_module {
1.100 + debug_module_t *mod;
1.101 + struct kernel_debug_module *next;
1.102 +} kernel_debug_module_t;
1.103 +
1.104 +
1.105 +/*
1.106 + * crypto_kernel_t is the data structure for the crypto kernel
1.107 + *
1.108 + * note that there is *exactly one* instance of this data type,
1.109 + * a global variable defined in crypto_kernel.c
1.110 + */
1.111 +
1.112 +typedef struct {
1.113 + crypto_kernel_state_t state; /* current state of kernel */
1.114 + kernel_cipher_type_t *cipher_type_list; /* list of all cipher types */
1.115 + kernel_auth_type_t *auth_type_list; /* list of all auth func types */
1.116 + kernel_debug_module_t *debug_module_list; /* list of all debug modules */
1.117 +} crypto_kernel_t;
1.118 +
1.119 +
1.120 +/*
1.121 + * crypto_kernel_t external api
1.122 + */
1.123 +
1.124 +
1.125 +/*
1.126 + * The function crypto_kernel_init() initialized the crypto kernel and
1.127 + * runs the self-test operations on the random number generators and
1.128 + * crypto algorithms. Possible return values are:
1.129 + *
1.130 + * err_status_ok initialization successful
1.131 + * <other> init failure
1.132 + *
1.133 + * If any value other than err_status_ok is returned, the
1.134 + * crypto_kernel MUST NOT be used.
1.135 + */
1.136 +
1.137 +err_status_t
1.138 +crypto_kernel_init(void);
1.139 +
1.140 +
1.141 +/*
1.142 + * The function crypto_kernel_shutdown() de-initializes the
1.143 + * crypto_kernel, zeroizes keys and other cryptographic material, and
1.144 + * deallocates any dynamically allocated memory. Possible return
1.145 + * values are:
1.146 + *
1.147 + * err_status_ok shutdown successful
1.148 + * <other> shutdown failure
1.149 + *
1.150 + */
1.151 +
1.152 +err_status_t
1.153 +crypto_kernel_shutdown(void);
1.154 +
1.155 +/*
1.156 + * The function crypto_kernel_stats() checks the the crypto_kernel,
1.157 + * running tests on the ciphers, auth funcs, and rng, and prints out a
1.158 + * status report. Possible return values are:
1.159 + *
1.160 + * err_status_ok all tests were passed
1.161 + * <other> a test failed
1.162 + *
1.163 + */
1.164 +
1.165 +err_status_t
1.166 +crypto_kernel_status(void);
1.167 +
1.168 +
1.169 +/*
1.170 + * crypto_kernel_list_debug_modules() outputs a list of debugging modules
1.171 + *
1.172 + */
1.173 +
1.174 +err_status_t
1.175 +crypto_kernel_list_debug_modules(void);
1.176 +
1.177 +/*
1.178 + * crypto_kernel_load_cipher_type()
1.179 + *
1.180 + */
1.181 +
1.182 +err_status_t
1.183 +crypto_kernel_load_cipher_type(cipher_type_t *ct, cipher_type_id_t id);
1.184 +
1.185 +err_status_t
1.186 +crypto_kernel_load_auth_type(auth_type_t *ct, auth_type_id_t id);
1.187 +
1.188 +/*
1.189 + * crypto_kernel_replace_cipher_type(ct, id)
1.190 + *
1.191 + * replaces the crypto kernel's existing cipher for the cipher_type id
1.192 + * with a new one passed in externally. The new cipher must pass all the
1.193 + * existing cipher_type's self tests as well as its own.
1.194 + */
1.195 +err_status_t
1.196 +crypto_kernel_replace_cipher_type(cipher_type_t *ct, cipher_type_id_t id);
1.197 +
1.198 +
1.199 +/*
1.200 + * crypto_kernel_replace_auth_type(ct, id)
1.201 + *
1.202 + * replaces the crypto kernel's existing cipher for the auth_type id
1.203 + * with a new one passed in externally. The new auth type must pass all the
1.204 + * existing auth_type's self tests as well as its own.
1.205 + */
1.206 +err_status_t
1.207 +crypto_kernel_replace_auth_type(auth_type_t *ct, auth_type_id_t id);
1.208 +
1.209 +
1.210 +err_status_t
1.211 +crypto_kernel_load_debug_module(debug_module_t *new_dm);
1.212 +
1.213 +/*
1.214 + * crypto_kernel_alloc_cipher(id, cp, key_len);
1.215 + *
1.216 + * allocates a cipher of type id at location *cp, with key length
1.217 + * key_len octets. Return values are:
1.218 + *
1.219 + * err_status_ok no problems
1.220 + * err_status_alloc_fail an allocation failure occured
1.221 + * err_status_fail couldn't find cipher with identifier 'id'
1.222 + */
1.223 +
1.224 +err_status_t
1.225 +crypto_kernel_alloc_cipher(cipher_type_id_t id,
1.226 + cipher_pointer_t *cp,
1.227 + int key_len);
1.228 +
1.229 +/*
1.230 + * crypto_kernel_alloc_auth(id, ap, key_len, tag_len);
1.231 + *
1.232 + * allocates an auth function of type id at location *ap, with key
1.233 + * length key_len octets and output tag length of tag_len. Return
1.234 + * values are:
1.235 + *
1.236 + * err_status_ok no problems
1.237 + * err_status_alloc_fail an allocation failure occured
1.238 + * err_status_fail couldn't find auth with identifier 'id'
1.239 + */
1.240 +
1.241 +err_status_t
1.242 +crypto_kernel_alloc_auth(auth_type_id_t id,
1.243 + auth_pointer_t *ap,
1.244 + int key_len,
1.245 + int tag_len);
1.246 +
1.247 +
1.248 +/*
1.249 + * crypto_kernel_set_debug_module(mod_name, v)
1.250 + *
1.251 + * sets dynamic debugging to the value v (0 for off, 1 for on) for the
1.252 + * debug module with the name mod_name
1.253 + *
1.254 + * returns err_status_ok on success, err_status_fail otherwise
1.255 + */
1.256 +
1.257 +err_status_t
1.258 +crypto_kernel_set_debug_module(char *mod_name, int v);
1.259 +
1.260 +/**
1.261 + * @brief writes a random octet string.
1.262 + *
1.263 + * The function call crypto_get_random(dest, len) writes len octets of
1.264 + * random data to the location to which dest points, and returns an
1.265 + * error code. This error code @b must be checked, and if a failure is
1.266 + * reported, the data in the buffer @b must @b not be used.
1.267 + *
1.268 + * @warning If the return code is not checked, then non-random
1.269 + * data may be in the buffer. This function will fail
1.270 + * unless it is called after crypto_kernel_init().
1.271 + *
1.272 + * @return
1.273 + * - err_status_ok if no problems occured.
1.274 + * - [other] a problem occured, and no assumptions should
1.275 + * be made about the contents of the destination
1.276 + * buffer.
1.277 + *
1.278 + * @ingroup SRTP
1.279 + */
1.280 +err_status_t
1.281 +crypto_get_random(unsigned char *buffer, unsigned int length);
1.282 +
1.283 +#endif /* CRYPTO_KERNEL */
