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