feat: adds cert-utility.

[ianhundere]

closes #1869

Summary

currently, there is no standard method for creating cert chains for fulcio or tsa. the community has used an assortment of open source scripts/tools, but i thought it would be nice to have a small cloud agnostic go app to create/sign (via awskms, cloudkms, or azurekms) certificates. the smallstep crypto library is fairly comprehensive in its kms/cert capabilities.

this will focus on ExtKeyUsage / CodeSigning

@haydentherapper / @bobcallaway gave the go ahead in proceeding w/ this work.

Release Note

• Adds certificate utility to create and sign certificates via AWS KMS, Google Cloud KMS, or Azure Key Vault.

Documentation

Overview

This tool creates root and leaf certificates for:

• Fulcio (Code Signing Certificate Authority)

Requirements

• Access to one of the supported KMS providers (AWS, Google Cloud, Azure)
• Pre-existing KMS keys (the tool uses existing keys and does not create new ones)

Local Development

Clone and build the project locally:

# Clone the repository
git clone https://github.com/sigstore/fulcio

# Change to project directory
cd fulcio

# Build the binary
go build -o fulcio-certificate-maker ./cmd/certificate_maker

Usage

The tool can be configured using either command-line flags or environment variables.

Command-Line Interface

Available flags:

• --kms-type: KMS provider type (awskms, cloudkms, azurekms)
• --kms-region: KMS region (required for AWS KMS)
• --root-key-id: KMS key identifier for root certificate
• --leaf-key-id: KMS key identifier for leaf certificate
• --kms-tenant-id: Azure KMS tenant ID
• --kms-credentials-file: Path to credentials file (for Google Cloud KMS)
• --root-template: Path to root certificate template
• --leaf-template: Path to leaf certificate template
• --root-cert: Output path for root certificate (default: root.pem)
• --leaf-cert: Output path for leaf certificate (default: leaf.pem)

Environment Variables

• KMS_TYPE: KMS provider type ("awskms", "cloudkms", "azurekms")
• KMS_REGION: Region (required for AWS KMS, defaults to us-east-1)
• ROOT_KEY_ID: Key identifier for root certificate
• LEAF_KEY_ID: Key identifier for leaf certificate
• KMS_VAULT_NAME: Azure Key Vault name
• KMS_TENANT_ID: Azure tenant ID
• KMS_CREDENTIALS_FILE: Path to credentials file (for Google Cloud KMS)

Provider-Specific Configuration Examples

AWS KMS

export KMS_TYPE=awskms
export KMS_REGION=us-east-1
export ROOT_KEY_ID=alias/fulcio-root
export LEAF_KEY_ID=alias/fulcio-leaf

Google Cloud KMS

export KMS_TYPE=cloudkms
export ROOT_KEY_ID=projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/root-key
export LEAF_KEY_ID=projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/leaf-key
export KMS_CREDENTIALS_FILE=/path/to/credentials.json

Azure KMS

export KMS_TYPE=azurekms
export ROOT_KEY_ID=root-key
export LEAF_KEY_ID=leaf-key
export KMS_VAULT_NAME=my-vault
export KMS_TENANT_ID=tenant-id

Example Certificate Outputs

Fulcio Root CA Certificate

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1732586606 (0x67452c6e)
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: C=US, O=Sigstore, OU=Fulcio Root CA, CN=https://fulcio.com
        Validity
            Not Before: Jan  1 00:00:00 2024 GMT
            Not After : Jan  1 00:00:00 2034 GMT
        Subject: C=US, O=Sigstore, OU=Fulcio Root CA, CN=https://fulcio.com
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:73:77:29:2b:48:de:da:82:53:60:36:ac:9e:b7:
                    e1:78:3e:e1:d6:58:f1:7e:fa:b2:2a:28:c5:c8:d4:
                    25:c6:e8:5c:d1:63:a8:22:3e:a6:7b:bb:3b:d7:f3:
                    98:c8:25:52:12:2a:c1:fb:9b:56:af:97:77:a4:48:
                    89:be:49:bc:63
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Key Usage: critical
                Certificate Sign, CRL Sign
            X509v3 Basic Constraints: critical
                CA:TRUE, pathlen:1
            X509v3 Subject Key Identifier:
                BB:84:41:46:F0:A6:90:38:C0:73:1E:11:F4:58:7C:44:9B:C6:45:89
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:44:02:20:5c:35:e4:05:05:84:dd:e0:a7:5f:50:ca:04:66:
        0b:9f:ef:11:02:2d:99:0a:74:d5:c7:da:de:1f:f1:fc:71:34:
        02:20:4e:8c:c6:b9:c2:1c:b2:88:bc:20:62:52:ef:ef:cb:c6:
        4b:25:25:15:a8:14:25:e1:dd:60:d3:1f:ed:dc:a1:e9

