RDK Certificate Configuration Integration Guide

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

Purpose: Intelligent certificate selection with automatic failover. 

• Key Features:

  • Returns the best available certificate for a given connection type. This includes logic to choose the best available certificate from a predefined set, called a certificate group.
  • Tracks certificate validity state. It maintains state to avoid returning the path to a certificate that has been deemed invalid (e.g., expired, untrusted, or corrupted)
  • Automatically skips failed certificates until they're updated. Once a certificate is marked as BAD, it remains so until the file changes. When a change is detected, the certificate becomes eligible for use on the next call, allowing a bad certificate to be replaced and used immediately once corrected.
  • 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 

• Purpose: Simple certificate lookup table. This makes it easier to find a specific certificate, even if it's stored in different places on different devices.
• 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. is the name 

• <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

BPI implementation 

 xconf-client ( FirmwareDownload )

BPI 2025Q4 build uses getMtlsCerts() directly because its xconf-client doesn't have LIBRDKCERTSEL_BUILD defined. It gets a single static cert from the shell script, no retry mechanism.

WITH rdk-cert-config (LIBRDKCERTSEL_BUILD):

#ifdef LIBRDKCERTSEL_BUILD
    do {
        xcGetCertStatus = rdkcertselector_getCert(handleCertSelector, &pCertURI, &pCertPC);
        // Set cert on curl handle
        curl_easy_perform(easy);
        
        // Report result back to selector
        rdkcertselector_setCurlStatus(handleCertSelector, curl_code, url);
    } while(rdkcertselector_setCurlStatus(...) == TRY_ANOTHER);  // <- Retry on failure

WITHOUT rdk-cert-config (no LIBRDKCERTSEL_BUILD):

#else
    // Fallback - simple one-shot attempt
    if(T2ERROR_SUCCESS == getMtlsCerts(&pCertFile, &pCertPC)) {
        curl_easy_perform(easy);
    }
    // No retry logic - fails if cert unavailable
#endif

 Key Difference:

• rdkcertselector_getCert() = Advanced failover (tries CURL_MTLS → CURL_RED → next cert if connection fails)
• getMtlsCerts() = Simple fallback (load cert once, use it, if it fails, done—no retry)

Server Side (xconfwebconfig/xconfadmin)

The xconf-server currently does NOT validate incoming client certificates, which requires below key points.

• Require client certificates for mTLS endpoints
• TLS ClientAuth middleware to validate device certificates
• Device CA certificate bundle
• Pin specific device certificates

Telemetry ( xconf-client for T2 profile )

• Enabling LIBRDKCERTSEL_BUILD will allow xconf-client to use rdk-cert-config for intelligent certificate management
• Telemetry already has the mTLS infrastructure working (handles PKCS#11, certificate retry logic, error reporting)
• SE/TEE paths can be configured in the certificate manifest

Gap Analysis

• Set up SE/TEE certificate paths on BPI4
• Enable required flags to integrate rdk-cert-config APIs
• Prepare /etc/ssl/certs/certsel.conf and  /etc/ssl/certs/hrot.properties for BPI4 platform

If MTLS is enabled in client side and not in server side then,

• Client sends cert ✅
• Server receives but ignores it ❌
• Any device with any certificate gets accepted
• Not secure - this is incomplete

For TRUE mTLS :

1. Server-side validation in xconfwebconfig (mandatory):

   • Load device CA certificate bundle
   • Add TLS middleware to validate incoming client certificates
   • Check certificate DN, fingerprint, or whitelist
   • Only accept requests from authorized devices

2. Client-side with LIBRDKCERTSEL_BUILD (already works in telemetry):

   • Uses SE/TEE for private key storage
   • Sends device certificate in TLS handshake
3. This will break standalone xconf-client ( FirmwareDownload ) or any other client app without MTLS enabled connecting server

                Server Enabled with MTLS ( needs client Certs )
                                   ┌───────┴───────┐
                                   ↓                                        ↓
                              Telemetry               Standalone xconf-client
                       (with LIBRDKCERTSEL)       (without LIBRDKCERTSEL)
                                  ↓                                           ↓
                       ✅ Can send cert                 ❌ WILL FAIL - has no cert to send
                              Connects OK                         Connection Denied