cipher.h (9627B)
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-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 SRTP_CIPHER_H 46 #define SRTP_CIPHER_H 47 48 #include "srtp.h" 49 #include "crypto_types.h" /* for values of cipher_type_id_t */ 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /* 56 * srtp_cipher_direction_t defines a particular cipher operation. 57 * 58 * A srtp_cipher_direction_t is an enum that describes a particular cipher 59 * operation, i.e. encryption or decryption. For some ciphers, this 60 * distinction does not matter, but for others, it is essential. 61 */ 62 typedef enum { 63 srtp_direction_encrypt, /**< encryption (convert plaintext to ciphertext) */ 64 srtp_direction_decrypt, /**< decryption (convert ciphertext to plaintext) */ 65 srtp_direction_any /**< encryption or decryption */ 66 } srtp_cipher_direction_t; 67 68 /* 69 * the srtp_cipher_pointer_t definition is needed 70 * as srtp_cipher_t is not yet defined 71 */ 72 typedef struct srtp_cipher_t *srtp_cipher_pointer_t; 73 74 /* 75 * a srtp_cipher_alloc_func_t allocates (but does not initialize) a 76 * srtp_cipher_t 77 */ 78 typedef srtp_err_status_t (*srtp_cipher_alloc_func_t)(srtp_cipher_pointer_t *cp, 79 int key_len, 80 int tag_len); 81 82 /* 83 * a srtp_cipher_init_func_t [re-]initializes a cipher_t with a given key 84 */ 85 typedef srtp_err_status_t (*srtp_cipher_init_func_t)(void *state, 86 const uint8_t *key); 87 88 /* a srtp_cipher_dealloc_func_t de-allocates a cipher_t */ 89 typedef srtp_err_status_t (*srtp_cipher_dealloc_func_t)( 90 srtp_cipher_pointer_t cp); 91 92 /* 93 * a srtp_cipher_set_aad_func_t processes the AAD data for AEAD ciphers 94 */ 95 typedef srtp_err_status_t (*srtp_cipher_set_aad_func_t)(void *state, 96 const uint8_t *aad, 97 uint32_t aad_len); 98 99 /* a srtp_cipher_encrypt_func_t encrypts data in-place */ 100 typedef srtp_err_status_t (*srtp_cipher_encrypt_func_t)( 101 void *state, 102 uint8_t *buffer, 103 unsigned int *octets_to_encrypt); 104 105 /* a srtp_cipher_decrypt_func_t decrypts data in-place */ 106 typedef srtp_err_status_t (*srtp_cipher_decrypt_func_t)( 107 void *state, 108 uint8_t *buffer, 109 unsigned int *octets_to_decrypt); 110 111 /* 112 * a srtp_cipher_set_iv_func_t function sets the current initialization vector 113 */ 114 typedef srtp_err_status_t (*srtp_cipher_set_iv_func_t)( 115 void *state, 116 uint8_t *iv, 117 srtp_cipher_direction_t direction); 118 119 /* 120 * a cipher_get_tag_func_t function is used to get the authentication 121 * tag that was calculated by an AEAD cipher. 122 */ 123 typedef srtp_err_status_t (*srtp_cipher_get_tag_func_t)(void *state, 124 uint8_t *tag, 125 uint32_t *len); 126 127 /* 128 * srtp_cipher_test_case_t is a (list of) key, salt, plaintext, ciphertext, 129 * and aad values that are known to be correct for a 130 * particular cipher. this data can be used to test an implementation 131 * in an on-the-fly self test of the correctness of the implementation. 132 * (see the srtp_cipher_type_self_test() function below) 133 */ 134 typedef struct srtp_cipher_test_case_t { 135 int key_length_octets; /* octets in key */ 136 const uint8_t *key; /* key */ 137 uint8_t *idx; /* packet index */ 138 unsigned int plaintext_length_octets; /* octets in plaintext */ 139 const uint8_t *plaintext; /* plaintext */ 140 unsigned int ciphertext_length_octets; /* octets in plaintext */ 141 const uint8_t *ciphertext; /* ciphertext */ 142 int aad_length_octets; /* octets in AAD */ 143 const uint8_t *aad; /* AAD */ 144 int tag_length_octets; /* Length of AEAD tag */ 145 const struct srtp_cipher_test_case_t 146 *next_test_case; /* pointer to next testcase */ 147 } srtp_cipher_test_case_t; 148 149 /* srtp_cipher_type_t defines the 'metadata' for a particular cipher type */ 150 typedef struct srtp_cipher_type_t { 151 srtp_cipher_alloc_func_t alloc; 152 srtp_cipher_dealloc_func_t dealloc; 153 srtp_cipher_init_func_t init; 154 srtp_cipher_set_aad_func_t set_aad; 155 srtp_cipher_encrypt_func_t encrypt; 156 srtp_cipher_decrypt_func_t decrypt; 157 srtp_cipher_set_iv_func_t set_iv; 158 srtp_cipher_get_tag_func_t get_tag; 159 const char *description; 160 const srtp_cipher_test_case_t *test_data; 161 srtp_cipher_type_id_t id; 162 } srtp_cipher_type_t; 163 164 /* 165 * srtp_cipher_t defines an instantiation of a particular cipher, with fixed 166 * key length, key and salt values 167 */ 168 typedef struct srtp_cipher_t { 169 const srtp_cipher_type_t *type; 170 void *state; 171 int key_len; 172 int algorithm; 173 } srtp_cipher_t; 174 175 /* some bookkeeping functions */ 176 int srtp_cipher_get_key_length(const srtp_cipher_t *c); 177 178 /* 179 * srtp_cipher_type_self_test() tests a cipher against test cases provided in 180 * an array of values of key/srtp_xtd_seq_num_t/plaintext/ciphertext 181 * that is known to be good 182 */ 183 srtp_err_status_t srtp_cipher_type_self_test(const srtp_cipher_type_t *ct); 184 185 /* 186 * srtp_cipher_type_test() tests a cipher against external test cases provided 187 * in 188 * an array of values of key/srtp_xtd_seq_num_t/plaintext/ciphertext 189 * that is known to be good 190 */ 191 srtp_err_status_t srtp_cipher_type_test( 192 const srtp_cipher_type_t *ct, 193 const srtp_cipher_test_case_t *test_data); 194 195 /* 196 * srtp_cipher_bits_per_second(c, l, t) computes (an estimate of) the 197 * number of bits that a cipher implementation can encrypt in a second 198 * 199 * c is a cipher (which MUST be allocated and initialized already), l 200 * is the length in octets of the test data to be encrypted, and t is 201 * the number of trials 202 * 203 * if an error is encountered, then the value 0 is returned 204 */ 205 uint64_t srtp_cipher_bits_per_second(srtp_cipher_t *c, 206 int octets_in_buffer, 207 int num_trials); 208 209 srtp_err_status_t srtp_cipher_type_alloc(const srtp_cipher_type_t *ct, 210 srtp_cipher_t **c, 211 int key_len, 212 int tlen); 213 srtp_err_status_t srtp_cipher_dealloc(srtp_cipher_t *c); 214 srtp_err_status_t srtp_cipher_init(srtp_cipher_t *c, const uint8_t *key); 215 srtp_err_status_t srtp_cipher_set_iv(srtp_cipher_t *c, 216 uint8_t *iv, 217 int direction); 218 srtp_err_status_t srtp_cipher_output(srtp_cipher_t *c, 219 uint8_t *buffer, 220 uint32_t *num_octets_to_output); 221 srtp_err_status_t srtp_cipher_encrypt(srtp_cipher_t *c, 222 uint8_t *buffer, 223 uint32_t *num_octets_to_output); 224 srtp_err_status_t srtp_cipher_decrypt(srtp_cipher_t *c, 225 uint8_t *buffer, 226 uint32_t *num_octets_to_output); 227 srtp_err_status_t srtp_cipher_get_tag(srtp_cipher_t *c, 228 uint8_t *buffer, 229 uint32_t *tag_len); 230 srtp_err_status_t srtp_cipher_set_aad(srtp_cipher_t *c, 231 const uint8_t *aad, 232 uint32_t aad_len); 233 234 /* 235 * srtp_replace_cipher_type(ct, id) 236 * 237 * replaces srtp's existing cipher implementation for the cipher_type id 238 * with a new one passed in externally. The new cipher must pass all the 239 * existing cipher_type's self tests as well as its own. 240 */ 241 srtp_err_status_t srtp_replace_cipher_type(const srtp_cipher_type_t *ct, 242 srtp_cipher_type_id_t id); 243 244 #ifdef __cplusplus 245 } 246 #endif 247 248 #endif /* SRTP_CIPHER_H */