Redfish Certificate Service

This document describes the Redfish Certificate Service in tlBMC. It details the routes, actions, and resources used for managing certificates (such as trust bundles, server certificates, and owner verification certificates) for secure communication.

The Certificate Service implementation is split across two files:

  • certificate_service.cc: Implements the main CertificateService endpoint and its actions (GenerateCSR, ReplaceCertificate).
  • manager_certificates.cc: Implements the certificate collection and individual certificate resource endpoints.

Enablement

These routes are active if the TrustBundleInstallModule is enabled in the Central Configuration.

The configuration flag trust_bundle_install_module.enabled is checked in all_routes.cc:

  if (GetTlbmcConfig().trust_bundle_install_module().enabled()) {
    certificate_service::RegisterRoutes(app, root_path);
    manager_certificates::RegisterRoutes(app);
  }

Main Service Endpoint

  • URL: /redfish/v1/CertificateService
  • Handler: HandleCertificateService
  • Method: GET
  • Description: Provides the main entry point for the Certificate Service, linking to the available actions:
    • #CertificateService.GenerateCSR
    • #CertificateService.ReplaceCertificate

Redfish Output Example

The following JSON snippet demonstrates a sample Redfish representation of the CertificateService resource as exposed over HTTP GET requests:

{
  "@odata.id": "/redfish/v1/CertificateService",
  "@odata.type": "#CertificateService.v1_1_0.CertificateService",
  "Actions": {
    "#CertificateService.GenerateCSR": {
      "@Redfish.ActionInfo": "/redfish/v1/CertificateService/GenerateCSRActionInfo",
      "target": "/redfish/v1/CertificateService/Actions/CertificateService.GenerateCSR"
    },
    "#CertificateService.ReplaceCertificate": {
      "@Redfish.ActionInfo": "/redfish/v1/CertificateService/ReplaceCertificateActionInfo",
      "target": "/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate"
    }
  },
  "Description": "Actions related to certificates.",
  "Id": "CertificateService",
  "Name": "Certificate Service"
}

Actions

Generate CSR

  • Action URL: /redfish/v1/CertificateService/Actions/CertificateService.GenerateCSR
  • Handler: HandleGenerateCsr
  • Method: POST
  • Action Info URL: /redfish/v1/CertificateService/GenerateCSRActionInfo (GET) - HandleGenerateCsrActionInfo
  • Description: Generates a Certificate Signing Request (CSR) based on the parameters provided in the POST body.
  • Parameters:
    • AlternativeNames (Array of Strings, Optional): Subject Alternative Names for the certificate.
    • City (String, Required): The city or locality of the organization.
    • CommonName (String, Required): The fully qualified domain name (FQDN) or IP address.
    • Country (String, Required): The two-letter country code.
    • Organization (String, Required): The legal name of the organization.
    • OrganizationalUnit (String, Required): The division or department.
    • State (String, Required): The state or province.
    • CertificateCollection (Object, Required): Must contain a /CertificateCollection/@odata.id pointing to the main certificates path /redfish/v1/Managers/bmc/Certificates.
  • Response:
    • CSRString (String): The PEM-encoded CSR string.
    • CertificateCollection (Object): Link back to the collection /redfish/v1/Managers/bmc/Certificates.

Replace Certificate

  • Action URL: /redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate
  • Handler: HandleReplaceCertificate
  • Method: POST
  • Action Info URL: /redfish/v1/CertificateService/ReplaceCertificateActionInfo (GET) - HandleReplaceCertificateActionInfo
  • Description: Replaces an existing certificate resource. The target certificate is identified by the CertificateUri parameter.
  • Parameters:
    • CertificateString (String, Required): The PEM-encoded certificate content.
    • CertificateType (String, Required): Must be "PEM".
    • CertificateUri (Object, Required): Must contain a /CertificateUri/@odata.id pointing to one of the supported certificate URIs listed below.
    • OEM Google Parameters:
      • DetachedSignature (String, Optional): A PEM-encoded PKCS#7 detached signature to authenticate the CertificateString. Required for TrustBundle and TrustedUserCAKeys.
      • BmcSshTrustedUserCAKeys (String, Optional): Trusted user CA keys for SSH access. Replaces the current SSH keys. (Used when replacing OwnerVerificationCertificate).
      • OwnerVerificationCertificateConfiguration (Object, Optional): Configuration settings to apply when the Owner Verification Certificate (OVC) is installed. Used when replacing OwnerVerificationCertificate.
        • SshEnabled (Boolean, default true): Enables/disables SSH access.
        • FirmwareUpdateEnabled (Boolean, default true): Enables/disables firmware updates.
        • SerialConsoleAccessLevel (String, default “Full”): Access level for the serial console. Must be one of: "Full", "ReadOnly", "Disable".
        • BundleDevVerificationEnabled (Boolean, default true): Enables/disables verification with a developer key for firmware bundles.
      • SyslogCertificateConfiguration (Object, Optional): Configuration for the syslog target collector when replacing SyslogCertificate.
        • TargetIp (String, Required if config is provided)
        • TargetPort (Integer, Required if config is provided)

