Skip to content

api: add GET /intermediate.crt for AIA caIssuers#2655

Open
Yannik wants to merge 1 commit intosmallstep:masterfrom
Yannik:feat/intermediate-cert-der-endpoint
Open

api: add GET /intermediate.crt for AIA caIssuers#2655
Yannik wants to merge 1 commit intosmallstep:masterfrom
Yannik:feat/intermediate-cert-der-endpoint

Conversation

@Yannik
Copy link
Copy Markdown
Contributor

@Yannik Yannik commented Apr 20, 2026

Name of feature:

api: add GET /intermediate.crt for AIA caIssuers

Pain or issue this feature alleviates:

step-ca currently exposes /intermediates.pem, but that endpoint is not a good
fit for a certificate's AIA caIssuers URL:

  • It serves PEM, while RFC 5280 Section 4.2.2.1 says an HTTP
    id-ad-caIssuers accessLocation must point to either a single
    DER-encoded certificate as specified by RFC 2585 Section 3, or a certs-only
    CMS bundle. For a single-certificate response, RFC 5280 recommends
    Content-Type: application/pkix-cert, the media type registered by RFC 2585
    Section 4.1.
  • It is only registered on the HTTPS mux. For TLS subscriber certificates,
    CA/Browser Forum Baseline Requirements Section 7.1.2.7.7 describe
    id-ad-caIssuers as an HTTP URL of the issuing CA certificate, so clients
    can fetch the issuer before they can validate the CA's TLS certificate.

Why is this important to the project (if not answered above):

This makes step-ca able to serve the issuing intermediate certificate in the
format and scheme expected by common AIA caIssuers clients, without requiring
extra infrastructure around step-ca.

Is there documentation on how to use this feature? If so, where?

No standalone documentation is added in this PR. The endpoint can be used
by setting a certificate template's issuingCertificateURL to the HTTP
endpoint:

{
  "issuingCertificateURL": ["http://ca.example.com/intermediate.crt"]
}

In what environments or workflows is this feature supported?

When step-ca is an intermediate CA.

In what environments or workflows is this feature explicitly NOT supported (if any)?

If step-ca is a Root CA (GetIntermediateCertificates() returns no certificates)

Supporting links/other PRs/issues:

  • RFC 5280 Section 4.2.2.1: Authority Information Access
  • RFC 2585 Sections 3 and 4.1: Internet X.509 Public Key Infrastructure
    Operational Protocols: FTP and HTTP
  • CA/Browser Forum Baseline Requirements Section 7.1.2.7.7:
    id-ad-caIssuers for TLS subscriber certificates
  • Mozilla bug 1637093: PEM served via AIA caIssuers flagged as a compliance
    issue

@github-actions github-actions Bot added the needs triage Waiting for discussion / prioritization by team label Apr 20, 2026
Adds a new endpoint that returns the CA's issuing intermediate
certificate as a single DER-encoded X.509 certificate for use as an
Authority Information Access (AIA) caIssuers URI.

RFC 5280 Section 4.2.2.1 permits HTTP caIssuers URIs to point to a
single DER certificate as specified by RFC 2585 Section 3. For that
single-certificate representation, RFC 5280 recommends Content-Type
application/pkix-cert, the media type registered by RFC 2585 Section
4.1.

The existing /intermediates.pem endpoint serves PEM on the HTTPS
listener only. Neither property is suitable for TLS subscriber
certificate AIA use: PEM over AIA has been flagged as a compliance
issue by browser root programs (see Mozilla bug 1637093), and the
CA/Browser Forum Baseline Requirements Section 7.1.2.7.7 describe
id-ad-caIssuers as an HTTP URL of the issuing CA certificate. This lets
clients fetch the issuer before they can validate the CA's TLS
certificate.

The endpoint is mounted on both the secure and insecure muxes, mirroring
/crl. The insecure server now starts for this endpoint when
insecureAddress is configured and the CA has an issuer certificate.
@Yannik Yannik force-pushed the feat/intermediate-cert-der-endpoint branch from 8f90322 to 4e021fe Compare April 20, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs triage Waiting for discussion / prioritization by team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants