@@ -524,11 +524,14 @@ NGTCP2_EXTERN int ngtcp2_crypto_recv_client_initial_cb(ngtcp2_conn *conn,
524524 * completes. It is allowed to call this function with |datalen| ==
525525 * 0. In this case, no additional read operation is done.
526526 *
527+ * This function is implemented per TLS backend. See
528+ * :ref:`tls-integration` for more details.
529+ *
527530 * This function returns 0 if it succeeds, or a negative error code.
528531 * The generic error code is -1 if a specific error code is not
529532 * suitable. The error codes less than -10000 are specific to
530- * underlying TLS implementation. For quictls, the error codes are
531- * defined in *ngtcp2_crypto_quictls.h* .
533+ * underlying TLS implementation. Refer to the implementation
534+ * specific header files for error codes .
532535 */
533536NGTCP2_EXTERN int
534537ngtcp2_crypto_read_write_crypto_data (ngtcp2_conn * conn ,
@@ -542,11 +545,22 @@ ngtcp2_crypto_read_write_crypto_data(ngtcp2_conn *conn,
542545 * `ngtcp2_crypto_read_write_crypto_data`. It can be directly passed
543546 * to :member:`ngtcp2_callbacks.recv_crypto_data` field.
544547 *
548+ * For quictls and OpenSSL, the following error codes are treated as
549+ * success:
550+ *
551+ * - -10001 (e.g., :macro:`NGTCP2_CRYPTO_QUICTLS_ERR_TLS_WANT_X509_LOOKUP`)
552+ * - -10002 (e.g., :macro:`NGTCP2_CRYPTO_QUICTLS_ERR_TLS_WANT_CLIENT_HELLO_CB`)
553+ *
554+ * To continue the interrupted handshake, call
555+ * `ngtcp2_conn_continue_handshake`.
556+ *
557+ * See :ref:`tls-integration` for more details.
558+ *
545559 * If this function is used, the TLS implementation specific error
546560 * codes described in `ngtcp2_crypto_read_write_crypto_data` are
547- * treated as if it returns -1. Do not use this function if an
548- * application wishes to use the TLS implementation specific error
549- * codes.
561+ * treated as if it returns -1 except for those that are listed above.
562+ * Do not use this function if an application wishes to use the TLS
563+ * implementation specific error codes.
550564 */
551565NGTCP2_EXTERN int ngtcp2_crypto_recv_crypto_data_cb (
552566 ngtcp2_conn * conn , ngtcp2_encryption_level encryption_level , uint64_t offset ,
@@ -583,15 +597,15 @@ NGTCP2_EXTERN int ngtcp2_crypto_generate_stateless_reset_token(
583597 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY` is the magic byte for
584598 * Retry token generated by `ngtcp2_crypto_generate_retry_token`.
585599 */
586- #define NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY 0xb6
600+ #define NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY 0xB6
587601
588602/**
589603 * @macro
590604 *
591605 * :macro:`NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY2` is the magic byte for
592606 * Retry token generated by `ngtcp2_crypto_generate_retry_token2`.
593607 */
594- #define NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY2 0xb7
608+ #define NGTCP2_CRYPTO_TOKEN_MAGIC_RETRY2 0xB7
595609
596610/**
597611 * @macro
@@ -978,11 +992,29 @@ NGTCP2_EXTERN void ngtcp2_crypto_delete_crypto_cipher_ctx_cb(
978992 *
979993 * This function can be directly passed to
980994 * :member:`ngtcp2_callbacks.get_path_challenge_data` field.
995+ *
996+ * Deprecated since v1.22.0. Use
997+ * `ngtcp2_crypto_get_path_challenge_data2_cb` instead.
981998 */
982999NGTCP2_EXTERN int ngtcp2_crypto_get_path_challenge_data_cb (ngtcp2_conn * conn ,
9831000 uint8_t * data ,
9841001 void * user_data );
9851002
1003+ /**
1004+ * @function
1005+ *
1006+ * `ngtcp2_crypto_get_path_challenge_data2_cb` writes unpredictable
1007+ * sequence of :macro:`NGTCP2_PATH_CHALLENGE_DATALEN` bytes to |data|
1008+ * which is sent with PATH_CHALLENGE frame.
1009+ *
1010+ * This function can be directly passed to
1011+ * :member:`ngtcp2_callbacks.get_path_challenge_data2` field.
1012+ *
1013+ * This function has been available since v1.22.0.
1014+ */
1015+ NGTCP2_EXTERN int ngtcp2_crypto_get_path_challenge_data2_cb (
1016+ ngtcp2_conn * conn , ngtcp2_path_challenge_data * data , void * user_data );