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_CRYPTO_H 26 #define NGTCP2_CRYPTO_H 27 28 #include <ngtcp2/ngtcp2.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 #ifdef WIN32 35 # ifndef WIN32_LEAN_AND_MEAN 36 # define WIN32_LEAN_AND_MEAN 37 # endif 38 # include <ws2tcpip.h> 39 #endif /* WIN32 */ 40 41 /** 42 * @macro 43 * 44 * :macro:`NGTCP2_CRYPTO_INITIAL_SECRETLEN` is the length of secret 45 * for Initial packets. 46 */ 47 #define NGTCP2_CRYPTO_INITIAL_SECRETLEN 32 48 49 /** 50 * @macro 51 * 52 * :macro:`NGTCP2_CRYPTO_INITIAL_KEYLEN` is the length of key for 53 * Initial packets. 54 */ 55 #define NGTCP2_CRYPTO_INITIAL_KEYLEN 16 56 57 /** 58 * @macro 59 * 60 * :macro:`NGTCP2_CRYPTO_INITIAL_IVLEN` is the length of IV for 61 * Initial packets. 62 */ 63 #define NGTCP2_CRYPTO_INITIAL_IVLEN 12 64 65 /** 66 * @function 67 * 68 * `ngtcp2_crypto_ctx_tls` initializes |ctx| by extracting negotiated 69 * ciphers and message digests from native TLS session 70 * |tls_native_handle|. This is used for encrypting/decrypting 71 * Handshake and Short header packets. 72 * 73 * If libngtcp2_crypto_openssl is linked, |tls_native_handle| must be 74 * a pointer to SSL object. 75 */ 76 NGTCP2_EXTERN ngtcp2_crypto_ctx *ngtcp2_crypto_ctx_tls(ngtcp2_crypto_ctx *ctx, 77 void *tls_native_handle); 78 79 /** 80 * @function 81 * 82 * `ngtcp2_crypto_ctx_tls_early` initializes |ctx| by extracting early 83 * ciphers and message digests from native TLS session 84 * |tls_native_handle|. This is used for encrypting/decrypting 0RTT 85 * packets. 86 * 87 * If libngtcp2_crypto_openssl is linked, |tls_native_handle| must be 88 * a pointer to SSL object. 89 */ 90 NGTCP2_EXTERN ngtcp2_crypto_ctx * 91 ngtcp2_crypto_ctx_tls_early(ngtcp2_crypto_ctx *ctx, void *tls_native_handle); 92 93 /** 94 * @function 95 * 96 * `ngtcp2_crypto_md_init` initializes |md| with the provided 97 * |md_native_handle| which is an underlying message digest object. 98 * 99 * If libngtcp2_crypto_openssl is linked, |md_native_handle| must be a 100 * pointer to EVP_MD. 101 * 102 * If libngtcp2_crypto_gnutls is linked, |md_native_handle| must be 103 * gnutls_mac_algorithm_t casted to ``void *``. 104 * 105 * If libngtcp2_crypto_boringssl is linked, |md_native_handle| must be 106 * a pointer to EVP_MD. 107 */ 108 NGTCP2_EXTERN ngtcp2_crypto_md *ngtcp2_crypto_md_init(ngtcp2_crypto_md *md, 109 void *md_native_handle); 110 111 /** 112 * @function 113 * 114 * `ngtcp2_crypto_md_hashlen` returns the length of |md| output. 115 */ 116 NGTCP2_EXTERN size_t ngtcp2_crypto_md_hashlen(const ngtcp2_crypto_md *md); 117 118 /** 119 * @function 120 * 121 * `ngtcp2_crypto_aead_keylen` returns the length of key for |aead|. 122 */ 123 NGTCP2_EXTERN size_t ngtcp2_crypto_aead_keylen(const ngtcp2_crypto_aead *aead); 124 125 /** 126 * @function 127 * 128 * `ngtcp2_crypto_aead_noncelen` returns the length of nonce for 129 * |aead|. 130 */ 131 NGTCP2_EXTERN size_t 132 ngtcp2_crypto_aead_noncelen(const ngtcp2_crypto_aead *aead); 133 134 /** 135 * @function 136 * 137 * `ngtcp2_crypto_hkdf_extract` performs HKDF extract operation. The 138 * result is the length of |md| and is stored to the buffer pointed by 139 * |dest|. The caller is responsible to specify the buffer that can 140 * store the output. 141 * 142 * This function returns 0 if it succeeds, or -1. 143 */ 144 NGTCP2_EXTERN int 145 ngtcp2_crypto_hkdf_extract(uint8_t *dest, const ngtcp2_crypto_md *md, 146 const uint8_t *secret, size_t secretlen, 147 const uint8_t *salt, size_t saltlen); 148 149 /** 150 * @function 151 * 152 * `ngtcp2_crypto_hkdf_expand` performs HKDF expand operation. The 153 * result is |destlen| bytes long and is stored to the buffer pointed 154 * by |dest|. 155 * 156 * This function returns 0 if it succeeds, or -1. 157 */ 158 NGTCP2_EXTERN int ngtcp2_crypto_hkdf_expand(uint8_t *dest, size_t destlen, 159 const ngtcp2_crypto_md *md, 160 const uint8_t *secret, 161 size_t secretlen, 162 const uint8_t *info, 163 size_t infolen); 164 165 /** 166 * @function 167 * 168 * `ngtcp2_crypto_hkdf` performs HKDF operation. The result is 169 * |destlen| bytes long and is stored to the buffer pointed by |dest|. 170 * 171 * This function returns 0 if it succeeds, or -1. 172 */ 173 NGTCP2_EXTERN int ngtcp2_crypto_hkdf(uint8_t *dest, size_t destlen, 174 const ngtcp2_crypto_md *md, 175 const uint8_t *secret, size_t secretlen, 176 const uint8_t *salt, size_t saltlen, 177 const uint8_t *info, size_t infolen); 178 179 /** 180 * @function 181 * 182 * `ngtcp2_crypto_hkdf_expand_label` performs HKDF expand label. The 183 * result is |destlen| bytes long and is stored to the buffer pointed 184 * by |dest|. 185 * 186 * This function returns 0 if it succeeds, or -1. 187 */ 188 NGTCP2_EXTERN int ngtcp2_crypto_hkdf_expand_label(uint8_t *dest, size_t destlen, 189 const ngtcp2_crypto_md *md, 190 const uint8_t *secret, 191 size_t secretlen, 192 const uint8_t *label, 193 size_t labellen); 194 195 /** 196 * @enum 197 * 198 * :type:`ngtcp2_crypto_side` indicates which side the application 199 * implements; client or server. 200 */ 201 typedef enum ngtcp2_crypto_side { 202 /** 203 * :enum:`NGTCP2_CRYPTO_SIDE_CLIENT` indicates that the application 204 * is client. 205 */ 206 NGTCP2_CRYPTO_SIDE_CLIENT, 207 /** 208 * :enum:`NGTCP2_CRYPTO_SIDE_SERVER` indicates that the application 209 * is server. 210 */ 211 NGTCP2_CRYPTO_SIDE_SERVER 212 } ngtcp2_crypto_side; 213 214 /** 215 * @function 216 * 217 * `ngtcp2_crypto_packet_protection_ivlen` returns the length of IV 218 * used to encrypt QUIC packet. 219 */ 220 NGTCP2_EXTERN size_t 221 ngtcp2_crypto_packet_protection_ivlen(const ngtcp2_crypto_aead *aead); 222 223 /** 224 * @function 225 * 226 * `ngtcp2_crypto_encrypt` encrypts |plaintext| of length 227 * |plaintextlen| and writes the ciphertext into the buffer pointed by 228 * |dest|. The length of ciphertext is plaintextlen + 229 * :member:`aead->max_overhead <ngtcp2_crypto_aead.max_overhead>` 230 * bytes long. |dest| must have enough capacity to store the 231 * ciphertext. It is allowed to specify the same value to |dest| and 232 * |plaintext|. 233 * 234 * This function returns 0 if it succeeds, or -1. 235 */ 236 NGTCP2_EXTERN int ngtcp2_crypto_encrypt(uint8_t *dest, 237 const ngtcp2_crypto_aead *aead, 238 const ngtcp2_crypto_aead_ctx *aead_ctx, 239 const uint8_t *plaintext, 240 size_t plaintextlen, 241 const uint8_t *nonce, size_t noncelen, 242 const uint8_t *aad, size_t aadlen); 243 244 /** 245 * @function 246 * 247 * `ngtcp2_crypto_encrypt_cb` is a wrapper function around 248 * `ngtcp2_crypto_encrypt`. It can be directly passed to 249 * :member:`ngtcp2_callbacks.encrypt` field. 250 * 251 * This function returns 0 if it succeeds, or 252 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 253 */ 254 NGTCP2_EXTERN int 255 ngtcp2_crypto_encrypt_cb(uint8_t *dest, const ngtcp2_crypto_aead *aead, 256 const ngtcp2_crypto_aead_ctx *aead_ctx, 257 const uint8_t *plaintext, size_t plaintextlen, 258 const uint8_t *nonce, size_t noncelen, 259 const uint8_t *aad, size_t aadlen); 260 261 /** 262 * @function 263 * 264 * `ngtcp2_crypto_decrypt` decrypts |ciphertext| of length 265 * |ciphertextlen| and writes the plaintext into the buffer pointed by 266 * |dest|. The length of plaintext is ciphertextlen - 267 * :member:`aead->max_overhead <ngtcp2_crypto_aead.max_overhead>` 268 * bytes long. |dest| must have enough capacity to store the 269 * plaintext. It is allowed to specify the same value to |dest| and 270 * |ciphertext|. 271 * 272 * This function returns 0 if it succeeds, or -1. 273 */ 274 NGTCP2_EXTERN int ngtcp2_crypto_decrypt(uint8_t *dest, 275 const ngtcp2_crypto_aead *aead, 276 const ngtcp2_crypto_aead_ctx *aead_ctx, 277 const uint8_t *ciphertext, 278 size_t ciphertextlen, 279 const uint8_t *nonce, size_t noncelen, 280 const uint8_t *aad, size_t aadlen); 281 282 /** 283 * @function 284 * 285 * `ngtcp2_crypto_decrypt_cb` is a wrapper function around 286 * `ngtcp2_crypto_decrypt`. It can be directly passed to 287 * :member:`ngtcp2_callbacks.decrypt` field. 288 * 289 * This function returns 0 if it succeeds, or 290 * :macro:`NGTCP2_ERR_TLS_DECRYPT`. 291 */ 292 NGTCP2_EXTERN int 293 ngtcp2_crypto_decrypt_cb(uint8_t *dest, const ngtcp2_crypto_aead *aead, 294 const ngtcp2_crypto_aead_ctx *aead_ctx, 295 const uint8_t *ciphertext, size_t ciphertextlen, 296 const uint8_t *nonce, size_t noncelen, 297 const uint8_t *aad, size_t aadlen); 298 299 /** 300 * @function 301 * 302 * `ngtcp2_crypto_hp_mask` generates mask which is used in packet 303 * header encryption. The mask is written to the buffer pointed by 304 * |dest|. The sample is passed as |sample| which is 305 * :macro:`NGTCP2_HP_SAMPLELEN` bytes long. The length of mask must 306 * be at least :macro:`NGTCP2_HP_MASKLEN`. The library only uses the 307 * first :macro:`NGTCP2_HP_MASKLEN` bytes of the produced mask. The 308 * buffer pointed by |dest| must have at least 309 * :macro:`NGTCP2_HP_SAMPLELEN` bytes available. 310 * 311 * This function returns 0 if it succeeds, or -1. 312 */ 313 NGTCP2_EXTERN int ngtcp2_crypto_hp_mask(uint8_t *dest, 314 const ngtcp2_crypto_cipher *hp, 315 const ngtcp2_crypto_cipher_ctx *hp_ctx, 316 const uint8_t *sample); 317 318 /** 319 * @function 320 * 321 * `ngtcp2_crypto_hp_mask_cb` is a wrapper function around 322 * `ngtcp2_crypto_hp_mask`. It can be directly passed to 323 * :member:`ngtcp2_callbacks.hp_mask` field. 324 * 325 * This function returns 0 if it succeeds, or 326 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 327 */ 328 NGTCP2_EXTERN int 329 ngtcp2_crypto_hp_mask_cb(uint8_t *dest, const ngtcp2_crypto_cipher *hp, 330 const ngtcp2_crypto_cipher_ctx *hp_ctx, 331 const uint8_t *sample); 332 333 /** 334 * @function 335 * 336 * `ngtcp2_crypto_derive_and_install_rx_key` derives the rx keys from 337 * |secret| and installs new keys to |conn|. 338 * 339 * If |key| is not NULL, the derived packet protection key for 340 * decryption is written to the buffer pointed by |key|. If |iv| is 341 * not NULL, the derived packet protection IV for decryption is 342 * written to the buffer pointed by |iv|. If |hp| is not NULL, the 343 * derived header protection key for decryption is written to the 344 * buffer pointed by |hp|. 345 * 346 * |secretlen| specifies the length of |secret|. 347 * 348 * The length of packet protection key and header protection key is 349 * `ngtcp2_crypto_aead_keylen(ctx->aead) <ngtcp2_crypto_aead_keylen>`, 350 * and the length of packet protection IV is 351 * `ngtcp2_crypto_packet_protection_ivlen(ctx->aead) 352 * <ngtcp2_crypto_packet_protection_ivlen>` where ctx is obtained by 353 * `ngtcp2_crypto_ctx_tls` (or `ngtcp2_crypto_ctx_tls_early` if 354 * |level| == :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`). 355 * 356 * In the first call of this function, it calls 357 * `ngtcp2_conn_set_crypto_ctx` (or `ngtcp2_conn_set_early_crypto_ctx` 358 * if |level| == 359 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`) to set 360 * negotiated AEAD and message digest algorithm. After the successful 361 * call of this function, application can use 362 * `ngtcp2_conn_get_crypto_ctx` (or `ngtcp2_conn_get_early_crypto_ctx` 363 * if |level| == 364 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`) to get 365 * :type:`ngtcp2_crypto_ctx`. 366 * 367 * If |conn| is initialized as client, and |level| is 368 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_APPLICATION`, this 369 * function retrieves a remote QUIC transport parameters extension 370 * from an object obtained by `ngtcp2_conn_get_tls_native_handle` and 371 * sets it to |conn| by calling 372 * `ngtcp2_conn_decode_remote_transport_params`. 373 * 374 * This function returns 0 if it succeeds, or -1. 375 */ 376 NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_rx_key( 377 ngtcp2_conn *conn, uint8_t *key, uint8_t *iv, uint8_t *hp, 378 ngtcp2_crypto_level level, const uint8_t *secret, size_t secretlen); 379 380 /** 381 * @function 382 * 383 * `ngtcp2_crypto_derive_and_install_tx_key` derives the tx keys from 384 * |secret| and installs new keys to |conn|. 385 * 386 * If |key| is not NULL, the derived packet protection key for 387 * encryption is written to the buffer pointed by |key|. If |iv| is 388 * not NULL, the derived packet protection IV for encryption is 389 * written to the buffer pointed by |iv|. If |hp| is not NULL, the 390 * derived header protection key for encryption is written to the 391 * buffer pointed by |hp|. 392 * 393 * |secretlen| specifies the length of |secret|. 394 * 395 * The length of packet protection key and header protection key is 396 * `ngtcp2_crypto_aead_keylen(ctx->aead) <ngtcp2_crypto_aead_keylen>`, 397 * and the length of packet protection IV is 398 * `ngtcp2_crypto_packet_protection_ivlen(ctx->aead) 399 * <ngtcp2_crypto_packet_protection_ivlen>` where ctx is obtained by 400 * `ngtcp2_crypto_ctx_tls` (or `ngtcp2_crypto_ctx_tls_early` if 401 * |level| == :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`). 402 * 403 * In the first call of this function, it calls 404 * `ngtcp2_conn_set_crypto_ctx` (or `ngtcp2_conn_set_early_crypto_ctx` 405 * if |level| == 406 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`) to set 407 * negotiated AEAD and message digest algorithm. After the successful 408 * call of this function, application can use 409 * `ngtcp2_conn_get_crypto_ctx` (or `ngtcp2_conn_get_early_crypto_ctx` 410 * if |level| == 411 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_EARLY`) to get 412 * :type:`ngtcp2_crypto_ctx`. 413 * 414 * If |conn| is initialized as server, and |level| is 415 * :enum:`ngtcp2_crypto_level.NGTCP2_CRYPTO_LEVEL_APPLICATION`, this 416 * function retrieves a remote QUIC transport parameters extension 417 * from an object obtained by `ngtcp2_conn_get_tls_native_handle` and 418 * sets it to |conn| by calling 419 * `ngtcp2_conn_decode_remote_transport_params`. 420 * 421 * This function returns 0 if it succeeds, or -1. 422 */ 423 NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_tx_key( 424 ngtcp2_conn *conn, uint8_t *key, uint8_t *iv, uint8_t *hp, 425 ngtcp2_crypto_level level, const uint8_t *secret, size_t secretlen); 426 427 /** 428 * @function 429 * 430 * `ngtcp2_crypto_update_key` updates traffic keying materials. 431 * 432 * The new traffic secret for decryption is written to the buffer 433 * pointed by |rx_secret|. The length of secret is |secretlen| bytes, 434 * and |rx_secret| must point to the buffer which has enough capacity. 435 * 436 * The new traffic secret for encryption is written to the buffer 437 * pointed by |tx_secret|. The length of secret is |secretlen| bytes, 438 * and |tx_secret| must point to the buffer which has enough capacity. 439 * 440 * The derived packet protection key for decryption is written to the 441 * buffer pointed by |rx_key|. The derived packet protection IV for 442 * decryption is written to the buffer pointed by |rx_iv|. 443 * |rx_aead_ctx| must be constructed with |rx_key|. 444 * 445 * The derived packet protection key for encryption is written to the 446 * buffer pointed by |tx_key|. The derived packet protection IV for 447 * encryption is written to the buffer pointed by |tx_iv|. 448 * |tx_aead_ctx| must be constructed with |rx_key|. 449 * 450 * |current_rx_secret| and |current_tx_secret| are the current traffic 451 * secrets for decryption and encryption. |secretlen| specifies the 452 * length of |rx_secret| and |tx_secret|. 453 * 454 * The length of packet protection key and header protection key is 455 * `ngtcp2_crypto_aead_keylen(ctx->aead) <ngtcp2_crypto_aead_keylen>`, 456 * and the length of packet protection IV is 457 * `ngtcp2_crypto_packet_protection_ivlen(ctx->aead) 458 * <ngtcp2_crypto_packet_protection_ivlen>` where ctx is obtained by 459 * `ngtcp2_crypto_ctx_tls`. 460 * 461 * This function returns 0 if it succeeds, or -1. 462 */ 463 NGTCP2_EXTERN int ngtcp2_crypto_update_key( 464 ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret, 465 ngtcp2_crypto_aead_ctx *rx_aead_ctx, uint8_t *rx_key, uint8_t *rx_iv, 466 ngtcp2_crypto_aead_ctx *tx_aead_ctx, uint8_t *tx_key, uint8_t *tx_iv, 467 const uint8_t *current_rx_secret, const uint8_t *current_tx_secret, 468 size_t secretlen); 469 470 /** 471 * @function 472 * 473 * `ngtcp2_crypto_update_key_cb` is a wrapper function around 474 * `ngtcp2_crypto_update_key`. It can be directly passed to 475 * :member:`ngtcp2_callbacks.update_key` field. 476 * 477 * This function returns 0 if it succeeds, or 478 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 479 */ 480 NGTCP2_EXTERN int ngtcp2_crypto_update_key_cb( 481 ngtcp2_conn *conn, uint8_t *rx_secret, uint8_t *tx_secret, 482 ngtcp2_crypto_aead_ctx *rx_aead_ctx, uint8_t *rx_iv, 483 ngtcp2_crypto_aead_ctx *tx_aead_ctx, uint8_t *tx_iv, 484 const uint8_t *current_rx_secret, const uint8_t *current_tx_secret, 485 size_t secretlen, void *user_data); 486 487 /** 488 * @function 489 * 490 * `ngtcp2_crypto_client_initial_cb` installs initial secrets and 491 * encryption keys and sets QUIC transport parameters. 492 * 493 * This function can be directly passed to 494 * :member:`ngtcp2_callbacks.client_initial` field. It is only used 495 * by client. 496 * 497 * This function returns 0 if it succeeds, or 498 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 499 */ 500 NGTCP2_EXTERN int ngtcp2_crypto_client_initial_cb(ngtcp2_conn *conn, 501 void *user_data); 502 503 /** 504 * @function 505 * 506 * `ngtcp2_crypto_recv_retry_cb` re-installs initial secrets in 507 * response to incoming Retry packet. 508 * 509 * This function can be directly passed to 510 * :member:`ngtcp2_callbacks.recv_retry` field. It is only used 511 * by client. 512 * 513 * This function returns 0 if it succeeds, or 514 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 515 */ 516 NGTCP2_EXTERN int ngtcp2_crypto_recv_retry_cb(ngtcp2_conn *conn, 517 const ngtcp2_pkt_hd *hd, 518 void *user_data); 519 520 /** 521 * @function 522 * 523 * `ngtcp2_crypto_recv_client_initial_cb` installs initial secrets in 524 * response to an incoming Initial packet from client, and sets QUIC 525 * transport parameters. 526 * 527 * This function can be directly passed to 528 * :member:`ngtcp2_callbacks.recv_client_initial` field. It is 529 * only used by server. 530 * 531 * This function returns 0 if it succeeds, or 532 * :macro:`NGTCP2_ERR_CALLBACK_FAILURE`. 533 */ 534 NGTCP2_EXTERN int ngtcp2_crypto_recv_client_initial_cb(ngtcp2_conn *conn, 535 const ngtcp2_cid *dcid, 536 void *user_data); 537 538 /** 539 * @function 540 * 541 * `ngtcp2_crypto_read_write_crypto_data` reads CRYPTO data |data| of 542 * length |datalen| in encryption level |crypto_level| and may feed 543 * outgoing CRYPTO data to |conn|. This function can drive handshake. 544 * This function can be also used after handshake completes. It is 545 * allowed to call this function with |datalen| == 0. In this case, 546 * no additional read operation is done. 547 * 548 * This function returns 0 if it succeeds, or a negative error code. 549 * The generic error code is -1 if a specific error code is not 550 * suitable. The error codes less than -10000 are specific to 551 * underlying TLS implementation. For OpenSSL, the error codes are 552 * defined in *ngtcp2_crypto_openssl.h*. 553 */ 554 NGTCP2_EXTERN int 555 ngtcp2_crypto_read_write_crypto_data(ngtcp2_conn *conn, 556 ngtcp2_crypto_level crypto_level, 557 const uint8_t *data, size_t datalen); 558 559 /** 560 * @function 561 * 562 * `ngtcp2_crypto_recv_crypto_data_cb` is a wrapper function around 563 * `ngtcp2_crypto_read_write_crypto_data`. It can be directly passed 564 * to :member:`ngtcp2_callbacks.recv_crypto_data` field. 565 * 566 * If this function is used, the TLS implementation specific error 567 * codes described in `ngtcp2_crypto_read_write_crypto_data` are 568 * treated as if it returns -1. Do not use this function if an 569 * application wishes to use the TLS implementation specific error 570 * codes. 571 */ 572 NGTCP2_EXTERN int ngtcp2_crypto_recv_crypto_data_cb( 573 ngtcp2_conn *conn, ngtcp2_crypto_level crypto_level, uint64_t offset, 574 const uint8_t *data, size_t datalen, void *user_data); 575 576 /** 577 * @function 578 * 579 * `ngtcp2_crypto_generate_stateless_reset_token` generates a 580 * stateless reset token using HKDF extraction using the given |cid| 581 * and static key |secret| as input. The token will be written to 582 * the buffer pointed by |token| and it must have a capacity of at 583 * least :macro:`NGTCP2_STATELESS_RESET_TOKENLEN` bytes. 584 * 585 * This function returns 0 if it succeeds, or -1. 586 */ 587 NGTCP2_EXTERN int ngtcp2_crypto_generate_stateless_reset_token( 588 uint8_t *token, const uint8_t *secret, size_t secretlen, 589 const ngtcp2_cid *cid); 590 591 /** 592 * @macro 593 * 594 * :macro:`NGTCP2_CRYPTO_TOKEN_RAND_DATALEN` is the length of random 595 * data added to a token generated by 596 * `ngtcp2_crypto_generate_retry_token` or 597 * `ngtcp2_crypto_generate_regular_token`. 598 */ 599 #define NGTCP2_CRYPTO_TOKEN_RAND_DATALEN 32 600 601 /** 602 * @macro 603 * 604 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY` is the magic byte for 605 * Retry token generated by `ngtcp2_crypto_generate_retry_token`. 606 */ 607 #define NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY 0xb6 608 609 /** 610 * @macro 611 * 612 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_REGULAR` is the magic byte for a 613 * token generated by `ngtcp2_crypto_generate_regular_token`. 614 */ 615 #define NGTCP2_CRYPTO_TOKEN_MAGIC_REGULAR 0x36 616 617 /** 618 * @macro 619 * 620 * :macro:`NGTCP2_CRYPTO_MAX_RETRY_TOKENLEN` is the maximum length of 621 * a token generated by `ngtcp2_crypto_generate_retry_token`. 622 */ 623 #define NGTCP2_CRYPTO_MAX_RETRY_TOKENLEN \ 624 (/* magic = */ 1 + /* cid len = */ 1 + NGTCP2_MAX_CIDLEN + \ 625 sizeof(ngtcp2_tstamp) + /* aead tag = */ 16 + \ 626 NGTCP2_CRYPTO_TOKEN_RAND_DATALEN) 627 628 /** 629 * @macro 630 * 631 * :macro:`NGTCP2_CRYPTO_MAX_REGULAR_TOKENLEN` is the maximum length 632 * of a token generated by `ngtcp2_crypto_generate_regular_token`. 633 */ 634 #define NGTCP2_CRYPTO_MAX_REGULAR_TOKENLEN \ 635 (/* magic = */ 1 + sizeof(ngtcp2_tstamp) + /* aead tag = */ 16 + \ 636 NGTCP2_CRYPTO_TOKEN_RAND_DATALEN) 637 638 /** 639 * @function 640 * 641 * `ngtcp2_crypto_generate_retry_token` generates a token in the 642 * buffer pointed by |token| that is sent with Retry packet. The 643 * buffer pointed by |token| must have at least 644 * :macro:`NGTCP2_CRYPTO_MAX_RETRY_TOKENLEN` bytes long. The 645 * successfully generated token starts with 646 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY`. |secret| of length 647 * |secretlen| is an initial keying material to generate keys to 648 * encrypt the token. |version| is QUIC version. |remote_addr| of 649 * length |remote_addrlen| is an address of client. |retry_scid| is a 650 * Source Connection ID chosen by server and set in Retry packet. 651 * |odcid| is a Destination Connection ID in Initial packet sent by 652 * client. |ts| is the timestamp when the token is generated. 653 * 654 * This function returns the length of generated token if it succeeds, 655 * or -1. 656 */ 657 NGTCP2_EXTERN ngtcp2_ssize ngtcp2_crypto_generate_retry_token( 658 uint8_t *token, const uint8_t *secret, size_t secretlen, uint32_t version, 659 const ngtcp2_sockaddr *remote_addr, ngtcp2_socklen remote_addrlen, 660 const ngtcp2_cid *retry_scid, const ngtcp2_cid *odcid, ngtcp2_tstamp ts); 661 662 /** 663 * @function 664 * 665 * `ngtcp2_crypto_verify_retry_token` verifies Retry token stored in 666 * the buffer pointed by |token| of length |tokenlen|. |secret| of 667 * length |secretlen| is an initial keying material to generate keys 668 * to decrypt the token. |version| is QUIC version of the Initial 669 * packet that contains this token. |remote_addr| of length 670 * |remote_addrlen| is an address of client. |dcid| is a Destination 671 * Connection ID in Initial packet sent by client. |timeout| is the 672 * period during which the token is valid. |ts| is the current 673 * timestamp. When validation succeeds, the extracted Destination 674 * Connection ID (which is the Destination Connection ID in Initial 675 * packet sent by client that triggered Retry packet) is stored to the 676 * buffer pointed by |odcid|. 677 * 678 * This function returns 0 if it succeeds, or -1. 679 */ 680 NGTCP2_EXTERN int ngtcp2_crypto_verify_retry_token( 681 ngtcp2_cid *odcid, const uint8_t *token, size_t tokenlen, 682 const uint8_t *secret, size_t secretlen, uint32_t version, 683 const ngtcp2_sockaddr *remote_addr, ngtcp2_socklen remote_addrlen, 684 const ngtcp2_cid *dcid, ngtcp2_duration timeout, ngtcp2_tstamp ts); 685 686 /** 687 * @function 688 * 689 * `ngtcp2_crypto_generate_regular_token` generates a token in the 690 * buffer pointed by |token| that is sent with NEW_TOKEN frame. The 691 * buffer pointed by |token| must have at least 692 * :macro:`NGTCP2_CRYPTO_MAX_REGULAR_TOKENLEN` bytes long. The 693 * successfully generated token starts with 694 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_REGULAR`. |secret| of length 695 * |secretlen| is an initial keying material to generate keys to 696 * encrypt the token. |remote_addr| of length |remote_addrlen| is an 697 * address of client. |ts| is the timestamp when the token is 698 * generated. 699 * 700 * This function returns the length of generated token if it succeeds, 701 * or -1. 702 */ 703 NGTCP2_EXTERN ngtcp2_ssize ngtcp2_crypto_generate_regular_token( 704 uint8_t *token, const uint8_t *secret, size_t secretlen, 705 const ngtcp2_sockaddr *remote_addr, ngtcp2_socklen remote_addrlen, 706 ngtcp2_tstamp ts); 707 708 /** 709 * @function 710 * 711 * `ngtcp2_crypto_verify_regular_token` verifies a regular token 712 * stored in the buffer pointed by |token| of length |tokenlen|. 713 * |secret| of length |secretlen| is an initial keying material to 714 * generate keys to decrypt the token. |remote_addr| of length 715 * |remote_addrlen| is an address of client. |timeout| is the period 716 * during which the token is valid. |ts| is the current timestamp. 717 * 718 * This function returns 0 if it succeeds, or -1. 719 */ 720 NGTCP2_EXTERN int ngtcp2_crypto_verify_regular_token( 721 const uint8_t *token, size_t tokenlen, const uint8_t *secret, 722 size_t secretlen, const ngtcp2_sockaddr *remote_addr, 723 ngtcp2_socklen remote_addrlen, ngtcp2_duration timeout, ngtcp2_tstamp ts); 724 725 /** 726 * @function 727 * 728 * `ngtcp2_crypto_write_connection_close` writes Initial packet 729 * containing CONNECTION_CLOSE with the given |error_code| and the 730 * optional |reason| of length |reasonlen| to the buffer pointed by 731 * |dest| of length |destlen|. This function is designed for server 732 * to close connection without committing the state when validating 733 * Retry token fails. This function must not be used by client. The 734 * |dcid| must be the Source Connection ID in Initial packet from 735 * client. The |scid| must be the Destination Connection ID in 736 * Initial packet from client. |scid| is used to derive initial 737 * keying materials. 738 * 739 * This function wraps around `ngtcp2_pkt_write_connection_close` for 740 * easier use. 741 * 742 * This function returns 0 if it succeeds, or -1. 743 */ 744 NGTCP2_EXTERN ngtcp2_ssize ngtcp2_crypto_write_connection_close( 745 uint8_t *dest, size_t destlen, uint32_t version, const ngtcp2_cid *dcid, 746 const ngtcp2_cid *scid, uint64_t error_code, const uint8_t *reason, 747 size_t reasonlen); 748 749 /** 750 * @function 751 * 752 * `ngtcp2_crypto_write_retry` writes Retry packet to the buffer 753 * pointed by |dest| of length |destlen|. |odcid| specifies Original 754 * Destination Connection ID. |token| specifies Retry Token, and 755 * |tokenlen| specifies its length. 756 * 757 * This function wraps around `ngtcp2_pkt_write_retry` for easier use. 758 * 759 * This function returns 0 if it succeeds, or -1. 760 */ 761 NGTCP2_EXTERN ngtcp2_ssize ngtcp2_crypto_write_retry( 762 uint8_t *dest, size_t destlen, uint32_t version, const ngtcp2_cid *dcid, 763 const ngtcp2_cid *scid, const ngtcp2_cid *odcid, const uint8_t *token, 764 size_t tokenlen); 765 766 /** 767 * @function 768 * 769 * `ngtcp2_crypto_aead_ctx_encrypt_init` initializes |aead_ctx| with 770 * new AEAD cipher context object for encryption which is constructed 771 * to use |key| as encryption key. |aead| specifies AEAD cipher to 772 * use. |noncelen| is the length of nonce. 773 * 774 * This function returns 0 if it succeeds, or -1. 775 */ 776 NGTCP2_EXTERN int 777 ngtcp2_crypto_aead_ctx_encrypt_init(ngtcp2_crypto_aead_ctx *aead_ctx, 778 const ngtcp2_crypto_aead *aead, 779 const uint8_t *key, size_t noncelen); 780 781 /** 782 * @function 783 * 784 * `ngtcp2_crypto_aead_ctx_decrypt_init` initializes |aead_ctx| with 785 * new AEAD cipher context object for decryption which is constructed 786 * to use |key| as encryption key. |aead| specifies AEAD cipher to 787 * use. |noncelen| is the length of nonce. 788 * 789 * This function returns 0 if it succeeds, or -1. 790 */ 791 NGTCP2_EXTERN int 792 ngtcp2_crypto_aead_ctx_decrypt_init(ngtcp2_crypto_aead_ctx *aead_ctx, 793 const ngtcp2_crypto_aead *aead, 794 const uint8_t *key, size_t noncelen); 795 796 /** 797 * @function 798 * 799 * `ngtcp2_crypto_aead_ctx_free` frees up resources used by 800 * |aead_ctx|. This function does not free the memory pointed by 801 * |aead_ctx| itself. 802 */ 803 NGTCP2_EXTERN void 804 ngtcp2_crypto_aead_ctx_free(ngtcp2_crypto_aead_ctx *aead_ctx); 805 806 /** 807 * @function 808 * 809 * `ngtcp2_crypto_delete_crypto_aead_ctx_cb` deletes the given |aead_ctx|. 810 * 811 * This function can be directly passed to 812 * :member:`ngtcp2_callbacks.delete_crypto_aead_ctx` field. 813 */ 814 NGTCP2_EXTERN void ngtcp2_crypto_delete_crypto_aead_ctx_cb( 815 ngtcp2_conn *conn, ngtcp2_crypto_aead_ctx *aead_ctx, void *user_data); 816 817 /** 818 * @function 819 * 820 * `ngtcp2_crypto_delete_crypto_cipher_ctx_cb` deletes the given 821 * |cipher_ctx|. 822 * 823 * This function can be directly passed to 824 * :member:`ngtcp2_callbacks.delete_crypto_cipher_ctx` field. 825 */ 826 NGTCP2_EXTERN void ngtcp2_crypto_delete_crypto_cipher_ctx_cb( 827 ngtcp2_conn *conn, ngtcp2_crypto_cipher_ctx *cipher_ctx, void *user_data); 828 829 /** 830 * @function 831 * 832 * `ngtcp2_crypto_get_path_challenge_data_cb` writes unpredictable 833 * sequence of :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` bytes to |data| 834 * which is sent with PATH_CHALLENGE frame. 835 * 836 * This function can be directly passed to 837 * :member:`ngtcp2_callbacks.get_path_challenge_data` field. 838 */ 839 NGTCP2_EXTERN int ngtcp2_crypto_get_path_challenge_data_cb(ngtcp2_conn *conn, 840 uint8_t *data, 841 void *user_data); 842 843 /** 844 * @function 845 * 846 * `ngtcp2_crypto_version_negotiation_cb` installs Initial keys for 847 * |version| which is negotiated or being negotiated. |client_dcid| 848 * is the destination connection ID in first Initial packet of client. 849 * 850 * This function can be directly passed to 851 * :member:`ngtcp2_callbacks.version_negotiation` field. 852 */ 853 NGTCP2_EXTERN int 854 ngtcp2_crypto_version_negotiation_cb(ngtcp2_conn *conn, uint32_t version, 855 const ngtcp2_cid *client_dcid, 856 void *user_data); 857 858 typedef struct ngtcp2_crypto_conn_ref ngtcp2_crypto_conn_ref; 859 860 /** 861 * @functypedef 862 * 863 * :type:`ngtcp2_crypto_get_conn` is a callback function to get a 864 * pointer to :type:`ngtcp2_conn` from |conn_ref|. The implementation 865 * must return non-NULL :type:`ngtcp2_conn` object. 866 */ 867 typedef ngtcp2_conn *(*ngtcp2_crypto_get_conn)( 868 ngtcp2_crypto_conn_ref *conn_ref); 869 870 /** 871 * @struct 872 * 873 * :type:`ngtcp2_crypto_conn_ref` is a structure to get a pointer to 874 * :type:`ngtcp2_conn`. It is meant to be set to TLS native handle as 875 * an application specific data (e.g. SSL_set_app_data in OpenSSL). 876 */ 877 typedef struct ngtcp2_crypto_conn_ref { 878 /** 879 * :member:`get_conn` is a callback function to get a pointer to 880 * :type:`ngtcp2_conn` object. 881 */ 882 ngtcp2_crypto_get_conn get_conn; 883 /** 884 * :member:`user_data` is a pointer to arbitrary user data. 885 */ 886 void *user_data; 887 } ngtcp2_crypto_conn_ref; 888 889 #ifdef __cplusplus 890 } 891 #endif 892 893 #endif /* NGTCP2_CRYPTO_H */ 894