@@ -175,7 +175,7 @@ ngtcp2_crypto_packet_protection_ivlen(const ngtcp2_crypto_aead *aead);
175175/**
176176 * @function
177177 *
178- * `ngtcp2_crypto_derive_packet_protection_key` dervies packet
178+ * `ngtcp2_crypto_derive_packet_protection_key` derives packet
179179 * protection key. This function writes packet protection key into
180180 * the buffer pointed by |key|. |key| must point to the buffer which
181181 * is at least ngtcp2_crypto_aead_keylen(aead) bytes long. This
@@ -237,7 +237,7 @@ ngtcp2_crypto_encrypt_cb(uint8_t *dest, const ngtcp2_crypto_aead *aead,
237237 * `ngtcp2_crypto_decrypt` decrypts |ciphertext| of length
238238 * |ciphertextlen| and writes the plaintext into the buffer pointed by
239239 * |dest|. The length of plaintext is ciphertextlen -
240- * ngtcp2_crypto_aead_taglen(aead) bytes log . |dest| must have enough
240+ * ngtcp2_crypto_aead_taglen(aead) bytes long . |dest| must have enough
241241 * capacity to store the plaintext. It is allowed to specify the same
242242 * value to |dest| and |ciphertext|.
243243 *
@@ -298,32 +298,17 @@ NGTCP2_EXTERN int ngtcp2_crypto_hp_mask_cb(uint8_t *dest,
298298/**
299299 * @function
300300 *
301- * `ngtcp2_crypto_derive_and_install_key` derives the rx and tx keys
302- * from |rx_secret| and |tx_secret| respectively and installs new keys
303- * to |conn|.
301+ * `ngtcp2_crypto_derive_and_install_rx_key` derives the rx keys from
302+ * |secret| and installs new keys to |conn|.
303+ *
304+ * If |key| is not NULL, the derived packet protection key for
305+ * decryption is written to the buffer pointed by |key|. If |iv| is
306+ * not NULL, the derived packet protection IV for decryption is
307+ * written to the buffer pointed by |iv|. If |hp| is not NULL, the
308+ * derived header protection key for decryption is written to the
309+ * buffer pointed by |hp|.
304310 *
305- * If |rx_key| is not NULL, the derived packet protection key for
306- * decryption is written to the buffer pointed by |rx_key|. If
307- * |rx_iv| is not NULL, the derived packet protection IV for
308- * decryption is written to the buffer pointed by |rx_iv|. If |rx_hp|
309- * is not NULL, the derived header protection key for decryption is
310- * written to the buffer pointed by |rx_hp|.
311- *
312- * If |tx_key| is not NULL, the derived packet protection key for
313- * encryption is written to the buffer pointed by |tx_key|. If
314- * |tx_iv| is not NULL, the derived packet protection IV for
315- * encryption is written to the buffer pointed by |tx_iv|. If |tx_hp|
316- * is not NULL, the derived header protection key for encryption is
317- * written to the buffer pointed by |tx_hp|.
318- *
319- * |level| specifies the encryption level. If |level| is
320- * NGTCP2_CRYPTO_LEVEL_EARLY, and if |side| is
321- * NGTCP2_CRYPTO_SIDE_CLIENT, |rx_secret| must be NULL. If |level| is
322- * NGTCP2_CRYPTO_LEVEL_EARLY, and if |side| is
323- * NGTCP2_CRYPTO_SIDE_SERVER, |tx_secret| must be NULL. Otherwise,
324- * |rx_secret| and |tx_secret| must not be NULL.
325- *
326- * |secretlen| specifies the length of |rx_secret| and |tx_secret|.
311+ * |secretlen| specifies the length of |secret|.
327312 *
328313 * The length of packet protection key and header protection key is
329314 * ngtcp2_crypto_aead(ctx->aead), and the length of packet protection
@@ -337,71 +322,48 @@ NGTCP2_EXTERN int ngtcp2_crypto_hp_mask_cb(uint8_t *dest,
337322 * It also calls `ngtcp2_conn_set_aead_overhead` to set AEAD tag
338323 * length.
339324 *
340- * If |level| is NGTCP2_CRYPTO_LEVEL_APP, this function retrieves a
341- * remote QUIC transport parameters extension from |tls| and sets it
342- * to |conn|.
343- *
344325 * This function returns 0 if it succeeds, or -1.
345326 */
346- NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_key (
347- ngtcp2_conn * conn , void * tls , uint8_t * rx_key , uint8_t * rx_iv ,
348- uint8_t * rx_hp , uint8_t * tx_key , uint8_t * tx_iv , uint8_t * tx_hp ,
349- ngtcp2_crypto_level level , const uint8_t * rx_secret ,
350- const uint8_t * tx_secret , size_t secretlen , ngtcp2_crypto_side side );
327+ NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_rx_key (
328+ ngtcp2_conn * conn , uint8_t * key , uint8_t * iv , uint8_t * hp ,
329+ ngtcp2_crypto_level level , const uint8_t * secret , size_t secretlen );
351330
352331/**
353332 * @function
354333 *
355- * `ngtcp2_crypto_derive_and_install_initial_key` derives initial
356- * keying materials and installs keys to |conn|.
357- *
358- * If |rx_secret| is not NULL, the secret for decryption is written to
359- * the buffer pointed by |rx_secret|. The length of secret is 32
360- * bytes, and |rx_secret| must point to the buffer which has enough
361- * capacity.
362- *
363- * If |tx_secret| is not NULL, the secret for encryption is written to
364- * the buffer pointed by |tx_secret|. The length of secret is 32
365- * bytes, and |tx_secret| must point to the buffer which has enough
366- * capacity.
367- *
368- * If |initial_secret| is not NULL, the initial secret is written to
369- * the buffer pointed by |initial_secret|. The length of secret is 32
370- * bytes, and |initial_secret| must point to the buffer which has
371- * enough capacity.
372- *
373- * |client_dcid| is the destination connection ID in first Initial
374- * packet of client.
375- *
376- * If |rx_key| is not NULL, the derived packet protection key for
377- * decryption is written to the buffer pointed by |rx_key|. If
378- * |rx_iv| is not NULL, the derived packet protection IV for
379- * decryption is written to the buffer pointed by |rx_iv|. If |rx_hp|
380- * is not NULL, the derived header protection key for decryption is
381- * written to the buffer pointed by |rx_hp|.
382- *
383- * If |tx_key| is not NULL, the derived packet protection key for
384- * encryption is written to the buffer pointed by |tx_key|. If
385- * |tx_iv| is not NULL, the derived packet protection IV for
386- * encryption is written to the buffer pointed by |tx_iv|. If |tx_hp|
387- * is not NULL, the derived header protection key for encryption is
388- * written to the buffer pointed by |tx_hp|.
389- *
390- * The length of packet protection key and header protection key is 16
391- * bytes long. The length of packet protection IV is 12 bytes long.
392- *
393- * This function calls `ngtcp2_conn_set_initial_crypto_ctx` to set
394- * initial AEAD and message digest algorithm. After the successful
395- * call of this function, application can use
396- * `ngtcp2_conn_get_initial_crypto_ctx` to get the object.
334+ * `ngtcp2_crypto_derive_and_install_tx_key` derives the tx keys from
335+ * |secret| and installs new keys to |conn|.
336+ *
337+ * If |key| is not NULL, the derived packet protection key for
338+ * encryption is written to the buffer pointed by |key|. If |iv| is
339+ * not NULL, the derived packet protection IV for encryption is
340+ * written to the buffer pointed by |iv|. If |hp| is not NULL, the
341+ * derived header protection key for encryption is written to the
342+ * buffer pointed by |hp|.
343+ *
344+ * |secretlen| specifies the length of |secret|.
345+ *
346+ * The length of packet protection key and header protection key is
347+ * ngtcp2_crypto_aead(ctx->aead), and the length of packet protection
348+ * IV is ngtcp2_crypto_packet_protection_ivlen(ctx->aead) where ctx
349+ * can be obtained by `ngtcp2_crypto_ctx_tls`.
350+ *
351+ * In the first call of this function, it calls
352+ * `ngtcp2_conn_set_crypto_ctx` to set negotiated AEAD and message
353+ * digest algorithm. After the successful call of this function,
354+ * application can use `ngtcp2_conn_get_crypto_ctx` to get the object.
355+ * It also calls `ngtcp2_conn_set_aead_overhead` to set AEAD tag
356+ * length.
357+ *
358+ * If |level| is NGTCP2_CRYPTO_LEVEL_APP, this function retrieves a
359+ * remote QUIC transport parameters extension from |tls| and sets it
360+ * to |conn|.
397361 *
398362 * This function returns 0 if it succeeds, or -1.
399363 */
400- NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_initial_key (
401- ngtcp2_conn * conn , uint8_t * rx_secret , uint8_t * tx_secret ,
402- uint8_t * initial_secret , uint8_t * rx_key , uint8_t * rx_iv , uint8_t * rx_hp ,
403- uint8_t * tx_key , uint8_t * tx_iv , uint8_t * tx_hp ,
404- const ngtcp2_cid * client_dcid , ngtcp2_crypto_side side );
364+ NGTCP2_EXTERN int ngtcp2_crypto_derive_and_install_tx_key (
365+ ngtcp2_conn * conn , uint8_t * key , uint8_t * iv , uint8_t * hp ,
366+ ngtcp2_crypto_level level , const uint8_t * secret , size_t secretlen );
405367
406368/**
407369 * @function
@@ -458,6 +420,54 @@ NGTCP2_EXTERN int ngtcp2_crypto_update_key_cb(
458420 const uint8_t * current_rx_secret , const uint8_t * current_tx_secret ,
459421 size_t secretlen , void * user_data );
460422
423+ /**
424+ * @function
425+ *
426+ * `ngtcp2_crypto_client_initial_cb` installs initial secrets and
427+ * encryption keys and sets QUIC transport parameters.
428+ *
429+ * This function can be directly passed to client_initial field in
430+ * ngtcp2_callbacks. It is only used by client.
431+ *
432+ * This function returns 0 if it succeeds, or
433+ * :enum:`NGTCP2_ERR_CALLBACK_FAILURE`.
434+ */
435+ NGTCP2_EXTERN int ngtcp2_crypto_client_initial_cb (ngtcp2_conn * conn ,
436+ void * user_data );
437+
438+ /**
439+ * @function
440+ *
441+ * `ngtcp2_crypto_recv_retry_cb` re-installs initial secrets in
442+ * response to incoming Retry packet.
443+ *
444+ * This function can be directly passed to recv_retry field in
445+ * ngtcp2_callbacks. It is only used by client.
446+ *
447+ * This function returns 0 if it succeeds, or
448+ * :enum:`NGTCP2_ERR_CALLBACK_FAILURE`.
449+ */
450+ NGTCP2_EXTERN int ngtcp2_crypto_recv_retry_cb (ngtcp2_conn * conn ,
451+ const ngtcp2_pkt_hd * hd ,
452+ void * user_data );
453+
454+ /**
455+ * @function
456+ *
457+ * `ngtcp2_crypto_recv_client_initial_cb` installs initial secrets in
458+ * response to an incoming Initial packet from client, and sets QUIC
459+ * transport parameters.
460+ *
461+ * This function can be directly passed to recv_client_initial field
462+ * in ngtcp2_callbacks. It is only used by server.
463+ *
464+ * This function returns 0 if it succeeds, or
465+ * :enum:`NGTCP2_ERR_CALLBACK_FAILURE`.
466+ */
467+ NGTCP2_EXTERN int ngtcp2_crypto_recv_client_initial_cb (ngtcp2_conn * conn ,
468+ const ngtcp2_cid * dcid ,
469+ void * user_data );
470+
461471/**
462472 * @function
463473 *
@@ -468,38 +478,17 @@ NGTCP2_EXTERN int ngtcp2_crypto_update_key_cb(
468478 * allowed to call this function with datalen == 0. In this case, no
469479 * additional read operation is done.
470480 *
471- * |tls| points to a implementation dependent TLS session object. If
472- * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL
473- * object.
474- *
475481 * This function returns 0 if it succeeds, or a negative error code.
476482 * The generic error code is -1 if a specific error code is not
477483 * suitable. The error codes less than -10000 are specific to
478484 * underlying TLS implementation. For OpenSSL, the error codes are
479485 * defined in ngtcp2_crypto_openssl.h.
480486 */
481487NGTCP2_EXTERN int
482- ngtcp2_crypto_read_write_crypto_data (ngtcp2_conn * conn , void * tls ,
488+ ngtcp2_crypto_read_write_crypto_data (ngtcp2_conn * conn ,
483489 ngtcp2_crypto_level crypto_level ,
484490 const uint8_t * data , size_t datalen );
485491
486- /**
487- * @function
488- *
489- * `ngtcp2_crypto_set_remote_transport_params` retrieves a remote QUIC
490- * transport parameters from |tls| and sets it to |conn| using
491- * `ngtcp2_conn_set_remote_transport_params`.
492- *
493- * |tls| points to a implementation dependent TLS session object. If
494- * libngtcp2_crypto_openssl is linked, |tls| must be a pointer to SSL
495- * object.
496- *
497- * This function returns 0 if it succeeds, or -1.
498- */
499- NGTCP2_EXTERN int
500- ngtcp2_crypto_set_remote_transport_params (ngtcp2_conn * conn , void * tls ,
501- ngtcp2_crypto_side side );
502-
503492/**
504493 * @function
505494 *
0 commit comments