Page History

Overview

This document provides comprehensive guidance for integrating rdk-cert-config with the xconf-client and xconf-server ecosystem. The rdk-cert-config library provides intelligent certificate management and selection capabilities for RDK devices, enabling:

• Automatic Certificate Fallback: When a certificate fails, the system automatically tries the next available certificate
• State Tracking: Failed certificates are remembered and won't be retried until updated
• Multi-Certificate Support: Supports PEM, P12, and PKCS#11 certificate formats
• Hardware Security Module Support: Can integrate with Secure Elements (SE) and Trusted Execution Environments (TEE)
• OpenSSL Provider Integration: Supports hardware-optimized certificate operations

Repo - https://github.com/rdkcentral/rdk-cert-config

What is RDK-CERT-CONFIG

 Architecture

rdk-cert-config repo provides two main libraries:

1. CertSelector (Recommended)

• Purpose: Intelligent certificate selection with automatic failover

• Key Features:

  • Returns the best available certificate for a given connection type
  • Tracks certificate validity state
  • Automatically skips failed certificates until they're updated
  • Returns both certificate URI and password/credential
  • Supports OpenSSL engine selection for hardware acceleration

• API Methods:

rdkcertselector_h rdkcertselector_new(const char *config_path, 
                                      const char *hrotprop_path, 
                                      const char *cert_group)

rdkcertselectorStatus_t rdkcertselector_getCert(rdkcertselector_h handle,
                                                char **cert_uri,
                                                char **cert_pass)

rdkcertselectorRetry_t rdkcertselector_setCurlStatus(rdkcertselector_h handle,
                                                     unsigned int curl_status,
                                                     const char *endpoint)

void rdkcertselector_free(rdkcertselector_h *handle)

2. CertLocator (Alternative)

• Purpose: Simple certificate lookup table
• Key Features:
  • Direct mapping of cert reference → URI and password
  • Simpler than CertSelector for fixed certificate scenarios
  • No state tracking or automatic failover

Status

Enumeration

CertSelector Status Codes:

• certselectorOk (0) - Success
• certselectorGeneralFailure (1) - General failure
• certselectorBadPointer (2) - Invalid pointer
• certselectorFileError (3) - File access error
• certselectorFileNotFound (4) - Certificate file not found
• certselectorBadArgument (5) - Invalid argument

CertSelector Retry Codes:

• NO_RETRY (100) - Certificate succeeded or connection failed for non-cert reason
• TRY_ANOTHER (101) - Certificate failed; another cert is available to try
• RETRY_ERROR (102) - Internal error

Configuration Files

 Device-Side Files

Both CertSelector and CertLocator rely on a configuration file, certsel.conf, which contains a prioritized list of certificates along with their file paths and passcode sources. Additionally, CertSelector uses another configuration file, hrot.properties, to determine the name of the OpenSSL provider when available.

These files must be deployed on each RDK device:

File 1: /etc/ssl/certs/certsel.conf

Certificate manifest defining available certificates and their priority order.

Format:

<usage_group>,<cert_reference>,<cert_type>,<cert_uri>,<credential_reference>

Example:

# Primary certificate (TEE, highest priority)
CURL_XCONF,XCONF_TEE_P12,P12,pkcs11:model=PKCS#15;token=test,xconf_tee_cred

# Secondary certificate (Secure Element)
CURL_XCONF,XCONF_SE_P12,P12,[file:///opt/certs/xconf_se.pk12],xconf_se_cred

# Tertiary certificate (Filesystem)
CURL_XCONF,XCONF_MAIN_P12,P12,[file:///etc/ssl/certs/xconf_main.pk12],xconf_main_cred

# Fallback certificate (firmware-embedded, static)
CURL_XCONF,XCONF_FALLBACK_P12,P12,[file:///etc/ssl/certs/xconf_fallback.pk12],xconf_fb_cred

Field Descriptions:

File 2: /etc/ssl/certs/hrot.properties

Hardware Root of Trust properties for OpenSSL engine selection. 

• <engine name> is the name provided by the SE or TEE provider

Format:

hrotengine=<engine_name>

Example:

# Using Hardware Secure Element
hrotengine=rdktee

# Using Software-based OpenSSL
hrotengine=

# Using SE provider
hrotengine=se_pkcs