1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/srtp/src/crypto/include/cipher.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,230 @@
1.4 +/*
1.5 + * cipher.h
1.6 + *
1.7 + * common interface to ciphers
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 CIPHER_H
1.50 +#define CIPHER_H
1.51 +
1.52 +#include "datatypes.h"
1.53 +#include "rdbx.h" /* for xtd_seq_num_t */
1.54 +#include "err.h" /* for error codes */
1.55 +#include "crypto.h" /* for cipher_type_id_t */
1.56 +#include "crypto_types.h" /* for values of cipher_type_id_t */
1.57 +
1.58 +
1.59 +/**
1.60 + * @brief cipher_direction_t defines a particular cipher operation.
1.61 + *
1.62 + * A cipher_direction_t is an enum that describes a particular cipher
1.63 + * operation, i.e. encryption or decryption. For some ciphers, this
1.64 + * distinction does not matter, but for others, it is essential.
1.65 + */
1.66 +
1.67 +typedef enum {
1.68 + direction_encrypt, /**< encryption (convert plaintext to ciphertext) */
1.69 + direction_decrypt, /**< decryption (convert ciphertext to plaintext) */
1.70 + direction_any /**< encryption or decryption */
1.71 +} cipher_direction_t;
1.72 +
1.73 +/*
1.74 + * the cipher_pointer and cipher_type_pointer definitions are needed
1.75 + * as cipher_t and cipher_type_t are not yet defined
1.76 + */
1.77 +
1.78 +typedef struct cipher_type_t *cipher_type_pointer_t;
1.79 +typedef struct cipher_t *cipher_pointer_t;
1.80 +
1.81 +/*
1.82 + * a cipher_alloc_func_t allocates (but does not initialize) a cipher_t
1.83 + */
1.84 +
1.85 +typedef err_status_t (*cipher_alloc_func_t)
1.86 + (cipher_pointer_t *cp, int key_len);
1.87 +
1.88 +/*
1.89 + * a cipher_init_func_t [re-]initializes a cipher_t with a given key
1.90 + * and direction (i.e., encrypt or decrypt)
1.91 + */
1.92 +
1.93 +typedef err_status_t (*cipher_init_func_t)
1.94 +(void *state, const uint8_t *key, int key_len, cipher_direction_t dir);
1.95 +
1.96 +/* a cipher_dealloc_func_t de-allocates a cipher_t */
1.97 +
1.98 +typedef err_status_t (*cipher_dealloc_func_t)(cipher_pointer_t cp);
1.99 +
1.100 +/* a cipher_set_segment_func_t sets the segment index of a cipher_t */
1.101 +
1.102 +typedef err_status_t (*cipher_set_segment_func_t)
1.103 + (void *state, xtd_seq_num_t idx);
1.104 +
1.105 +/* a cipher_encrypt_func_t encrypts data in-place */
1.106 +
1.107 +typedef err_status_t (*cipher_encrypt_func_t)
1.108 + (void *state, uint8_t *buffer, unsigned int *octets_to_encrypt);
1.109 +
1.110 +/* a cipher_decrypt_func_t decrypts data in-place */
1.111 +
1.112 +typedef err_status_t (*cipher_decrypt_func_t)
1.113 + (void *state, uint8_t *buffer, unsigned int *octets_to_decrypt);
1.114 +
1.115 +/*
1.116 + * a cipher_set_iv_func_t function sets the current initialization vector
1.117 + */
1.118 +
1.119 +typedef err_status_t (*cipher_set_iv_func_t)
1.120 + (cipher_pointer_t cp, void *iv);
1.121 +
1.122 +/*
1.123 + * cipher_test_case_t is a (list of) key, salt, xtd_seq_num_t,
1.124 + * plaintext, and ciphertext values that are known to be correct for a
1.125 + * particular cipher. this data can be used to test an implementation
1.126 + * in an on-the-fly self test of the correcness of the implementation.
1.127 + * (see the cipher_type_self_test() function below)
1.128 + */
1.129 +
1.130 +typedef struct cipher_test_case_t {
1.131 + int key_length_octets; /* octets in key */
1.132 + uint8_t *key; /* key */
1.133 + uint8_t *idx; /* packet index */
1.134 + int plaintext_length_octets; /* octets in plaintext */
1.135 + uint8_t *plaintext; /* plaintext */
1.136 + int ciphertext_length_octets; /* octets in plaintext */
1.137 + uint8_t *ciphertext; /* ciphertext */
1.138 + struct cipher_test_case_t *next_test_case; /* pointer to next testcase */
1.139 +} cipher_test_case_t;
1.140 +
1.141 +/* cipher_type_t defines the 'metadata' for a particular cipher type */
1.142 +
1.143 +typedef struct cipher_type_t {
1.144 + cipher_alloc_func_t alloc;
1.145 + cipher_dealloc_func_t dealloc;
1.146 + cipher_init_func_t init;
1.147 + cipher_encrypt_func_t encrypt;
1.148 + cipher_encrypt_func_t decrypt;
1.149 + cipher_set_iv_func_t set_iv;
1.150 + char *description;
1.151 + int ref_count;
1.152 + cipher_test_case_t *test_data;
1.153 + debug_module_t *debug;
1.154 + cipher_type_id_t id;
1.155 +} cipher_type_t;
1.156 +
1.157 +/*
1.158 + * cipher_t defines an instantiation of a particular cipher, with fixed
1.159 + * key length, key and salt values
1.160 + */
1.161 +
1.162 +typedef struct cipher_t {
1.163 + cipher_type_t *type;
1.164 + void *state;
1.165 + int key_len;
1.166 +#ifdef FORCE_64BIT_ALIGN
1.167 + int pad;
1.168 +#endif
1.169 +} cipher_t;
1.170 +
1.171 +/* some syntactic sugar on these function types */
1.172 +
1.173 +#define cipher_type_alloc(ct, c, klen) ((ct)->alloc((c), (klen)))
1.174 +
1.175 +#define cipher_dealloc(c) (((c)->type)->dealloc(c))
1.176 +
1.177 +#define cipher_init(c, k, dir) (((c)->type)->init(((c)->state), (k), ((c)->key_len), (dir)))
1.178 +
1.179 +#define cipher_encrypt(c, buf, len) \
1.180 + (((c)->type)->encrypt(((c)->state), (buf), (len)))
1.181 +
1.182 +#define cipher_decrypt(c, buf, len) \
1.183 + (((c)->type)->decrypt(((c)->state), (buf), (len)))
1.184 +
1.185 +#define cipher_set_iv(c, n) \
1.186 + ((c) ? (((c)->type)->set_iv(((cipher_pointer_t)(c)->state), (n))) : \
1.187 + err_status_no_such_op)
1.188 +
1.189 +err_status_t
1.190 +cipher_output(cipher_t *c, uint8_t *buffer, int num_octets_to_output);
1.191 +
1.192 +
1.193 +/* some bookkeeping functions */
1.194 +
1.195 +int
1.196 +cipher_get_key_length(const cipher_t *c);
1.197 +
1.198 +
1.199 +/*
1.200 + * cipher_type_self_test() tests a cipher against test cases provided in
1.201 + * an array of values of key/xtd_seq_num_t/plaintext/ciphertext
1.202 + * that is known to be good
1.203 + */
1.204 +
1.205 +err_status_t
1.206 +cipher_type_self_test(const cipher_type_t *ct);
1.207 +
1.208 +
1.209 +/*
1.210 + * cipher_type_test() tests a cipher against external test cases provided in
1.211 + * an array of values of key/xtd_seq_num_t/plaintext/ciphertext
1.212 + * that is known to be good
1.213 + */
1.214 +
1.215 +err_status_t
1.216 +cipher_type_test(const cipher_type_t *ct, const cipher_test_case_t *test_data);
1.217 +
1.218 +
1.219 +/*
1.220 + * cipher_bits_per_second(c, l, t) computes (and estimate of) the
1.221 + * number of bits that a cipher implementation can encrypt in a second
1.222 + *
1.223 + * c is a cipher (which MUST be allocated and initialized already), l
1.224 + * is the length in octets of the test data to be encrypted, and t is
1.225 + * the number of trials
1.226 + *
1.227 + * if an error is encountered, then the value 0 is returned
1.228 + */
1.229 +
1.230 +uint64_t
1.231 +cipher_bits_per_second(cipher_t *c, int octets_in_buffer, int num_trials);
1.232 +
1.233 +#endif /* CIPHER_H */
