Skip to main content
Version: 0.1.23

TLS 1.2

TLS 1.0, 1.1, and 1.2 implementation. Header: noxtls_tls12.h. Context extends dtls_context_t (which contains tls_context_t).

Types​

tls12_context_t​

TLS 1.2 context: base DTLS/TLS context plus handshake state (client/server random, cipher suite, keys, IVs, MAC keys, sequence numbers), server certificate, optional server RSA private key or crypto provider handle, key exchange (premaster secret, master secret, ECDHE/DHE context), handshake message buffer, client/server extensions, SNI, renegotiation and RFC 6066 max fragment length, RPK (RFC 7250) options, and workspace buffers. Initialized with tls12_context_init or tls12_context_init_with_version, freed with tls12_context_free.

API​

Context​

tls12_context_init​

noxtls_return_t tls12_context_init(tls12_context_t *ctx, tls_role_t role);

Initialize TLS 1.2 context (default TLS 1.2). Set I/O callbacks on ctx->base.base before connect/accept.

Returns: noxtls_return_t.

tls12_context_init_with_version​

noxtls_return_t tls12_context_init_with_version(tls12_context_t *ctx, tls_role_t role, uint16_t version);

Initialize for a specific version: TLS_VERSION_1_0, TLS_VERSION_1_1, or TLS_VERSION_1_2.

Returns: noxtls_return_t.

dtls12_context_init​

noxtls_return_t dtls12_context_init(tls12_context_t *ctx, tls_role_t role);

Initialize for DTLS 1.2. Use dtls_set_mtu and related DTLS options as needed.

Returns: noxtls_return_t.

tls12_context_free​

noxtls_return_t tls12_context_free(tls12_context_t *ctx);

Free TLS 1.2 context and owned resources.

Returns: noxtls_return_t.

Handshake and data​

tls12_connect​

noxtls_return_t tls12_connect(tls12_context_t *ctx);

Run full client handshake (Client Hello through Finished). Set server certificate verification expectations and optional SNI before calling.

Returns: noxtls_return_t.

tls12_accept​

noxtls_return_t tls12_accept(tls12_context_t *ctx);

Run full server handshake. Set server certificate and, for ECDHE-RSA/DHE-RSA, the server private key (or crypto provider) before calling.

Returns: noxtls_return_t.

tls12_send​

noxtls_return_t tls12_send(tls12_context_t *ctx, const uint8_t *data, uint32_t len);

Send application data (encrypted records). Call after handshake completes.

Returns: noxtls_return_t.

tls12_recv​

noxtls_return_t tls12_recv(tls12_context_t *ctx, uint8_t *data, uint32_t *len);

Receive application data. len is in/out: maximum buffer size in, actual bytes read out.

Returns: noxtls_return_t.

tls12_close​

noxtls_return_t tls12_close(tls12_context_t *ctx);

Send close_notify and transition to closing/closed state.

Returns: noxtls_return_t.

Server renegotiation​

tls12_send_hello_request​

noxtls_return_t tls12_send_hello_request(tls12_context_t *ctx);

Send HelloRequest to ask the client to renegotiate (RFC 5746).

Returns: noxtls_return_t.

Server key and certificate​

tls12_set_server_private_rsa​

void tls12_set_server_private_rsa(tls12_context_t *ctx, void *rsa_key);

Set server RSA private key (rsa_key_t*) for Server Key Exchange signature. Call before handshake when using ECDHE_RSA or DHE_RSA.

tls12_set_crypto_provider_server​

void tls12_set_crypto_provider_server(tls12_context_t *ctx, const noxtls_crypto_provider_t *provider, noxtls_crypto_key_handle_t server_key_handle);

Use a crypto provider (e.g. HSM/TPM) for server signing and decrypting Client Key Exchange instead of server_private_rsa. Call before handshake.

Raw Public Key (RFC 7250)​

tls12_set_server_use_rpk​

void tls12_set_server_use_rpk(tls12_context_t *ctx, int use_rpk);

Server: send Raw Public Key. Set server_cert/server_cert_len to SubjectPublicKeyInfo (DER). Call before handshake.

tls12_set_client_accept_server_rpk​

void tls12_set_client_accept_server_rpk(tls12_context_t *ctx, int accept);

Client: advertise acceptance of server RPK (server_certificate_type extension). Call before connect.

tls12_set_client_offer_client_rpk​

void tls12_set_client_offer_client_rpk(tls12_context_t *ctx, int offer);

Client: offer to send RPK for client auth (client_certificate_type extension). Call before connect.

Max fragment length (RFC 6066)​

tls12_set_max_fragment_length​

void tls12_set_max_fragment_length(tls12_context_t *ctx, uint8_t code);

Set max fragment length: 0 = disabled; 1 = 512, 2 = 1024, 3 = 2048, 4 = 4096 bytes. Call before handshake.

Key derivation (internal use)​

tls12_compute_master_secret​

noxtls_return_t tls12_compute_master_secret(tls12_context_t *ctx, const uint8_t *premaster_secret, uint32_t premaster_secret_len);

Compute master secret from premaster secret. Used internally during handshake.

Returns: noxtls_return_t.

tls12_derive_keys​

noxtls_return_t tls12_derive_keys(tls12_context_t *ctx);

Derive record protection keys from master secret. Used internally.

Returns: noxtls_return_t.

Client handshake steps (optional fine-grained control)​

  • tls12_send_client_hello, tls12_recv_server_hello, tls12_recv_certificate, tls12_recv_server_key_exchange, tls12_recv_server_hello_done
  • tls12_send_client_key_exchange, tls12_send_change_cipher_spec, tls12_send_finished
  • tls12_recv_change_cipher_spec, tls12_recv_finished

Server handshake steps (optional fine-grained control)​

  • tls12_recv_client_hello, tls12_send_server_hello, tls12_send_certificate, tls12_send_server_key_exchange, tls12_send_server_hello_done
  • tls12_recv_client_key_exchange, tls12_recv_change_cipher_spec_client, tls12_recv_finished_client
  • tls12_send_change_cipher_spec_server, tls12_send_finished_server

Record encryption/decryption is available via noxtls_tls12_encrypt_record and noxtls_tls12_decrypt_record from the common TLS API.