Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Cross-Signing

Cross-signing lets one CA issue a certificate for another CA’s public key, creating an alternative trust chain. This is useful when:

  • Migrating between CAs — a new CA can be cross-signed by the old one so that relying parties that only trust the old root can still validate certificates issued by the new CA.
  • Bridging to external PKI — an Akamu CA can cross-sign an external CA (or vice versa) to establish mutual trust without replacing either root.
  • Multi-algorithm deployments — an RSA CA can cross-sign an EC CA (or the reverse) so that clients supporting only one algorithm can validate certificates from either.

The resulting cross-certificate has BasicConstraints: cA=TRUE, pathLen=0, meaning the subject CA may sign end-entity certificates but cannot create further subordinate CAs. Key usage is restricted to keyCertSign and cRLSign.

Prerequisites

  • A running Akamu server with the [admin] section configured.
  • An authenticated operator session with the administrator or ca_operations role. See akamuctl — Admin CLI for authentication methods.

Listing available CAs

Before cross-signing, identify the CAs configured on your server:

akamuctl ca list

Example output:

ID       DEFAULT  KEY TYPE    HASH
rsa      yes      rsa:4096    sha256
ec       no       ec:P-256    sha256

The issuer is the CA that will sign the cross-certificate. The subject is the CA whose public key will be signed.

Cross-signing another CA on the same server

When both CAs are configured on the same Akamu instance, use --subject-ca-id:

akamuctl ca cross-sign rsa --subject-ca-id ec --validity-years 5

This makes the RSA CA (issuer) sign a certificate for the EC CA (subject). The resulting cross-certificate is valid for 5 years.

Example JSON output (-o json):

{
  "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "issuer_ca_id": "rsa",
  "subject_ca_id": "ec",
  "subject_dn": "CN=Akamu EC CA",
  "serial_number": "0a1b2c3d…",
  "not_before": 1783080000,
  "not_after": 1940846400,
  "cross_cert_pem": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----\n",
  "chain_pem": "-----BEGIN CERTIFICATE-----\n…(cross-certificate)…\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n…(issuer CA)…\n-----END CERTIFICATE-----\n",
  "created": 1783080000
}

The returned id is the UUID of the stored cross-certificate. Use it with the cross-cert subcommands to inspect or download the certificate. chain_pem is the cross-certificate followed by the issuer CA certificate — the chain a relying party that trusts the issuer CA needs to reach the subject CA.

Nothing else needs to change on the subject CA: it keeps issuing with its own certificate, and ACME clients are offered the chain through the cross-certificate automatically (see Alternate chains for ACME clients).

To cross-sign in the other direction (EC signs RSA):

akamuctl ca cross-sign ec --subject-ca-id rsa --validity-years 5

Cross-signing an external CA

When the subject CA is not configured on this server, provide its certificate as a PEM file using --subject-cert:

akamuctl ca cross-sign rsa \
    --subject-cert /path/to/partner-ca.pem \
    --validity-years 3

The PEM file must contain a CA certificate (BasicConstraints: cA=TRUE). The server rejects end-entity certificates.

Attaching an OCSP-signing EKU

If a CA also serves its own OCSP responses, RFC 6960 §4.2.2.2 (criterion 2) requires the certificate used to sign OCSP responses to carry the id-kp-OCSPSigning extended key usage (1.3.6.1.5.5.7.3.9). Since a CA’s self-signed certificate predates that requirement, the practical way to add the EKU is to cross-sign the CA: relying parties that validate a leaf through the cross-certificate (the alternate chain) see the EKU on the issuing CA certificate:

akamuctl ca cross-sign rsa --subject-ca-id ec \
    --extended-key-usages ocsp_signing

The --extended-key-usages flag takes a comma-separated list of short names (server_auth, client_auth, code_signing, email_protection, time_stamping, ocsp_signing) or dotted-decimal OID strings. The EKU extension is non-critical; omitting the flag leaves the cross-certificate without an EKU extension:

# Attach two EKUs
akamuctl ca cross-sign rsa --subject-ca-id ec \
    --extended-key-usages ocsp_signing,server_auth

EKUs on a CA certificate constrain its leaves. OpenSSL, NSS and Windows reject a leaf whose purpose is not listed in the EKU extension of every CA certificate above it. A cross-certificate with only ocsp_signing makes TLS server certificates validated through it fail. List every purpose the CA’s leaves need, for example --extended-key-usages server_auth,client_auth,ocsp_signing.

Restricting which EKUs a CA may grant

By default a CA may attach any EKU to the cross-certificates it issues. To restrict that, configure an allowed_ekus list on the CA:

[[ca]]
id = "rsa"
…
[ca.cross_sign]
allowed_ekus = ["server_auth", "ocsp_signing"]

Cross-sign requests whose EKUs are not a subset of the list are rejected with 400 Bad Request before any signing work. Entries may be short names or dotted-decimal OID strings; they are normalized to dotted-decimal OIDs before comparison, so server_auth and 1.3.6.1.5.5.7.3.1 are equivalent. The special value 2.5.29.37.0 (anyEKU) always passes — inside an EKU extension it means “no restriction”, the same as omitting the EKU extension entirely. See the [ca.cross_sign] section of the configuration reference.

Listing cross-certificates

List all cross-certificates stored on the server:

akamuctl cross-cert list

Filter by issuer or subject CA:

# All cross-certificates issued by the RSA CA
akamuctl cross-cert list --issuer-ca rsa

# All cross-certificates where the EC CA is the subject
akamuctl cross-cert list --subject-ca ec

Pagination is available via --limit and --offset (defaults: 100 and 0).

Inspecting a cross-certificate

