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