Supported Target URIs and Handlers

  • Trust Bundle
    • URI: /redfish/v1/Managers/bmc/Certificates/TrustBundle
    • Handler: HandleInstallTrustBundle
    • Effect: Installs a new trust bundle in the store. Requires DetachedSignature. Triggers a Redfish service restart asynchronously to apply the changes.
  • Server Certificate
    • URI: /redfish/v1/Managers/bmc/Certificates/ServerCert
    • Handler: HandleInstallServerCert
    • Effect: Installs a new server certificate in the store. Triggers a Redfish service restart asynchronously.
  • OS Verification Certificate
    • URI: /redfish/v1/Managers/bmc/Certificates/OsVerificationCertificate
    • Handler: HandleInstallOsCert
    • Effect: Installs a new OS verification certificate. The certificate is validated, public key extracted, and written to /var/google/os-keys/.
  • Owner Verification Certificate (OVC)
    • URI: /redfish/v1/Managers/bmc/Certificates/OwnerVerificationCertificate
    • Handler: HandleInstallOwnerVerificationCert
    • Effect: Stages a new OVC at /var/google/owner-verification/staged/cert.pem. It also stages SSH CA keys (from BmcSshTrustedUserCAKeys parameter) at /var/google/ssh/trusted_ca_pubkeys, and OVC configuration (OwnerVerificationCertificateConfiguration parameter) at /var/google/owner-verification/staged/config.textproto.
  • Trusted User CA Keys
    • URI: /redfish/v1/Managers/bmc/Certificates/TrustedUserCAKeys
    • Handler: HandleTrustedUserCAKeys
    • Effect: Installs trusted user CA keys for SSH access. Requires DetachedSignature.
  • Syslog Certificate
    • URI: /redfish/v1/Managers/bmc/Certificates/SyslogCertificate
    • Handler: HandleInstallSyslogCert
    • Effect: Installs the syslog certificate and configures the target collector IP/port (from SyslogCertificateConfiguration parameter).

Certificate Resources and Collections

These resources are registered in manager_certificates.cc and support GET requests to retrieve certificate details.

Certificate Collection

  • URL: /redfish/v1/Managers/bmc/Certificates
  • Handler: HandleGetCertificateCollection
  • Method: GET
  • Description: Returns a collection of all currently installed certificates. Only certificates that are present in the store are included in the Members array.

Owner Verification Certificate

  • URL: /redfish/v1/Managers/bmc/Certificates/OwnerVerificationCertificate
  • Handler: HandleGetOwnerVerificationCertificate
  • Method: GET
  • Description: Retrieves the Owner Verification Certificate.
  • Google OEM Extensions:
    • /Oem/Google/BmcSshTrustedUserCAKeys: Signature of the trusted user CA keys.
    • /Oem/Google/OwnerVerificationCertConfiguration: Current OVC configuration:
      • SshEnabled (Boolean)
      • SerialConsoleAccessLevel (String: “Full”, “ReadOnly”, or “Disable”)
      • FirmwareUpdateEnabled (Boolean)

Trust Bundle

  • URL: /redfish/v1/Managers/bmc/Certificates/TrustBundle
  • Handler: HandleGetTrustBundle
  • Method: GET
  • Description: Retrieves the Trust Bundle.
  • Google OEM Extensions:
    • /Oem/Google/DetatchedSignature: Detached signature of the trust bundle.

Server Certificate

  • URL: /redfish/v1/Managers/bmc/Certificates/ServerCert
  • Handler: HandleGetServerCert
  • Method: GET
  • Description: Retrieves the Server Certificate.

OS Verification Certificate

  • URL: /redfish/v1/Managers/bmc/Certificates/OsVerificationCertificate
  • Handler: HandleGetOsVerificationCertificate
  • Method: GET
  • Description: Retrieves the OS Verification Certificate.

Trusted User CA Keys

  • URL: /redfish/v1/Managers/bmc/Certificates/TrustedUserCAKeys
  • Handler: HandleGetTrustedUserCAKeys
  • Method: GET
  • Description: Retrieves the BMC Serial Console Trusted User CA Keys.
  • Google OEM Extensions:
    • /Oem/Google/DetatchedSignature: Detached signature of the trusted user CA keys.

Syslog Certificate

  • URL: /redfish/v1/Managers/bmc/Certificates/SyslogCertificate
  • Handler: HandleGetSyslogCertificate
  • Method: GET
  • Description: Retrieves the Syslog Certificate and its destination settings.
  • Google OEM Extensions:
    • /Oem/Google/SyslogCertificateConfiguration: Current target configuration:
      • Address (String)
      • Port (Integer)

Protobuf Configuration

Code References