ngtcp2_crypto.h 31 KB

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