sigstore/fulcio

SANs are used in verification policies as the primary identifier for a workload. When choosing a SAN for your service, consider these criteria:

• Policy Queryability: How will users want to write policies? A good test is whether the value works well with cosign verify --certificate-identity=<VALUE>.
• Specificity: Choose the most specific identifier that describes the workload without being too broad (granting unintended access) or too narrow (making management difficult).
• Stability: Avoid identifiers that change per instance (like UUIDs). If a policy requires a regex to match a SAN, the SAN is likely too specific.
• Uniqueness: SANs should be unique to the issuer and prevent one resource from spoofing another.
• Documentation: All SANs produced by a provider should be well-defined and documented.

Case Study: GitHub Actions

GitHub Actions uses job_workflow_ref as its SAN. This is preferred over other options because:

• It is tied to a specific Job in a workflow.
• It supports reusable workflows, allowing centralized policies.
• It is more stable than a unique Job ID (which changes every run) and more specific than a Repository URL (which is too broad).

Fulcio issues code signing certificates by verifying an OpenID Connect (OIDC) identity and proving possession of a private key. The process follows these steps:

1. Certificate Request Input: The client submits an OIDC identity token (JWT), a public key, and a signed challenge (a signature of the sub claim from the OIDC token). Alternatively, a Certificate Signing Request (CSR) can be provided.
2. Authentication: Fulcio authenticates the OIDC token by using the iss (issuer) claim to find the issuer's discovery endpoint, downloading their signing keys, and verifying the token signature.
3. Verifying the Challenge: Fulcio verifies that the client owns the private key corresponding to the provided public key by validating the signed challenge or the CSR.
4. Constructing the Certificate: Fulcio creates an X.509 certificate containing the client's public key, sets the Subject Alternative Name (SAN) to the OIDC sub claim (e.g., email, SPIFFE ID, or GitHub Actions identity), and includes the OIDC issuer in a custom field.
5. Signing: The certificate is signed by a Certificate Authority (CA) backend to create a chain of trust.
6. CT Log Inclusion: The certificate is sent to a Certificate Transparency (CT) log as a precertificate. The log returns a Signed Certificate Timestamp (SCT), which is embedded in the certificate before a final signature.
7. Delivery: The final certificate containing the embedded SCT is returned to the client.

To maintain a stable certificate chain (e.g., keeping a long-lived Root CA while rotating Leaf certificates), use the --existing-root-cert and --existing-intermediate-cert flags (or EXISTING_ROOT_CERT and EXISTING_INTERMEDIATE_CERT environment variables).

Decision Logic for Reuse

• Fresh Start: Generate all (Root + Intermediate + Leaf).
• Keep Root, Rotate Intermediate/Leaf: Use --existing-root-cert. This generates a new intermediate and leaf signed by the existing root.
• Keep Root & Intermediate, Rotate Leaf: Use --existing-root-cert AND --existing-intermediate-cert. This generates only a new leaf.
• Direct Leaf from Root: Use --existing-root-cert but do NOT provide an intermediate key ID. This generates a leaf signed directly by the root.

Important Constraints:

• The existing certificate's public key MUST match the KMS key specified. The tool validates this match before proceeding.
• --template flags and --existing-...-cert flags are mutually exclusive for the same certificate tier.

# Example: Reuse Root and Intermediate to generate a new Leaf only (GCP KMS)
./certificate-maker create "https://fulcio.example.com" \
  --kms-type gcpkms \
  --gcp-credentials-file ~/.config/gcloud/application_default_credentials.json \
  --root-key-id projects/<project>/locations/<loc>/keyRings/<ring>/cryptoKeys/root/cryptoKeyVersions/1 \
  --existing-root-cert ./existing-root.pem \
  --intermediate-key-id projects/<project>/locations/<loc>/keyRings/<ring>/cryptoKeys/intermediate/cryptoKeyVersions/1 \
  --existing-intermediate-cert ./existing-intermediate.pem \
  --leaf-key-id projects/<project>/locations/<loc>/keyRings/<ring>/cryptoKeys/leaf/cryptoKeyVersions/1 \
  --leaf-cert leaf.pem

Fulcio supports identities based on URIs or plain usernames, requiring a SubjectDomain in the Fulcio configuration.

URI Identity

• Token Claim: sub must be a URI (e.g., https://example.com/users/1).
• Constraint: The domain of the sub claim must match the SubjectDomain configuration exactly. The issuer must partially match the domain (scheme, TLD, and second-level domain).
• Result: sub is included as a SAN URI.

Username Identity

• Token Claim: sub is a username (e.g., exampleUsername).
• Constraint: The issuer must partially match the domain (TLD and second-level domain). The SubjectDomain is appended to sub to form the identity: sub!SubjectDomain (e.g., exampleUsername!example.com), which is included as an OtherName SAN.

// URI Example
{
    "sub": "https://example.com/users/1"
}

// Username Example
{
    "sub": "exampleUsername"
}