TKeeper logoTKeeperDevelopers
Download docs

X.509 Authorities

LLM index

X.509 authority support lives in the authority-x509 feature and currently requires the ecc platform.

Build example:

./gradlew shadowJar -Pkeeper.features=authority-x509 -Pkeeper.platforms=ecc

An X.509 authority lets TKeeper parse a DER-encoded TBS certificate, expose certificate fields to policy, and sign only approved certificate requests.

Use X.509 authorities for:

  • internal CA operations
  • workload identity certificates
  • service or agent certificates
  • certificate issuance requiring four-eye approval

Enforcement boundary

TKeeper signs the DER-encoded TBS certificate after policy evaluation. It does not replace the rest of the CA:

  • requester authentication and enrollment authorization
  • proof-of-possession checks
  • serial-number allocation
  • final certificate assembly and publication
  • certificate transparency, revocation, renewal, or inventory

The CA pipeline must submit and publish the same certificate content that policy approved. Relying parties must still validate the completed certificate chain and constraints.

Strict CEL roots:

  • encodedDerHex, encodedSha256
  • version, serialNumber, signature
  • issuer, subject, validity
  • subjectPublicKeyInfo
  • issuerUniqueID, subjectUniqueID
  • extensions

The intent accepts a DER-encoded RFC 5280 TBSCertificate. Malformed DER fails intent validation before policy evaluation.

Authority example: workload server certificate

This authority represents one logical action: issue a server leaf certificate for api.internal.example. It is intended for attachment to a P-256 issuing key, limits validity to 24 hours, and requires one PKI operator approval.

schemaVersion: verdict.authority/v1
id: api-internal-workload-certificate
type: x509.tbs-certificate
version: 1.0.0

metadata:
  title: API workload server certificate

policy:
  id: api-internal-workload-certificate
  fallback: DENY
  approvers:
    pki-operator:
      algorithm: ED25519
      publicKey64: "BASE64_ENCODED_ED25519_PUBLIC_KEY"
  variables:
    expectedIssuer: "CN=Internal Issuing CA,O=Example Corp"
    permittedDnsName: "api.internal.example"
    maximumValiditySeconds: 86400
  allow:
    - id: reviewed-workload-leaf
      where:
        - "version == 3"
        - "signature.oid == '1.2.840.10045.4.3.2'"
        - "issuer.rfc2253 == expectedIssuer"
        - "subject.commonName == permittedDnsName"
        - "time.before(validity.notBefore, validity.notAfter)"
        - "time.durationSeconds(validity.notBefore, validity.notAfter) <= maximumValiditySeconds"
        - "extensions.basicConstraints.present && extensions.basicConstraints.critical"
        - "!extensions.basicConstraints.cA"
        - "extensions.keyUsage.present && extensions.keyUsage.critical"
        - "extensions.keyUsage.digitalSignature"
        - "lists.hasOnly(extensions.keyUsage.names, ['digitalSignature'])"
        - "extensions.extKeyUsage.present && extensions.extKeyUsage.serverAuth"
        - "lists.hasOnly(extensions.extKeyUsage.names, ['serverAuth'])"
        - "extensions.subjectAltName.present"
        - "lists.size(extensions.subjectAltName.all) == 1"
        - "lists.contains(extensions.subjectAltName.dnsNames, permittedDnsName)"
      approvals:
        threshold: 1
        approvers: [pki-operator]
  deny: []

Replace the issuer, DNS name, and publicKey64 with trusted production values. Another DNS identity or certificate profile should use another authority id and document. The rule governs the TBS certificate fields and approval requirement. The CA pipeline must still authenticate the requester, authorize control of the requested name, validate the submitted public key, and verify proof of possession before calling TKeeper.

See Authorities for the document and policy schema and CEL Functions for policy helpers.