ngtcp2_conn_install_initial_key

Synopsis

#include <ngtcp2/ngtcp2.h>

int ngtcp2_conn_install_initial_key(ngtcp2_conn *conn, const ngtcp2_crypto_aead_ctx *rx_aead_ctx, const uint8_t *rx_iv, const ngtcp2_crypto_cipher_ctx *rx_hp_ctx, const ngtcp2_crypto_aead_ctx *tx_aead_ctx, const uint8_t *tx_iv, const ngtcp2_crypto_cipher_ctx *tx_hp_ctx, size_t ivlen)

ngtcp2_conn_install_initial_key() installs packet protection keying materials for Initial packets. rx_aead_ctx is AEAD cipher context object, and must be initialized with a decryption key. rx_iv is IV of length rx_ivlen for decryption. rx_hp_ctx is a packet header protection cipher context object for decryption. Similarly, tx_aead_ctx, tx_iv and tx_hp_ctx are for encrypting outgoing packets, and are the same length with the decryption counterpart . If they have already been set, they are overwritten.

ivlen must be the minimum length of AEAD nonce, or 8 bytes if that is larger.

If this function succeeds, conn takes ownership of rx_aead_ctx, rx_hp_ctx, tx_aead_ctx, and tx_hp_ctx. ngtcp2_callbacks.delete_crypto_aead_ctx and ngtcp2_callbacks.delete_crypto_cipher_ctx will be called to delete these objects when they are no longer used. If this function fails, the caller is responsible to delete them.

After receiving Retry packet, a Destination Connection ID that client sends in Initial packet most likely changes. In that case, client application must generate these keying materials again based on new Destination Connection ID, and install them again with this function.

This function returns 0 if it succeeds, or one of the following negative error codes:

NGTCP2_ERR_NOMEM

Out of memory.