Show the full metadata for a cross-certificate by its UUID:

akamuctl cross-cert show a1b2c3d4-5678-9abc-def0-1234567890ab

This returns the issuer CA ID, subject CA ID (or null for external subjects), serial number, validity window, creation timestamp, and the full PEM.

Downloading a cross-certificate

Save the cross-certificate PEM to a file:

akamuctl cross-cert download a1b2c3d4-5678-9abc-def0-1234567890ab \
    -o cross-cert.pem

Without -o, the PEM is printed to stdout.

Add --chain to download the cross-certificate followed by the issuer CA certificate:

akamuctl cross-cert download a1b2c3d4-5678-9abc-def0-1234567890ab \
    --chain -o cross-chain.pem

The web UI’s cross-certificate detail page offers the same chain for copy and download.

Alternate chains for ACME clients

When a CA on this server has been cross-signed by another CA on this server (--subject-ca-id), every certificate it issues can be downloaded through two chains (RFC 8555 §7.4.2):

  • the default chain, unchanged: leaf followed by the subject CA’s own certificate;
  • one alternate chain per currently valid cross-certificate: leaf, cross-certificate, issuer CA certificate.

The certificate download response advertises each alternate with a Link header:

Link: <https://acme.example.com/acme/ec/cert/<cert-id>/alt/<cross-cert-id>>; rel="alternate"

ACME clients choose among them, for example with certbot’s --preferred-chain "<issuer CA common name>". The alternate URL accepts the same unauthenticated GET and POST-as-GET requests, with the same account checks, as the default one.

STAR orders (RFC 8739) get rolling alternates the same way: the STAR certificate URL links …/cert/star/<order-id>/alt/<cross-cert-id>, which always serves the order’s current certificate through that cross-certificate, with the Cert-Not-Before/Cert-Not-After headers and the access rules of the STAR URL.

A cross-certificate is offered only while it is valid and only for certificates signed by the key it certifies, so a cross-certificate for a CA’s previous key is not offered after a key rotation. Cross-certificates for external CAs (--subject-cert) have no leaves on this server and are never offered.

Public discovery endpoint

Relying parties can discover cross-certificates without authentication via:

GET /ca/{ca_id}/cross-certs

This returns all cross-certificates where the specified CA is the subject (i.e., certificates that provide an alternative trust path to this CA). The response includes the PEM for each cross-certificate.

Example:

curl https://acme.example.com/ca/ec/cross-certs
{
  "cross_certs": [
    {
      "id": "a1b2c3d4-…",
      "issuer_ca_id": "rsa",
      "subject_dn": "CN=Akamu EC CA",
      "serial_number": "0a1b2c3d",
      "not_before": 1783080000,
      "not_after": 1940846400,
      "cross_cert_pem": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----\n",
      "created": 1783080000
    }
  ]
}

Relying parties can use this endpoint to build complete certificate chains when their trust store does not include the issuing CA’s root but does include the cross-signing CA’s root. ACME clients get the same chains ready-made as alternate chains.

Verifying a cross-certificate

After downloading, verify the cross-certificate chains back to the issuer CA:

# Download the issuer CA certificate
akamuctl ca cert rsa -o rsa-ca.pem

# Verify the cross-certificate
openssl verify -CAfile rsa-ca.pem cross-cert.pem

Expected output:

cross-cert.pem: OK

To inspect the cross-certificate’s extensions:

openssl x509 -in cross-cert.pem -text -noout

Look for:

  • X509v3 Basic Constraints: critical with CA:TRUE, pathlen:0
  • X509v3 Key Usage: critical with Certificate Sign, CRL Sign
  • X509v3 Authority Key Identifier matching the issuer CA’s Subject Key Identifier
  • X509v3 Subject Key Identifier matching the subject CA’s public key

Complete walkthrough

This example sets up bidirectional cross-signing between an RSA and EC CA, then verifies both chains.

# 1. Authenticate
akamuctl login

# 2. List CAs to confirm both are configured
akamuctl ca list

# 3. RSA signs EC (EC certificates can be verified via the RSA root)
akamuctl ca cross-sign rsa --subject-ca-id ec --validity-years 5

# 4. EC signs RSA (RSA certificates can be verified via the EC root)
akamuctl ca cross-sign ec --subject-ca-id rsa --validity-years 5

# 5. List all cross-certificates
akamuctl cross-cert list

# 6. Download and verify the RSA→EC cross-certificate
akamuctl cross-cert list --issuer-ca rsa -o json | \
    jq -r '.cross_certs[0].id'
# Use the UUID from the output:
akamuctl cross-cert download <uuid> -o rsa-signs-ec.pem
akamuctl ca cert rsa -o rsa-ca.pem
openssl verify -CAfile rsa-ca.pem rsa-signs-ec.pem

# 7. Download and verify the EC→RSA cross-certificate
akamuctl cross-cert list --issuer-ca ec -o json | \
    jq -r '.cross_certs[0].id'
akamuctl cross-cert download <uuid> -o ec-signs-rsa.pem
akamuctl ca cert ec -o ec-ca.pem
openssl verify -CAfile ec-ca.pem ec-signs-rsa.pem

Cross-certificate properties

PropertyValue
Basic ConstraintscA=TRUE, pathLen=0 (critical)
Key UsagekeyCertSign | cRLSign (critical)
Extended Key UsageOptional (non-critical); only present when extended_key_usages is specified
Subject Key IdentifierFrom the subject CA’s public key
Authority Key IdentifierFrom the issuer CA’s public key
Validity computationvalidity_years Julian years (365.25 days) from issuance time
BackdateNone (operator-initiated, not time-sensitive)
Maximum validity50 years
Minimum validity1 year