Fulcio Leaf Certificate

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1732586607 (0x67452c6f)
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: C=US, O=Sigstore, OU=Fulcio Root CA, CN=https://fulcio.com
        Validity
            Not Before: Jan  1 00:00:00 2024 GMT
            Not After : Jan  1 00:00:00 2034 GMT
        Subject: C=US, O=Sigstore, OU=Fulcio Leaf CA, CN=https://fulcio.com
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:f8:ca:84:0d:9d:31:da:d0:94:1f:2a:53:ff:3f:
                    f2:39:ca:90:5b:8c:26:29:28:02:a7:e2:10:80:92:
                    1b:9f:3a:03:c7:cd:36:7a:2c:2b:1c:0c:95:bc:86:
                    73:b4:55:46:0e:50:29:34:1e:07:a6:64:41:13:ca:
                    36:5d:d4:71:dd
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Key Usage: critical
                Digital Signature, Certificate Sign, CRL Sign
            X509v3 Extended Key Usage:
                Code Signing
            X509v3 Basic Constraints: critical
                CA:TRUE, pathlen:0
            X509v3 Subject Key Identifier:
                0D:1B:3F:95:18:04:65:60:AD:E3:28:D0:B7:43:45:BD:FE:63:5A:DF
            X509v3 Authority Key Identifier:
                BB:84:41:46:F0:A6:90:38:C0:73:1E:11:F4:58:7C:44:9B:C6:45:89
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:45:02:21:00:c9:10:79:60:2f:e5:ab:79:43:09:7c:94:b8:
        05:07:11:01:43:93:de:c0:0e:47:21:ae:42:fc:11:c2:34:6e:
        8a:02:20:0e:40:85:99:3e:ce:b8:48:33:9d:1a:63:c4:57:40:
        49:2e:40:f8:87:16:81:e6:fa:1f:7f:0f:e4:9a:87:a3:e3

Running the Tool

Example with AWS KMS:

fulcio-certificate-maker  create \
  --kms-type awskms \
  --kms-region us-east-1 \
  --root-key-id alias/fulcio-root \
  --leaf-key-id alias/fulcio-leaf \
  --root-template pkg/certmaker/templates/root-template.json \
  --leaf-template pkg/certmaker/templates/leaf-template.json

Example with Azure KMS:

fulcio-certificate-maker create \
  --kms-type azurekms \
  --kms-tenant-id 1b4a4fed-fed8-4823-a8a0-3d5cea83d122 \
  --root-key-id "azurekms:name=sigstore-key;vault=sigstore-key" \
  --leaf-key-id "azurekms:name=sigstore-key-intermediate;vault=sigstore-key" \
  --intermediate-key-id "azurekms:name=sigstore-key-intermediate;vault=sigstore-key” \
  --root-cert root.pem \
  --leaf-cert leaf.pem \
  --with-intermediate \
  --intermediate-cert intermediate.pem

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 49.03%. Comparing base (cf238ac) to head (450b214).
Report is 242 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1870      +/-   ##
==========================================
- Coverage   57.93%   49.03%   -8.90%     
==========================================
  Files          50       70      +20     
  Lines        3119     5204    +2085     
==========================================
+ Hits         1807     2552     +745     
- Misses       1154     2417    +1263     
- Partials      158      235      +77     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests