Skip to main content
Version: 0.1.23

Certificates

X.509 and certificate handling.

Types​

x509_certificate_t​

Parsed X.509 certificate object.

x509_certificate_chain_t​

Certificate chain container.

x509_private_key_t​

Parsed private key container.

API​

noxtls_parse_der​

uint32_t noxtls_parse_der(uint8_t * data, uint32_t len);

Parse ASN.1 DER Data

Parameters:

  • data — is a pointer to a pointer to the data to convert
  • length — is a pointer to the length
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

noxtls_parse_tag​

uint32_t noxtls_parse_tag(uint8_t ** data, uint8_t * end);

Parse ASN.1 Tag

Parameters:

  • data — is a pointer to a pointer to the data to convert
  • length — is a pointer to the length
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

asn1_decode_integer​

void asn1_decode_integer(uint8_t ** data, uint32_t len);

Decodes object identifier

Parameters:

  • data — is a pointer to the data to convert
  • length — is the length of the PEM data
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

asn1_decode_bitstring​

void asn1_decode_bitstring(uint8_t ** data, uint32_t len);

Decodes ASN.1 Bit String

Parameters:

  • data — is a pointer to a pointer of the data to convert
  • len — is the length of the data

asn1_decode_obj_ident​

void asn1_decode_obj_ident(uint8_t ** data, uint32_t len);

Decodes object identifier

Parameters:

  • data — is a pointer to the data to convert
  • length — is the length of the PEM data
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

asn1_find_oid​

void asn1_find_oid(char * oid);

Finds the OID description for an identifier

Parameters:

  • oid — is the OID string

asn1_decode_print_string​

void asn1_decode_print_string(uint8_t ** data, uint32_t len);

Decodes object identifier

Parameters:

  • data — is a pointer to the data to convert
  • length — is the length of the PEM data
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

noxtls_certificate_der_to_pem​

noxtls_return_t noxtls_certificate_der_to_pem(uint8_t * data, uint32_t length, uint8_t * output, uint32_t * out_len);

Converts DER certificate to PEM

Parameters:

  • data — is a pointer to the DER data to convert
  • length — is the length of the DER data
  • output — is a pointer to a buffer to place the PEM data
  • out_len — is the length of data placed in output

noxtls_csr_der_to_pem​

noxtls_return_t noxtls_csr_der_to_pem(uint8_t *data, uint32_t length, uint8_t *output, uint32_t *out_len);

