Certificate Handler API

API Component: Certificate Handler API_COMP_CERT_HANDLER
status: implemented
header_file: main/components/cert_handler/cert_handler.h
links outgoing: REQ_SYS_SEC_1

Brief Description

Certificate management for ESP32 HTTPS server. Provides access to embedded SSL certificates generated during the build process, supporting long-term IoT deployments.

Key features:

  • Embedded server and CA certificates

  • 25-year validity for IoT deployments

  • Build-time certificate generation

Architecture:

  • Certificates generated at build time and embedded in firmware

  • Accessed via type-safe API for HTTPS server initialization

Lifecycle Functions

API Function: cert_handler_init API_FUNC_CERT_HANDLER_INIT
status: implemented
api_signature: esp_err_t cert_handler_init(void)
returns: ESP_OK if all certificates are available, error codes otherwise
parameters: None
component: API_COMP_CERT_HANDLER
links outgoing: REQ_SYS_SEC_1

Initialize certificate management. Verifies that all required certificates are available and properly embedded in the firmware. Should be called during system initialization before starting the HTTPS server.

Signature:

esp_err_t cert_handler_init(void);

Parameters:

  • None

Returns:

  • ESP_OK - All certificates are available

  • ESP_ERR_NOT_FOUND - Any certificates are missing

Note

Call before HTTPS server startup.

Certificate Access Functions

API Function: cert_handler_get_server_cert API_FUNC_CERT_HANDLER_GET_SERVER_CERT
status: implemented
api_signature: esp_err_t cert_handler_get_server_cert(const char** cert_data, size_t* cert_len)
returns: ESP_OK on success, error codes otherwise
parameters: cert_data, cert_len
component: API_COMP_CERT_HANDLER
links outgoing: REQ_SYS_SEC_1

Get embedded server certificate data (PEM format) generated during build.

Signature:

esp_err_t cert_handler_get_server_cert(const char** cert_data, size_t* cert_len);

Parameters:

  • cert_data - Pointer to certificate data (null-terminated)

  • cert_len - Length of certificate data including null terminator

Returns:

  • ESP_OK - Success

  • ESP_ERR_INVALID_ARG - Parameters are NULL
API Function: cert_handler_get_server_key API_FUNC_CERT_HANDLER_GET_SERVER_KEY
status: implemented
api_signature: esp_err_t cert_handler_get_server_key(const char** key_data, size_t* key_len)
returns: ESP_OK on success, error codes otherwise
parameters: key_data, key_len
component: API_COMP_CERT_HANDLER
links outgoing: REQ_SYS_SEC_1

Get embedded server private key data (PEM format) generated during build.

Signature:

esp_err_t cert_handler_get_server_key(const char** key_data, size_t* key_len);

Parameters:

  • key_data - Pointer to private key data (null-terminated)

  • key_len - Length of private key data including null terminator

Returns:

  • ESP_OK - Success

  • ESP_ERR_INVALID_ARG - Parameters are NULL
API Function: cert_handler_get_ca_cert API_FUNC_CERT_HANDLER_GET_CA_CERT
status: implemented
api_signature: esp_err_t cert_handler_get_ca_cert(const char** cert_data, size_t* cert_len)
returns: ESP_OK on success, error codes otherwise
parameters: cert_data, cert_len
component: API_COMP_CERT_HANDLER
links outgoing: REQ_SYS_SEC_1

Get embedded CA certificate data (PEM format) generated during build.

Signature:

esp_err_t cert_handler_get_ca_cert(const char** cert_data, size_t* cert_len);

Parameters:

  • cert_data - Pointer to CA certificate data (null-terminated)

  • cert_len - Length of CA certificate data including null terminator

Returns:

  • ESP_OK - Success

  • ESP_ERR_INVALID_ARG - Parameters are NULL
API Function: cert_handler_get_info API_FUNC_CERT_HANDLER_GET_INFO
status: implemented
api_signature: esp_err_t cert_handler_get_info(char* info_buffer, size_t buffer_size)
returns: ESP_OK on success, error codes otherwise
parameters: info_buffer, buffer_size
component: API_COMP_CERT_HANDLER
links outgoing: REQ_SYS_SEC_1

Get certificate information for logging. Provides certificate metadata for diagnostics. Does not expose sensitive private key information.

Signature:

esp_err_t cert_handler_get_info(char* info_buffer, size_t buffer_size);

Parameters:

  • info_buffer - Buffer to store certificate information

  • buffer_size - Size of the information buffer

Returns:

  • ESP_OK - Success

  • ESP_ERR_INVALID_SIZE - Buffer too small