libSRTP  2.6.0
cipher.h
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,
64  srtp_direction_decrypt,
65  srtp_direction_any
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 */
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;
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,
243 
244 #ifdef __cplusplus
245 }
246 #endif
247 
248 #endif /* SRTP_CIPHER_H */
Definition: cipher.h:150
uint32_t srtp_cipher_type_id_t
A srtp_cipher_type_id_t is an identifier for a particular cipher type.
Definition: srtp.h:156
Definition: cipher.h:168
srtp_err_status_t
srtp_err_status_t defines error codes.
Definition: srtp.h:181
Definition: cipher.h:134