1 /* 2 * cipher.h 3 * 4 * common interface to ciphers 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 CIPHER_H 47 #define CIPHER_H 48 49 #include "datatypes.h" 50 #include "rdbx.h" /* for xtd_seq_num_t */ 51 #include "err.h" /* for error codes */ 52 #include "crypto.h" /* for cipher_type_id_t */ 53 #include "crypto_types.h" /* for values of cipher_type_id_t */ 54 55 56 /** 57 * @brief cipher_direction_t defines a particular cipher operation. 58 * 59 * A cipher_direction_t is an enum that describes a particular cipher 60 * operation, i.e. encryption or decryption. For some ciphers, this 61 * distinction does not matter, but for others, it is essential. 62 */ 63 64 typedef enum { 65 direction_encrypt, /**< encryption (convert plaintext to ciphertext) */ 66 direction_decrypt, /**< decryption (convert ciphertext to plaintext) */ 67 direction_any /**< encryption or decryption */ 68 } cipher_direction_t; 69 70 /* 71 * the cipher_pointer and cipher_type_pointer definitions are needed 72 * as cipher_t and cipher_type_t are not yet defined 73 */ 74 75 typedef struct cipher_type_t *cipher_type_pointer_t; 76 typedef struct cipher_t *cipher_pointer_t; 77 78 /* 79 * a cipher_alloc_func_t allocates (but does not initialize) a cipher_t 80 */ 81 82 typedef err_status_t (*cipher_alloc_func_t) 83 (cipher_pointer_t *cp, int key_len); 84 85 /* 86 * a cipher_init_func_t [re-]initializes a cipher_t with a given key 87 * and direction (i.e., encrypt or decrypt) 88 */ 89 90 typedef err_status_t (*cipher_init_func_t) 91 (void *state, const uint8_t *key, int key_len, cipher_direction_t dir); 92 93 /* a cipher_dealloc_func_t de-allocates a cipher_t */ 94 95 typedef err_status_t (*cipher_dealloc_func_t)(cipher_pointer_t cp); 96 97 /* a cipher_set_segment_func_t sets the segment index of a cipher_t */ 98 99 typedef err_status_t (*cipher_set_segment_func_t) 100 (void *state, xtd_seq_num_t idx); 101 102 /* a cipher_encrypt_func_t encrypts data in-place */ 103 104 typedef err_status_t (*cipher_encrypt_func_t) 105 (void *state, uint8_t *buffer, unsigned int *octets_to_encrypt); 106 107 /* a cipher_decrypt_func_t decrypts data in-place */ 108 109 typedef err_status_t (*cipher_decrypt_func_t) 110 (void *state, uint8_t *buffer, unsigned int *octets_to_decrypt); 111 112 /* 113 * a cipher_set_iv_func_t function sets the current initialization vector 114 */ 115 116 typedef err_status_t (*cipher_set_iv_func_t) 117 (cipher_pointer_t cp, void *iv); 118 119 /* 120 * cipher_test_case_t is a (list of) key, salt, xtd_seq_num_t, 121 * plaintext, and ciphertext values that are known to be correct for a 122 * particular cipher. this data can be used to test an implementation 123 * in an on-the-fly self test of the correcness of the implementation. 124 * (see the cipher_type_self_test() function below) 125 */ 126 127 typedef struct cipher_test_case_t { 128 int key_length_octets; /* octets in key */ 129 uint8_t *key; /* key */ 130 uint8_t *idx; /* packet index */ 131 int plaintext_length_octets; /* octets in plaintext */ 132 uint8_t *plaintext; /* plaintext */ 133 int ciphertext_length_octets; /* octets in plaintext */ 134 uint8_t *ciphertext; /* ciphertext */ 135 struct cipher_test_case_t *next_test_case; /* pointer to next testcase */ 136 } cipher_test_case_t; 137 138 /* cipher_type_t defines the 'metadata' for a particular cipher type */ 139 140 typedef struct cipher_type_t { 141 cipher_alloc_func_t alloc; 142 cipher_dealloc_func_t dealloc; 143 cipher_init_func_t init; 144 cipher_encrypt_func_t encrypt; 145 cipher_encrypt_func_t decrypt; 146 cipher_set_iv_func_t set_iv; 147 char *description; 148 int ref_count; 149 cipher_test_case_t *test_data; 150 debug_module_t *debug; 151 cipher_type_id_t id; 152 } cipher_type_t; 153 154 /* 155 * cipher_t defines an instantiation of a particular cipher, with fixed 156 * key length, key and salt values 157 */ 158 159 typedef struct cipher_t { 160 cipher_type_t *type; 161 void *state; 162 int key_len; 163 #ifdef FORCE_64BIT_ALIGN 164 int pad; 165 #endif 166 } cipher_t; 167 168 /* some syntactic sugar on these function types */ 169 170 #define cipher_type_alloc(ct, c, klen) ((ct)->alloc((c), (klen))) 171 172 #define cipher_dealloc(c) (((c)->type)->dealloc(c)) 173 174 #define cipher_init(c, k, dir) (((c)->type)->init(((c)->state), (k), ((c)->key_len), (dir))) 175 176 #define cipher_encrypt(c, buf, len) \ 177 (((c)->type)->encrypt(((c)->state), (buf), (len))) 178 179 #define cipher_decrypt(c, buf, len) \ 180 (((c)->type)->decrypt(((c)->state), (buf), (len))) 181 182 #define cipher_set_iv(c, n) \ 183 ((c) ? (((c)->type)->set_iv(((cipher_pointer_t)(c)->state), (n))) : \ 184 err_status_no_such_op) 185 186 err_status_t 187 cipher_output(cipher_t *c, uint8_t *buffer, int num_octets_to_output); 188 189 190 /* some bookkeeping functions */ 191 192 int 193 cipher_get_key_length(const cipher_t *c); 194 195 196 /* 197 * cipher_type_self_test() tests a cipher against test cases provided in 198 * an array of values of key/xtd_seq_num_t/plaintext/ciphertext 199 * that is known to be good 200 */ 201 202 err_status_t 203 cipher_type_self_test(const cipher_type_t *ct); 204 205 206 /* 207 * cipher_type_test() tests a cipher against external test cases provided in 208 * an array of values of key/xtd_seq_num_t/plaintext/ciphertext 209 * that is known to be good 210 */ 211 212 err_status_t 213 cipher_type_test(const cipher_type_t *ct, const cipher_test_case_t *test_data); 214 215 216 /* 217 * cipher_bits_per_second(c, l, t) computes (and estimate of) the 218 * number of bits that a cipher implementation can encrypt in a second 219 * 220 * c is a cipher (which MUST be allocated and initialized already), l 221 * is the length in octets of the test data to be encrypted, and t is 222 * the number of trials 223 * 224 * if an error is encountered, then the value 0 is returned 225 */ 226 227 uint64_t 228 cipher_bits_per_second(cipher_t *c, int octets_in_buffer, int num_trials); 229 230 #endif /* CIPHER_H */ 231