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 (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 Enumerations

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

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.

Format:

hrotengine=<engine_name>

Example:

# Using Hardware Secure Element
hrotengine=rdktee

# Using Software-based OpenSSL
hrotengine=

# Using SE provider
hrotengine=se_pkcs