1 /*
2  * ngtcp2
3  *
4  * Copyright (c) 2019 ngtcp2 contributors
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining
7  * a copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, sublicense, and/or sell copies of the Software, and to
11  * permit persons to whom the Software is furnished to do so, subject to
12  * the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be
15  * included in all copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24  */
25 #ifndef NGTCP2_SHARED_H
26 #define NGTCP2_SHARED_H
27 
28 #ifdef HAVE_CONFIG_H
29 #  include <config.h>
30 #endif /* HAVE_CONFIG_H */
31 
32 #include <ngtcp2/ngtcp2_crypto.h>
33 
34 /**
35  * @macro
36  *
37  * :macro:`NGTCP2_INITIAL_SALT_DRAFT` is a salt value which is used to
38  * derive initial secret.  It is used for QUIC draft versions.
39  */
40 #define NGTCP2_INITIAL_SALT_DRAFT                                              \
41   "\xaf\xbf\xec\x28\x99\x93\xd2\x4c\x9e\x97\x86\xf1\x9c\x61\x11\xe0\x43\x90"   \
42   "\xa8\x99"
43 
44 /**
45  * @macro
46  *
47  * :macro:`NGTCP2_INITIAL_SALT_V1` is a salt value which is used to
48  * derive initial secret.  It is used for QUIC v1.
49  */
50 #define NGTCP2_INITIAL_SALT_V1                                                 \
51   "\x38\x76\x2c\xf7\xf5\x59\x34\xb3\x4d\x17\x9a\xe6\xa4\xc8\x0c\xad\xcc\xbb"   \
52   "\x7f\x0a"
53 
54 /**
55  * @macro
56  *
57  * :macro:`NGTCP2_INITIAL_SALT_V2_DRAFT` is a salt value which is used to
58  * derive initial secret.  It is used for QUIC v2 draft.
59  */
60 #define NGTCP2_INITIAL_SALT_V2_DRAFT                                           \
61   "\xa7\x07\xc2\x03\xa5\x9b\x47\x18\x4a\x1d\x62\xca\x57\x04\x06\xea\x7a\xe3"   \
62   "\xe5\xd3"
63 
64 /* Maximum key usage (encryption) limits */
65 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_AES_GCM (1ULL << 23)
66 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_CHACHA20_POLY1305 (1ULL << 62)
67 #define NGTCP2_CRYPTO_MAX_ENCRYPTION_AES_CCM (2965820ULL)
68 
69 /* Maximum authentication failure (decryption) limits during the
70    lifetime of a connection. */
71 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_AES_GCM (1ULL << 52)
72 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_CHACHA20_POLY1305 (1ULL << 36)
73 #define NGTCP2_CRYPTO_MAX_DECRYPTION_FAILURE_AES_CCM (2965820ULL)
74 
75 /**
76  * @function
77  *
78  * `ngtcp2_crypto_ctx_initial` initializes |ctx| for Initial packet
79  * encryption and decryption.
80  */
81 ngtcp2_crypto_ctx *ngtcp2_crypto_ctx_initial(ngtcp2_crypto_ctx *ctx);
82 
83 /**
84  * @function
85  *
86  * `ngtcp2_crypto_aead_init` initializes |aead| with the provided
87  * |aead_native_handle| which is an underlying AEAD object.
88  *
89  * If libngtcp2_crypto_openssl is linked, |aead_native_handle| must be
90  * a pointer to EVP_CIPHER.
91  *
92  * If libngtcp2_crypto_gnutls is linked, |aead_native_handle| must be
93  * gnutls_cipher_algorithm_t casted to ``void *``.
94  *
95  * If libngtcp2_crypto_boringssl is linked, |aead_native_handle| must
96  * be a pointer to EVP_AEAD.
97  */
98 ngtcp2_crypto_aead *ngtcp2_crypto_aead_init(ngtcp2_crypto_aead *aead,
99                                             void *aead_native_handle);
100 
101 /**
102  * @function
103  *
104  * `ngtcp2_crypto_aead_retry` initializes |aead| with the AEAD cipher
105  * AEAD_AES_128_GCM for Retry packet integrity protection.
106  */
107 ngtcp2_crypto_aead *ngtcp2_crypto_aead_retry(ngtcp2_crypto_aead *aead);
108 
109 /**
110  * @function
111  *
112  * `ngtcp2_crypto_derive_initial_secrets` derives initial secrets.
113  * |rx_secret| and |tx_secret| must point to the buffer of at least 32
114  * bytes capacity.  rx for read and tx for write.  This function
115  * writes rx and tx secrets into |rx_secret| and |tx_secret|
116  * respectively.  The length of secret is 32 bytes long.
117  * |client_dcid| is the destination connection ID in first Initial
118  * packet of client.  If |initial_secret| is not NULL, the initial
119  * secret is written to it.  It must point to the buffer which has at
120  * least 32 bytes capacity.  The initial secret is 32 bytes long.
121  * |side| specifies the side of application.
122  *
123  * This function returns 0 if it succeeds, or -1.
124  */
125 int ngtcp2_crypto_derive_initial_secrets(uint32_t version, uint8_t *rx_secret,
126                                          uint8_t *tx_secret,
127                                          uint8_t *initial_secret,
128                                          const ngtcp2_cid *client_dcid,
129                                          ngtcp2_crypto_side side);
130 
131 /**
132  * @function
133  *
134  * `ngtcp2_crypto_derive_packet_protection_key` derives packet
135  * protection key.  This function writes packet protection key into
136  * the buffer pointed by |key|.  The length of derived key is
137  * `ngtcp2_crypto_aead_keylen(aead) <ngtcp2_crypto_aead_keylen>`
138  * bytes.  |key| must have enough capacity to store the key.  This
139  * function writes packet protection IV into |iv|.  The length of
140  * derived IV is `ngtcp2_crypto_packet_protection_ivlen(aead)
141  * <ngtcp2_crypto_packet_protection_ivlen>` bytes.  |iv| must have
142  * enough capacity to store the IV.
143  *
144  * If |hp| is not NULL, this function also derives packet header
145  * protection key and writes the key into the buffer pointed by |hp|.
146  * The length of derived key is `ngtcp2_crypto_aead_keylen(aead)
147  * <ngtcp2_crypto_aead_keylen>` bytes.  |hp|, if not NULL, must have
148  * enough capacity to store the key.
149  *
150  * This function returns 0 if it succeeds, or -1.
151  */
152 int ngtcp2_crypto_derive_packet_protection_key(uint8_t *key, uint8_t *iv,
153                                                uint8_t *hp, uint32_t version,
154                                                const ngtcp2_crypto_aead *aead,
155                                                const ngtcp2_crypto_md *md,
156                                                const uint8_t *secret,
157                                                size_t secretlen);
158 
159 /**
160  * @function
161  *
162  * `ngtcp2_crypto_update_traffic_secret` derives the next generation
163  * of the traffic secret.  |secret| specifies the current secret and
164  * its length is given in |secretlen|.  The length of new key is the
165  * same as the current key.  This function writes new key into the
166  * buffer pointed by |dest|.  |dest| must have the enough capacity to
167  * store the new key.
168  *
169  * This function returns 0 if it succeeds, or -1.
170  */
171 int ngtcp2_crypto_update_traffic_secret(uint8_t *dest,
172                                         const ngtcp2_crypto_md *md,
173                                         const uint8_t *secret,
174                                         size_t secretlen);
175 
176 /**
177  * @function
178  *
179  * `ngtcp2_crypto_set_local_transport_params` sets QUIC transport
180  * parameter, which is encoded in wire format and stored in the buffer
181  * pointed by |buf| of length |len|, to the native handle |tls|.
182  *
183  * |tls| points to a implementation dependent TLS session object.  If
184  * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL
185  * object.
186  *
187  * This function returns 0 if it succeeds, or -1.
188  */
189 int ngtcp2_crypto_set_local_transport_params(void *tls, const uint8_t *buf,
190                                              size_t len);
191 
192 /**
193  * @function
194  *
195  * `ngtcp2_crypto_set_remote_transport_params` retrieves a remote QUIC
196  * transport parameters from |tls| and sets it to |conn| using
197  * `ngtcp2_conn_set_remote_transport_params`.
198  *
199  * |tls| points to a implementation dependent TLS session object.  If
200  * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL
201  * object.
202  *
203  * This function returns 0 if it succeeds, or -1.
204  */
205 int ngtcp2_crypto_set_remote_transport_params(ngtcp2_conn *conn, void *tls);
206 
207 /**
208  * @function
209  *
210  * `ngtcp2_crypto_derive_and_install_initial_key` derives initial
211  * keying materials and installs keys to |conn|.
212  *
213  * If |rx_secret| is not NULL, the secret for decryption is written to
214  * the buffer pointed by |rx_secret|.  The length of secret is 32
215  * bytes, and |rx_secret| must point to the buffer which has enough
216  * capacity.
217  *
218  * If |tx_secret| is not NULL, the secret for encryption is written to
219  * the buffer pointed by |tx_secret|.  The length of secret is 32
220  * bytes, and |tx_secret| must point to the buffer which has enough
221  * capacity.
222  *
223  * If |initial_secret| is not NULL, the initial secret is written to
224  * the buffer pointed by |initial_secret|.  The length of secret is 32
225  * bytes, and |initial_secret| must point to the buffer which has
226  * enough capacity.
227  *
228  * |client_dcid| is the destination connection ID in first Initial
229  * packet of client.
230  *
231  * If |rx_key| is not NULL, the derived packet protection key for
232  * decryption is written to the buffer pointed by |rx_key|.  If
233  * |rx_iv| is not NULL, the derived packet protection IV for
234  * decryption is written to the buffer pointed by |rx_iv|.  If |rx_hp|
235  * is not NULL, the derived header protection key for decryption is
236  * written to the buffer pointed by |rx_hp|.
237  *
238  * If |tx_key| is not NULL, the derived packet protection key for
239  * encryption is written to the buffer pointed by |tx_key|.  If
240  * |tx_iv| is not NULL, the derived packet protection IV for
241  * encryption is written to the buffer pointed by |tx_iv|.  If |tx_hp|
242  * is not NULL, the derived header protection key for encryption is
243  * written to the buffer pointed by |tx_hp|.
244  *
245  * The length of packet protection key and header protection key is 16
246  * bytes long.  The length of packet protection IV is 12 bytes long.
247  *
248  * This function calls `ngtcp2_conn_set_initial_crypto_ctx` to set
249  * initial AEAD and message digest algorithm.  After the successful
250  * call of this function, application can use
251  * `ngtcp2_conn_get_initial_crypto_ctx` to get the object.
252  *
253  * This function returns 0 if it succeeds, or -1.
254  */
255 int ngtcp2_crypto_derive_and_install_initial_key(
256     ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret,
257     uint8_t *initial_secret, uint8_t *rx_key, uint8_t *rx_iv, uint8_t *rx_hp,
258     uint8_t *tx_key, uint8_t *tx_iv, uint8_t *tx_hp, uint32_t version,
259     const ngtcp2_cid *client_dcid);
260 
261 /**
262  * @function
263  *
264  * `ngtcp2_crypto_derive_and_install_vneg_initial_key` derives initial
265  * keying materials and installs keys to |conn|.  This function is
266  * dedicated to install keys for |version| which is negotiated, or
267  * being negotiated.
268  *
269  * If |rx_secret| is not NULL, the secret for decryption is written to
270  * the buffer pointed by |rx_secret|.  The length of secret is 32
271  * bytes, and |rx_secret| must point to the buffer which has enough
272  * capacity.
273  *
274  * If |tx_secret| is not NULL, the secret for encryption is written to
275  * the buffer pointed by |tx_secret|.  The length of secret is 32
276  * bytes, and |tx_secret| must point to the buffer which has enough
277  * capacity.
278  *
279  * If |initial_secret| is not NULL, the initial secret is written to
280  * the buffer pointed by |initial_secret|.  The length of secret is 32
281  * bytes, and |initial_secret| must point to the buffer which has
282  * enough capacity.
283  *
284  * |client_dcid| is the destination connection ID in first Initial
285  * packet of client.
286  *
287  * If |rx_key| is not NULL, the derived packet protection key for
288  * decryption is written to the buffer pointed by |rx_key|.  If
289  * |rx_iv| is not NULL, the derived packet protection IV for
290  * decryption is written to the buffer pointed by |rx_iv|.  If |rx_hp|
291  * is not NULL, the derived header protection key for decryption is
292  * written to the buffer pointed by |rx_hp|.
293  *
294  * If |tx_key| is not NULL, the derived packet protection key for
295  * encryption is written to the buffer pointed by |tx_key|.  If
296  * |tx_iv| is not NULL, the derived packet protection IV for
297  * encryption is written to the buffer pointed by |tx_iv|.  If |tx_hp|
298  * is not NULL, the derived header protection key for encryption is
299  * written to the buffer pointed by |tx_hp|.
300  *
301  * The length of packet protection key and header protection key is 16
302  * bytes long.  The length of packet protection IV is 12 bytes long.
303  *
304  * This function returns 0 if it succeeds, or -1.
305  */
306 int ngtcp2_crypto_derive_and_install_vneg_initial_key(
307     ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret,
308     uint8_t *initial_secret, uint8_t *rx_key, uint8_t *rx_iv, uint8_t *rx_hp,
309     uint8_t *tx_key, uint8_t *tx_iv, uint8_t *tx_hp, uint32_t version,
310     const ngtcp2_cid *client_dcid);
311 
312 /**
313  * @function
314  *
315  * `ngtcp2_crypto_cipher_ctx_encrypt_init` initializes |cipher_ctx|
316  * with new cipher context object for encryption which is constructed
317  * to use |key| as encryption key.  |cipher| specifies cipher to use.
318  *
319  * This function returns 0 if it succeeds, or -1.
320  */
321 int ngtcp2_crypto_cipher_ctx_encrypt_init(ngtcp2_crypto_cipher_ctx *cipher_ctx,
322                                           const ngtcp2_crypto_cipher *cipher,
323                                           const uint8_t *key);
324 
325 /**
326  * @function
327  *
328  * `ngtcp2_crypto_cipher_ctx_free` frees up resources used by
329  * |cipher_ctx|.  This function does not free the memory pointed by
330  * |cipher_ctx| itself.
331  */
332 void ngtcp2_crypto_cipher_ctx_free(ngtcp2_crypto_cipher_ctx *cipher_ctx);
333 
334 /*
335  * `ngtcp2_crypto_md_sha256` initializes |md| with SHA256 message
336  * digest algorithm and returns |md|.
337  */
338 ngtcp2_crypto_md *ngtcp2_crypto_md_sha256(ngtcp2_crypto_md *md);
339 
340 ngtcp2_crypto_aead *ngtcp2_crypto_aead_aes_128_gcm(ngtcp2_crypto_aead *aead);
341 
342 /*
343  * `ngtcp2_crypto_random` writes cryptographically-secure random
344  * |datalen| bytes into the buffer pointed by |data|.
345  *
346  * This function returns 0 if it succeeds, or -1.
347  */
348 int ngtcp2_crypto_random(uint8_t *data, size_t datalen);
349 
350 #endif /* NGTCP2_SHARED_H */
351