tlbmc/g3doc/components/credentials.md - gbmcweb - Git at Google

 <!--*
 # Document freshness: For more information, see go/fresh-source.
 freshness: { owner: 'tlbmc-dev' reviewed: '2026-06-05' }
 *-->

 # Credential Management

 ## Purpose & Overview

 The `CredentialManager` component is responsible for managing cryptographic
 identities, credentials, and secure communication anchors within tlBMC. It acts
 as the central authority for loading, generating, installing, and verifying
 secure artifacts across the BMC lifecycle.

 Specifically, `CredentialManager` handles:

 *   **Cryptographic Identities & CSRs**: Generating RSA private keys and
     Certificate Signing Requests (`GenerateCsr`).
 *   **Server Certificates (`server_cert`)**: Installing staged server
     certificates for HTTPS/Redfish endpoints (`InstallServerCert`).
 *   **Dynamic Client CA Trust Bundles (`trust_bundle`)**: Managing dynamic
     client CA trust bundles used for mTLS client authentication
     (`InstallTrustBundle`).
 *   **SSH Trusted User CA Keys**: Parsing and managing signatures and keys for
     secure SSH access (`bmc_ssh_trusted_user_ca_keys`).
 *   **Syslog Root Certificates & Target Configuration**: Managing secure root
     certificates and remote target logging configurations (`InstallSyslogCert`).
 *   **OS Verification Keys**: Verifying and storing OS signing certificates
     (`InstallOsVerificationCertificate`).

 ## Root of Trust

 The **Owner Verification Certificate** (`OwnerVerificationCert`) acts as the
 primary cryptographic root of trust (anchor) for the BMC. Loaded from the
 configured file path (`owner_verification_cert_path`) upon initialization, it
 provides the cryptographic anchor required to verify incoming credentials, trust
 bundles, and serial console keys.

 `CredentialManager` uses OpenSSL CLI wrappers via `ShellExecutor` to validate
 cryptographic signatures against this root of trust:

 *   **Trust Bundle & Serial Console Keys Verification
     (`kTrustBundleVerifyWithCaCommand`)**: Runs `openssl smime -verify -binary
     -inform PEM -in '%s' -content '%s' -CAfile '%s' -purpose any` to verify
     S/MIME detached signatures against the staged payload using the Owner
     Verification Certificate as the trusted CA.
 *   **OS Verification Certificate Verification (`kOsCertVerifyCommand`)**: Runs
     `openssl verify -CAfile '%s' -purpose any '%s'` to verify that incoming OS
     certificate chains are correctly anchored and signed by the Owner
     Verification Certificate.

 ## Key Functionality & Features

 ### 1. CSR Generation (`GenerateCsr`)

 When generating a new Certificate Signing Request:

 *   **RSA Private Key Generation**: Creates a fresh in-memory RSA private key
     (`private_key_`) using OpenSSL via `GeneratePrivateKey()`.
 *   **X509 Request Construction**: Allocates a new `X509_REQ` structure and
     populates its Subject Name entries (`C`, `ST`, `L`, `O`, `OU`, `CN`) using
     the fields specified in `CsrParams` (Country, State, City, Org, Unit, Common
     Name).
 *   **Subject Alternative Names (SANs)**: If `alternative_names` (SANs) are
     provided in `CsrParams`, formats them as `DNS:<san>` separated by commas,
     attaches the `NID_subject_alt_name` extension, and pushes it to the request
     extensions stack.
 *   **Signing & Output**: Sets the public key, signs the request using
     `EVP_sha256()`, writes to a memory BIO, and returns the resulting
     PEM-formatted CSR string. The generated private key is securely retained in
     memory for the subsequent certificate installation step.

 ### 2. Server Certificate Installation (`InstallServerCert`)

 Installing a signed server certificate completes the identity renewal cycle:

 *   **Key Matching**: Requires `GenerateCsr` to have been executed earlier so
     that `private_key_` resides in memory. Reads the incoming PEM certificate
     buffer and executes `X509_check_private_key()` to confirm that the staged
     PEM cert matches the in-memory private key.
 *   **Atomic Staging**: Writes both the PEM certificate and the serialized
     private key into a temporary staging directory (`<credential_dir>-tmp`). It
     then performs an atomic rename (`FileManager::RenamePath`) over the live
     directory (e.g., `/etc/ssl/certs/bmc`) to guarantee that key and certificate
     remain completely synchronized without race conditions.
 *   **Non-Blocking Asynchronous Service Restart**: Spawns a detached background
     thread (`RestartBmcwebInASeparateThread()`) that sleeps for a short 3-second
     delay (`kServerRestartDelaySeconds`) before executing `systemctl restart
     --no-block bmcweb`. This ensures the active Redfish/gRPC response
     successfully completes before the underlying web server reloads.

 ### 3. Trust Bundle & Syslog Installation

 *   **Trust Bundle Installation (`InstallTrustBundle`)**:
     *   **Signature Verification**: Stages incoming trust bundle PEM data and
         detached signature into secure temporary files
         (`/tmp/trust_bundle_XXXXXX`, `/tmp/signature_XXXXXX`). Verifies the
         signature using `VerifyAndStageCertificate` against the root of trust.
     *   **Rate-Limiting**: Enforces an installation retry delay
         (`kTrustBundleRetryDelaySeconds = 4` seconds) to prevent update flooding
         and race conditions during consecutive installation attempts.
     *   **Commit & Reload**: Once validated, atomically stages the bundle and
         signature to persistent storage and triggers an asynchronous,
         non-blocking restart of `bmcweb`.
 *   **Syslog Installation (`InstallSyslogCert`)**:
     *   Accepts a Syslog root certificate along with target IP and port
         configurations (`SyslogTargetConfig`).
     *   Generates a systemd environment override block (`[Service]
         Environment=PROD_SYSLOG_IP=...`) and commits it to the configured
         override path (`syslog_client_conf_override_path`).
     *   Writes the Syslog root certificate to disk, fully reverting the
         configuration override if saving fails.

 ### 4. Owner Verification Config

 `CredentialManager` parses the `OwnerVerificationCertConfiguration` textproto
 (`owner_verification_config_path`) using `proto2::TextFormat::Parser`.

 *   **Firmware Update Enablement**: Evaluates the `fw_update_enabled` property
     to determine firmware update enablement (`IsFirmwareUpdateable()`). If no
     configuration file is present, firmware updates are enabled by default.
 *   **Serial Console Policy**: Evaluates the `serial_console_access_level` enum:
     *   `ACCESS_FULL`: Allows complete interactive console access.
     *   `ACCESS_READONLY`: Writes an indicator file (`serial_console_readonly`)
         into the serial console access level directory
         (`serial_console_access_level_dir`).
     *   `ACCESS_DISABLE`: Writes a disabled indicator file
         (`serial_console_disabled`) to block serial console logins.

 ## Configuration Parameters (`CredentialManagerParams`)

 When instantiating `CredentialManager`, parameters are configured via the
 `CredentialManagerParams` struct:

 Parameter                                  | Type     | Description
 :----------------------------------------- | :------- | :----------
 `private_key_path`                         | `string` | File path for storing/reading the BMC RSA private key.
 `cert_path`                                | `string` | File path for storing/reading the BMC server certificate.
 `owner_verification_cert_path`             | `string` | File path to the Owner Verification Certificate (Root of Trust).
 `owner_verification_config_path`           | `string` | File path to the `OwnerVerificationCertConfiguration` textproto.
 `bmc_ssh_trusted_user_ca_keys_path`        | `string` | File path for SSH trusted user CA keys signature.
 `trust_bundle_path`                        | `string` | File path for the dynamic client CA trust bundle.
 `trust_bundle_signature_path`              | `string` | File path for the trust bundle detached signature.
 `os_verification_cert_path`                | `string` | File path for OS verification certificate chains.
 `os_verification_key_path`                 | `string` | File path for extracted OS public keys.
 `serial_console_trusted_user_ca_keys_path` | `string` | File path for serial console trusted CA keys.
 `serial_console_detatched_signature_path`  | `string` | File path for serial console detached signature.
 `serial_console_access_level_dir`          | `string` | Directory path for placing serial console access restriction flags.
 `syslog_client_conf_override_path`         | `string` | File path for systemd Syslog client environment overrides.
 `syslog_root_cert_path`                    | `string` | File path for remote Syslog server root CA certificates.

 ## Code References

 *   [credential_manager.h](file:///google3/third_party/milotic/external/cc/tlbmc/credentials/credential_manager.h):
     Header definition of `CredentialManager` and staging configuration
     parameters.
 *   [credential_manager.cc](file:///google3/third_party/milotic/external/cc/tlbmc/credentials/credential_manager_impl.cc):
     Implementation of CSR generation, OpenSSL CLI verification, atomic file
     staging, and asynchronous service restart.
	<!--*
	# Document freshness: For more information, see go/fresh-source.
	freshness: { owner: 'tlbmc-dev' reviewed: '2026-06-05' }
	*-->

	# Credential Management

	## Purpose & Overview

	The `CredentialManager` component is responsible for managing cryptographic
	identities, credentials, and secure communication anchors within tlBMC. It acts
	as the central authority for loading, generating, installing, and verifying
	secure artifacts across the BMC lifecycle.

	Specifically, `CredentialManager` handles:

	* Cryptographic Identities & CSRs: Generating RSA private keys and
	Certificate Signing Requests (`GenerateCsr`).
	* Server Certificates (`server_cert`): Installing staged server
	certificates for HTTPS/Redfish endpoints (`InstallServerCert`).
	* Dynamic Client CA Trust Bundles (`trust_bundle`): Managing dynamic
	client CA trust bundles used for mTLS client authentication
	(`InstallTrustBundle`).
	* SSH Trusted User CA Keys: Parsing and managing signatures and keys for
	secure SSH access (`bmc_ssh_trusted_user_ca_keys`).
	* Syslog Root Certificates & Target Configuration: Managing secure root
	certificates and remote target logging configurations (`InstallSyslogCert`).
	* OS Verification Keys: Verifying and storing OS signing certificates
	(`InstallOsVerificationCertificate`).

	## Root of Trust

	The Owner Verification Certificate (`OwnerVerificationCert`) acts as the
	primary cryptographic root of trust (anchor) for the BMC. Loaded from the
	configured file path (`owner_verification_cert_path`) upon initialization, it
	provides the cryptographic anchor required to verify incoming credentials, trust
	bundles, and serial console keys.

	`CredentialManager` uses OpenSSL CLI wrappers via `ShellExecutor` to validate
	cryptographic signatures against this root of trust:

	* **Trust Bundle & Serial Console Keys Verification
	(`kTrustBundleVerifyWithCaCommand`)**: Runs `openssl smime -verify -binary
	-inform PEM -in '%s' -content '%s' -CAfile '%s' -purpose any` to verify
	S/MIME detached signatures against the staged payload using the Owner
	Verification Certificate as the trusted CA.
	* OS Verification Certificate Verification (`kOsCertVerifyCommand`): Runs
	`openssl verify -CAfile '%s' -purpose any '%s'` to verify that incoming OS
	certificate chains are correctly anchored and signed by the Owner
	Verification Certificate.

	## Key Functionality & Features

	### 1. CSR Generation (`GenerateCsr`)

	When generating a new Certificate Signing Request:

	* RSA Private Key Generation: Creates a fresh in-memory RSA private key
	(`private_key_`) using OpenSSL via `GeneratePrivateKey()`.
	* X509 Request Construction: Allocates a new `X509_REQ` structure and
	populates its Subject Name entries (`C`, `ST`, `L`, `O`, `OU`, `CN`) using
	the fields specified in `CsrParams` (Country, State, City, Org, Unit, Common
	Name).
	* Subject Alternative Names (SANs): If `alternative_names` (SANs) are
	provided in `CsrParams`, formats them as `DNS:<san>` separated by commas,
	attaches the `NID_subject_alt_name` extension, and pushes it to the request
	extensions stack.
	* Signing & Output: Sets the public key, signs the request using
	`EVP_sha256()`, writes to a memory BIO, and returns the resulting
	PEM-formatted CSR string. The generated private key is securely retained in
	memory for the subsequent certificate installation step.

	### 2. Server Certificate Installation (`InstallServerCert`)

	Installing a signed server certificate completes the identity renewal cycle:

	* Key Matching: Requires `GenerateCsr` to have been executed earlier so
	that `private_key_` resides in memory. Reads the incoming PEM certificate
	buffer and executes `X509_check_private_key()` to confirm that the staged
	PEM cert matches the in-memory private key.
	* Atomic Staging: Writes both the PEM certificate and the serialized
	private key into a temporary staging directory (`<credential_dir>-tmp`). It
	then performs an atomic rename (`FileManager::RenamePath`) over the live
	directory (e.g., `/etc/ssl/certs/bmc`) to guarantee that key and certificate
	remain completely synchronized without race conditions.
	* Non-Blocking Asynchronous Service Restart: Spawns a detached background
	thread (`RestartBmcwebInASeparateThread()`) that sleeps for a short 3-second
	delay (`kServerRestartDelaySeconds`) before executing `systemctl restart
	--no-block bmcweb`. This ensures the active Redfish/gRPC response
	successfully completes before the underlying web server reloads.

	### 3. Trust Bundle & Syslog Installation

	* Trust Bundle Installation (`InstallTrustBundle`):
	* Signature Verification: Stages incoming trust bundle PEM data and
	detached signature into secure temporary files
	(`/tmp/trust_bundle_XXXXXX`, `/tmp/signature_XXXXXX`). Verifies the
	signature using `VerifyAndStageCertificate` against the root of trust.
	* Rate-Limiting: Enforces an installation retry delay
	(`kTrustBundleRetryDelaySeconds = 4` seconds) to prevent update flooding
	and race conditions during consecutive installation attempts.
	* Commit & Reload: Once validated, atomically stages the bundle and
	signature to persistent storage and triggers an asynchronous,
	non-blocking restart of `bmcweb`.
	* Syslog Installation (`InstallSyslogCert`):
	* Accepts a Syslog root certificate along with target IP and port
	configurations (`SyslogTargetConfig`).
	* Generates a systemd environment override block (`[Service]
	Environment=PROD_SYSLOG_IP=...`) and commits it to the configured
	override path (`syslog_client_conf_override_path`).
	* Writes the Syslog root certificate to disk, fully reverting the
	configuration override if saving fails.

	### 4. Owner Verification Config

	`CredentialManager` parses the `OwnerVerificationCertConfiguration` textproto
	(`owner_verification_config_path`) using `proto2::TextFormat::Parser`.

	* Firmware Update Enablement: Evaluates the `fw_update_enabled` property
	to determine firmware update enablement (`IsFirmwareUpdateable()`). If no
	configuration file is present, firmware updates are enabled by default.
	* Serial Console Policy: Evaluates the `serial_console_access_level` enum:
	* `ACCESS_FULL`: Allows complete interactive console access.
	* `ACCESS_READONLY`: Writes an indicator file (`serial_console_readonly`)
	into the serial console access level directory
	(`serial_console_access_level_dir`).
	* `ACCESS_DISABLE`: Writes a disabled indicator file
	(`serial_console_disabled`) to block serial console logins.

	## Configuration Parameters (`CredentialManagerParams`)

	When instantiating `CredentialManager`, parameters are configured via the
	`CredentialManagerParams` struct:

	Parameter \| Type \| Description
	:----------------------------------------- \| :------- \| :----------
	`private_key_path` \| `string` \| File path for storing/reading the BMC RSA private key.
	`cert_path` \| `string` \| File path for storing/reading the BMC server certificate.
	`owner_verification_cert_path` \| `string` \| File path to the Owner Verification Certificate (Root of Trust).
	`owner_verification_config_path` \| `string` \| File path to the `OwnerVerificationCertConfiguration` textproto.
	`bmc_ssh_trusted_user_ca_keys_path` \| `string` \| File path for SSH trusted user CA keys signature.
	`trust_bundle_path` \| `string` \| File path for the dynamic client CA trust bundle.
	`trust_bundle_signature_path` \| `string` \| File path for the trust bundle detached signature.
	`os_verification_cert_path` \| `string` \| File path for OS verification certificate chains.
	`os_verification_key_path` \| `string` \| File path for extracted OS public keys.
	`serial_console_trusted_user_ca_keys_path` \| `string` \| File path for serial console trusted CA keys.
	`serial_console_detatched_signature_path` \| `string` \| File path for serial console detached signature.
	`serial_console_access_level_dir` \| `string` \| Directory path for placing serial console access restriction flags.
	`syslog_client_conf_override_path` \| `string` \| File path for systemd Syslog client environment overrides.
	`syslog_root_cert_path` \| `string` \| File path for remote Syslog server root CA certificates.

	## Code References

	* [credential_manager.h](file:///google3/third_party/milotic/external/cc/tlbmc/credentials/credential_manager.h):
	Header definition of `CredentialManager` and staging configuration
	parameters.
	* [credential_manager.cc](file:///google3/third_party/milotic/external/cc/tlbmc/credentials/credential_manager_impl.cc):
	Implementation of CSR generation, OpenSSL CLI verification, atomic file
	staging, and asynchronous service restart.