Certificate Chains (PEM)

Option B: Root CA → Intermediate → Leaf

1. Generate certificate chain and prepare the chain file#

   If your organization already has a PKI, obtain a leaf certificate (and intermediate chain if applicable) from your CA. Place the leaf certificate (and any intermediates, root excluded) into chain.pem and skip to the next step.

   Otherwise, generate a chain locally with openssl. Choose the option that fits your setup and follow all commands within that tab – each tab is self-contained.

   Add an intermediate CA to keep the root CA key offline or to delegate signing authority.

   mkdir -p ~/.ocm/keys/pem-demo && cd ~/.ocm/keys/pem-demo
   
   # Root CA
   openssl genrsa -out root.key 4096
   openssl req -x509 -new -nodes \
     -key root.key -sha256 -days 3650 \
     -subj "/CN=OCM Demo Root CA" \
     -out root.crt
   
   # Intermediate CA
   openssl genrsa -out intermediate.key 4096
   openssl req -new -key intermediate.key \
     -subj "/CN=OCM Demo Intermediate CA" \
     -out intermediate.csr
   cat > intermediate-ext.cnf <<'EOF'
   basicConstraints = CA:TRUE
   keyUsage = digitalSignature, keyCertSign, cRLSign
   EOF
   openssl x509 -req \
     -in intermediate.csr -CA root.crt -CAkey root.key -CAcreateserial \
     -sha256 -days 1825 -extfile intermediate-ext.cnf \
     -out intermediate.crt
   
   # Leaf certificate
   openssl genrsa -out leaf.key 4096
   openssl req -new -key leaf.key \
     -subj "/CN=OCM Demo Signer" \
     -out leaf.csr
   openssl x509 -req \
     -in leaf.csr -CA intermediate.crt -CAkey intermediate.key -CAcreateserial \
     -sha256 -days 365 -out leaf.crt
   
   chmod 600 root.key intermediate.key leaf.key
   chmod 644 root.crt intermediate.crt leaf.crt

   Files created:

   File	Purpose
   root.key / root.crt	Root CA – keep the key offline in production
   intermediate.key / intermediate.crt	Intermediate CA
   leaf.key / leaf.crt	Leaf – the private key used for signing

   Prepare the chain file – leaf first, then intermediate (root excluded):

   cd ~/.ocm/keys/pem-demo
   cat leaf.crt intermediate.crt > chain.pem
   chmod 644 chain.pem

   Order matters

   The chain file must start with the leaf certificate, followed by any intermediates in order toward the root. The root CA is always omitted.

   Summary of files per role:

   Role	Files needed
   Signer	leaf.key (private key), chain.pem (leaf + any intermediates)
   Verifier	root.crt (trust anchor only)

2. Configure .ocmconfig file#

   Create separate credential entries for the signer and verifier roles. The file paths must be absolute – ~ and $HOME are not expanded in YAML values. Use the shell commands below to generate the files with the correct paths automatically:

   # Signer configuration
   cat > ~/.ocmconfig-pem-sign <<EOF
   type: generic.config.ocm.software/v1
   configurations:
     - type: credentials.config.ocm.software
       consumers:
         - identity:
             type: RSA/v1alpha1
             algorithm: RSASSA-PSS
             signature: default
           credentials:
             - type: Credentials/v1
               properties:
                 private_key_pem_file: $(realpath ~/.ocm/keys/pem-demo/leaf.key)
                 public_key_pem_file: $(realpath ~/.ocm/keys/pem-demo/chain.pem)
   EOF
   
   # Verifier configuration
   cat > ~/.ocmconfig-pem-verify <<EOF
   type: generic.config.ocm.software/v1
   configurations:
     - type: credentials.config.ocm.software
       consumers:
         - identity:
             type: RSA/v1alpha1
             algorithm: RSASSA-PSS
             signature: default
           credentials:
             - type: Credentials/v1
               properties:
                 public_key_pem_file: $(realpath ~/.ocm/keys/pem-demo/root.crt)
   EOF

   Trust anchor isolation

   When a self-signed certificate is supplied as public_key_pem_file for verification, OCM uses it as an isolated trust anchor and bypasses the system root store entirely. Only signatures rooted in that specific CA will verify successfully.

   For the full credential property and consumer identity reference, see Credential Consumer Identities – RSA/v1alpha1.

3. Create signer spec file#

   The --signer-spec flag enables the PEM encoding policy. Create the spec file:

   cat > ~/.ocm/keys/pem-demo/pem-signer.yaml <<EOF
   type: RSASigningConfiguration/v1alpha1
   signatureAlgorithm: RSASSA-PSS
   signatureEncodingPolicy: PEM
   EOF

   This controls how the signature is encoded. It does not contain credentials – those are always resolved from .ocmconfig.

4. Sign component version#

   Use --dry-run first to compute and print the signature without writing it to the repository:

   ocm sign cv \
     --config ~/.ocmconfig-pem-sign \
     --signer-spec ~/.ocm/keys/pem-demo/pem-signer.yaml \
     --dry-run \
     /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

   Once satisfied, sign for real:

   ocm sign cv \
     --config ~/.ocmconfig-pem-sign \
     --signer-spec ~/.ocm/keys/pem-demo/pem-signer.yaml \
     /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

   Early access

   PEM signing is an early access feature. The OCM CLI prints an experimental notice during signing and verification – this is expected and does not indicate a failure. We are awaiting feedback and the interface may evolve.

   Expected signature value in the component descriptor

   -----BEGIN SIGNATURE-----
   Signature Algorithm: RSASSA-PSS
   <base64-encoded signature bytes>
   -----END SIGNATURE-----
   -----BEGIN CERTIFICATE-----
   <leaf certificate DER>
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   <intermediate CA DER>  ← only present if intermediates were included in chain.pem
   -----END CERTIFICATE-----

5. Verify signature#

   ocm verify cv \
     --config ~/.ocmconfig-pem-verify \
     /tmp/helloworld/transport-archive//github.com/acme.org/helloworld:1.0.0

   No --verifier-spec is needed – OCM infers the PEM encoding from the application/x-pem-file media type stored alongside the signature and selects the correct handler automatically.

   Expected output

   time=2026-04-01T10:00:00.000+02:00 level=INFO msg="verifying signature" name=default
   time=2026-04-01T10:00:00.001+02:00 level=INFO msg="signature verification completed" name=default duration=1.2ms
   time=2026-04-01T10:00:00.001+02:00 level=INFO msg="SIGNATURE VERIFICATION SUCCESSFUL"

   ✅ Success! ✅
   The component version is verified as authentic and unmodified.

   If verification fails, see the troubleshooting section below.