Converts DER Certificate Signing Request (PKCS#10) to PEM.

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_certificate_pem_to_der​

noxtls_return_t noxtls_certificate_pem_to_der(uint8_t * data, uint32_t length, uint8_t * output, uint32_t * out_len);

Converts PEM certificate to DER

Parameters:

  • data — is a pointer to the data to convert
  • length — is the length of the PEM data
  • output — is a pointer to a buffer to place the DER data
  • out_len — is the length of data placed in output

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_matches_hostname​

noxtls_return_t noxtls_x509_certificate_matches_hostname(const x509_certificate_t *cert, const char *hostname, uint32_t hostname_len);

Check whether the certificate is valid for the given hostname (RFC 6125 style). Prefer SAN dNSName; if none, fall back to subject CN. Comparison is case-insensitive for DNS.

Parameters:

  • cert — x509_certificate_t (must have been parsed so subject_dn and optionally san_dns_ are set)
  • hostname — Expected hostname (need not be null-terminated)
  • hostname_len — Length of hostname

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS if hostname matches a SAN dNSName or subject CN; NOXTLS_RETURN_CERT_VERIFY_HOSTNAME_MISMATCH otherwise; NOXTLS_RETURN_NULL if cert or hostname is NULL.

noxtls_x509_certificate_init​

noxtls_return_t noxtls_x509_certificate_init(x509_certificate_t *cert);

Initialize X.509 certificate structure

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_free​

noxtls_return_t noxtls_x509_certificate_free(x509_certificate_t *cert);

Free X.509 certificate structure

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_parse_der​

noxtls_return_t noxtls_x509_certificate_parse_der(x509_certificate_t *cert, const uint8_t *data, uint32_t len);

Parse X.509 certificate from DER format

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_parse_pem​

noxtls_return_t noxtls_x509_certificate_parse_pem(x509_certificate_t *cert, const uint8_t *data, uint32_t len);

Parse X.509 certificate from PEM format

noxtls_x509_certificate_load_file​

noxtls_return_t noxtls_x509_certificate_load_file(x509_certificate_t *cert, const char *filename);

Load X.509 certificate from file

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_verify_signature​

noxtls_return_t noxtls_x509_certificate_verify_signature(x509_certificate_t *cert, const x509_certificate_t *issuer);

Verify certificate signature

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_check_validity​

noxtls_return_t noxtls_x509_certificate_check_validity(const x509_certificate_t *cert);

Check certificate validity (not expired). cert is x509_certificate_t.

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_get_public_key​

noxtls_return_t noxtls_x509_certificate_get_public_key(const x509_certificate_t *cert, void **key, uint32_t *key_type);

Get public key from certificate (noxtls_ namespace). cert is x509_certificate_t. For ECC: key is set to an allocated ecc_key_t (caller must noxtls_ecc_key_free then free). key_type: 1 = RSA, 2 = ECC.

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

x509_certificate_get_public_key​

noxtls_return_t x509_certificate_get_public_key(const x509_certificate_t *cert, void **key, uint32_t *key_type);

Get public key from certificate (legacy wrapper)

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

Raw Public Keys (RFC 7250)​

TLS 1.2 and DTLS 1.2 support Raw Public Keys (RPK) via the client_certificate_type and server_certificate_type extensions. The server can send a SubjectPublicKeyInfo (DER) in the Certificate message instead of an X.509 chain; the client receives it in server_cert and sets server_cert_is_rpk to 1. Verification is out-of-band (e.g. compare to a pinned key or use DANE). Use tls12 APIs: tls12_set_server_use_rpk() (server), tls12_set_client_accept_server_rpk() / tls12_set_client_offer_client_rpk() (client). Prefer ECDHE cipher suites with RPK.

Detailed certificate failure information​

When certificate parsing or verification fails, the library stores detailed failure information that you can retrieve to log or display the exact reason (time window, common name, expected hostname, chain index).

Return codes: Certificate APIs may return NOXTLS_RETURN_CERT_PARSE_FAILED, NOXTLS_RETURN_CERT_VERIFY_SIGNATURE_FAILED, NOXTLS_RETURN_CERT_VERIFY_HOSTNAME_MISMATCH, NOXTLS_RETURN_CERT_EXPIRED, NOXTLS_RETURN_CERT_NOT_YET_VALID, or NOXTLS_RETURN_CERT_VERIFY_CHAIN_FAILED. After any such failure, call noxtls_cert_verify_failure_get() to get a noxtls_cert_verify_failure_info_t with:

  • return_code — The same code that was returned.
  • not_before / not_after — Certificate validity times (e.g. for expired / not yet valid).
  • subject_dn — Subject distinguished name of the certificate that failed.
  • expected_hostname — The hostname that was checked (on hostname mismatch).
  • cert_index — Index in chain (0-based) when chain verification fails.
  • populated — 1 if the struct was filled by a failure; 0 otherwise.
noxtls_cert_verify_failure_info_t info;
noxtls_cert_verify_failure_get(&info);
if (info.populated) {
    /* e.g. printf("Cert failure: %d, subject=%s, not_after=%s\n", info.return_code, info.subject_dn, info.not_after); */
}

Clear: Call noxtls_cert_verify_failure_clear() before a new verification if you want to avoid reusing an older failure’s details. Storage is process-wide (not thread-safe).

noxtls_x509_get_attr_name_from_oid​

/* Helper function to get attribute name from OID */ static const char* noxtls_x509_get_attr_name_from_oid(const uint8_t *oid, uint32_t oid_len);

Parse Distinguished Name

noxtls_x509_parse_time​

noxtls_return_t noxtls_x509_parse_time(const uint8_t *time_data, uint32_t time_len, char *output, uint32_t output_size);

Parse ASN.1 time

noxtls_x509_certificate_chain_init​

noxtls_return_t noxtls_x509_certificate_chain_init(x509_certificate_chain_t *chain);

Initialize certificate chain

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_chain_free​

noxtls_return_t noxtls_x509_certificate_chain_free(x509_certificate_chain_t *chain);

Free certificate chain

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_certificate_chain_add​

noxtls_return_t noxtls_x509_certificate_chain_add(x509_certificate_chain_t *chain, const x509_certificate_t *cert);

Add certificate to chain. chain is x509_certificate_chain_t; cert is x509_certificate_t.

noxtls_x509_certificate_chain_verify​

noxtls_return_t noxtls_x509_certificate_chain_verify(x509_certificate_chain_t *chain);

Verify certificate chain

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_private_key_init​

noxtls_return_t noxtls_x509_private_key_init(x509_private_key_t *key);

Initialize X.509 private key structure

noxtls_x509_private_key_free​

noxtls_return_t noxtls_x509_private_key_free(x509_private_key_t *key);

Free X.509 private key structure

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_private_key_parse_der​

noxtls_return_t noxtls_x509_private_key_parse_der(x509_private_key_t *key, const uint8_t *data, uint32_t len);

Parse X.509 private key from DER format

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_private_key_parse_pem​

noxtls_return_t noxtls_x509_private_key_parse_pem(x509_private_key_t *key, const uint8_t *data, uint32_t len);

Parse X.509 private key from PEM format

noxtls_x509_private_key_load_file​

noxtls_return_t noxtls_x509_private_key_load_file(x509_private_key_t *key, const char *filename);

Load X.509 private key from file

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_private_key_to_rsa_key​

noxtls_return_t noxtls_x509_private_key_to_rsa_key(const x509_private_key_t *key, void *rsa_key);

Convert X.509 private key to RSA key structure

noxtls_x509_private_key_to_ecc_key​

noxtls_return_t noxtls_x509_private_key_to_ecc_key(const x509_private_key_t *key, ecc_key_t *ecc_key);

Convert X.509 private key to ecc_key_t (noxtls_ namespace). key is x509_private_key_t. Caller provides ecc_key; it is filled and must be freed with noxtls_ecc_key_free.

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_private_key_sign_data​

noxtls_return_t noxtls_x509_private_key_sign_data(const uint8_t *key, uint32_t key_len, const uint8_t *data, uint32_t data_len, noxtls_hash_algos_t hash_algo, uint8_t *out_der, uint32_t out_max, uint32_t *out_len);

High-level sign data with X.509 private key; output DER signature.

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

x509_private_key_to_ecc_key​

noxtls_return_t x509_private_key_to_ecc_key(const x509_private_key_t *key, void *ecc_key);

Convert X.509 private key to ECC key structure (legacy wrapper)

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.

noxtls_x509_debug_print_oid​

void noxtls_x509_debug_print_oid(const char *label, const uint8_t *oid, uint32_t oid_len);

Print OID in readable format

noxtls_x509_debug_print_hex​

void noxtls_x509_debug_print_hex(const char *label, const uint8_t *data, uint32_t len, uint8_t verbose);

Print hex data with formatting

noxtls_x509_certificate_debug_print​

noxtls_return_t noxtls_x509_certificate_debug_print(x509_certificate_t *cert, uint8_t verbose);

Debug print certificate information

noxtls_x509_private_key_debug_print​

noxtls_return_t noxtls_x509_private_key_debug_print(x509_private_key_t *key, uint8_t verbose);

Debug print private key information

Returns: noxtls_return_t: NOXTLS_RETURN_SUCCESS on success.