Return codes (noxtls_return_t)

Most NoxTLS API functions return noxtls_return_t, an unsigned 32-bit status type. Always check the return value: use NOXTLS_RETURN_SUCCESS for success, or handle specific error codes for diagnostics.

The type and constants are defined in noxtls_common.h.

Type

noxtls_return_t — typedef uint32_t noxtls_return_t; with each code defined as an unsigned constant, e.g. #define NOXTLS_RETURN_SUCCESS ((noxtls_return_t)0U). Use it as the return type of API functions that report status.

Changed in 0.3.0

Before 0.3.0, noxtls_return_t was a C enum. It became a uint32_t typedef so that the return constants have the same essential type as the API return type (MISRA C:2025 Rule 10.3). The numeric values are unchanged. Comparisons and switch statements on the constants work as before. Remove any enum forward declarations of the type. See MISRA C:2025.

Values

Constant	Value	Description
NOXTLS_RETURN_SUCCESS	0	Operation completed successfully.
NOXTLS_RETURN_FAILED	1	General failure (e.g. verification failed, crypto operation failed).
NOXTLS_RETURN_NULL	2	A required pointer argument was NULL.
NOXTLS_RETURN_INVALID_PARAM	3	An argument was invalid (e.g. out of range, inconsistent).
NOXTLS_RETURN_INVALID_BLOCK_SIZE	4	Block or buffer size invalid for the operation.
NOXTLS_RETURN_INVALID_KEY_SIZE	5	Key size invalid for the algorithm or mode.
NOXTLS_RETURN_INVALID_MODE	6	Cipher mode invalid or not supported for this operation.
NOXTLS_RETURN_INVALID_ALGORITHM	7	Requested algorithm not supported or invalid in this context.
NOXTLS_RETURN_BAD_DATA	8	Input data was malformed or invalid (e.g. auth tag mismatch).
NOXTLS_RETURN_TIMEOUT	9	Operation timed out.
NOXTLS_RETURN_NOT_SUPPORTED	10	Requested feature or option is not supported.
NOXTLS_RETURN_NOT_INITIALIZED	11	Context or module was not initialized.
NOXTLS_RETURN_NOT_ENOUGH_MEMORY	12	Memory allocation failed.
NOXTLS_RETURN_NOT_ENOUGH_ENTROPY	13	Insufficient entropy for random or key-generation.
NOXTLS_RETURN_CERT_PARSE_FAILED	14	Certificate parsing failed (malformed DER or invalid structure).
NOXTLS_RETURN_CERT_VERIFY_FAILED	15	Certificate verification failed (generic).
NOXTLS_RETURN_TLS_ERROR	16	TLS/protocol error (handshake, record, or unexpected message).
NOXTLS_RETURN_CERT_VERIFY_SIGNATURE_FAILED	17	Certificate signature verification failed (invalid or issuer key missing).
NOXTLS_RETURN_CERT_VERIFY_HOSTNAME_MISMATCH	18	Hostname does not match certificate SAN or subject CN.
NOXTLS_RETURN_CERT_EXPIRED	19	Certificate has expired (current time > notAfter).
NOXTLS_RETURN_CERT_NOT_YET_VALID	20	Certificate not yet valid (current time < notBefore).
NOXTLS_RETURN_CERT_VERIFY_CHAIN_FAILED	21	Certificate chain verification failed (signature or validity of a link).
NOXTLS_RETURN_CERT_REVOKED	22	Certificate serial appears on a supplied CRL (revoked).
NOXTLS_RETURN_CRL_PARSE_FAILED	23	CRL parsing failed (malformed DER/PEM or unsupported structure).
NOXTLS_RETURN_CRL_VERIFY_FAILED	24	CRL signature verification failed against the issuer certificate.
NOXTLS_RETURN_CRL_EXPIRED	25	CRL is outside its validity window (e.g. current time past nextUpdate when nextUpdate is present).
NOXTLS_RETURN_TLS_WEAK_DHE_PARAMS	26	Weak or unsupported DHE parameters in ServerKeyExchange.
NOXTLS_RETURN_RECORD_OVERFLOW	27	TLS record plaintext exceeds the negotiated or protocol maximum.
NOXTLS_RETURN_CERT_REQUIRED	28	A client certificate was required but the peer did not present one.
NOXTLS_RETURN_TLS_ALERT_DECODE_ERROR	29	Malformed handshake message (decode_error).
NOXTLS_RETURN_TLS_ALERT_ILLEGAL_PARAMETER	30	Invalid handshake field (illegal_parameter).
NOXTLS_RETURN_TLS_RECORD_AUTH_FAILED	31	AEAD record open failed (bad_record_mac).
NOXTLS_RETURN_TLS_FINISHED_VERIFY_FAILED	32	Finished verify_data mismatch.
NOXTLS_RETURN_NEGOTIATED_TLS12	33	Downgrade path: continue as TLS 1.2.
NOXTLS_RETURN_WANT_READ	34	Nonblocking I/O: more input bytes are needed; call again when readable.
NOXTLS_RETURN_WANT_WRITE	35	Nonblocking I/O: encrypted output is pending; flush when writable.
NOXTLS_RETURN_ECDH_PRIVATE_KEY_INVALID	36	ECDH private-key context invalid.
NOXTLS_RETURN_ECDH_OUTPUT_TOO_SMALL	37	ECDH output buffer too small.
NOXTLS_RETURN_ECDH_PEER_PUBLIC_KEY_INVALID	38	ECDH peer public key invalid.
NOXTLS_RETURN_ECDH_SCALAR_MULTIPLY_FAILED	39	ECDH scalar multiplication failed.
NOXTLS_RETURN_ECDH_SHARED_POINT_INFINITY	40	ECDH result was the point at infinity.

Usage

• For success, check for ret == NOXTLS_RETURN_SUCCESS (or !ret when 0 is the only success value).
• For verification-style functions (e.g. hash verify), NOXTLS_RETURN_SUCCESS means the check passed; NOXTLS_RETURN_FAILED means it did not.
• Use specific codes (e.g. NOXTLS_RETURN_NULL, NOXTLS_RETURN_BAD_DATA) to narrow down errors in logs or handling.
• For TLS and X.509 APIs, use the specific certificate return codes above to distinguish parse, signature, hostname, time, chain, revocation, and CRL failures. Use NOXTLS_RETURN_TLS_ERROR for protocol-level TLS/handshake errors.
• For detailed certificate failure info (notBefore, notAfter, subject DN, expected hostname, chain index), call noxtls_cert_verify_failure_get after any X.509 or TLS API that returns a CERT_* code.

See also

• Common — Memory and debug utilities that also use noxtls_return_t.