diff --git a/README.md b/README.md index f834f5402..68c475477 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,16 @@ mygUY7Ii2zbdCdliiow= -----END CERTIFICATE----- ``` +### Certificate Maker + +The Fulcio's Certificate Maker is a tool for creating Fulcio compliant certificate chains. It supports: + +* Two-level chains (root -> leaf) +* Three-level chains (root -> intermediate -> leaf) +* Multiple KMS providers (AWS, Google Cloud, Azure, HashiCorp Vault) + +For detailed usage instructions and examples, see the [Certificate Maker documentation](docs/certificate-maker.md). + ### Verifying releases You can also verify signed releases (`fulcio-.sig`) using the artifact signing key: diff --git a/docs/certificate-maker.md b/docs/certificate-maker.md new file mode 100644 index 000000000..3a112ca96 --- /dev/null +++ b/docs/certificate-maker.md @@ -0,0 +1,171 @@ +# Fulcio Certificate Maker + +This tool creates root, intermediate (optional), and leaf certificates for Fulcio with code signing capabilities: + +- Two-level chain (root -> leaf) +- Three-level chain (root -> intermediate -> leaf) + +## Requirements + +- Access to one of the supported KMS providers (AWS, Google Cloud, Azure, HashiCorp Vault) +- Pre-existing KMS keys (the tool uses existing keys and does not create new ones) + +## Local Development + +Clone and build the project locally: + +```bash +# 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, gcpkms, azurekms, hashivault) +- `--root-key-id`: KMS key identifier for root certificate +- `--leaf-key-id`: KMS key identifier for leaf certificate +- `--aws-region`: AWS region (required for AWS KMS) +- `--azure-tenant-id`: Azure KMS tenant ID +- `--gcp-credentials-file`: Path to credentials file (for Google Cloud KMS) +- `--vault-address`: HashiCorp Vault address +- `--vault-token`: HashiCorp Vault token +- `--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) +- `--intermediate-key-id`: KMS key identifier for intermediate certificate +- `--intermediate-template`: Path to intermediate certificate template +- `--intermediate-cert`: Output path for intermediate certificate + +### Environment Variables + +- `KMS_TYPE`: KMS provider type ("awskms", "gcpkms", "azurekms", "hashivault") +- `ROOT_KEY_ID`: Key identifier for root certificate +- `KMS_INTERMEDIATE_KEY_ID`: Key identifier for intermediate certificate +- `LEAF_KEY_ID`: Key identifier for leaf certificate +- `AWS_REGION`: AWS Region (required for AWS KMS) +- `AZURE_TENANT_ID`: Azure tenant ID +- `GCP_CREDENTIALS_FILE`: Path to credentials file (for Google Cloud KMS) +- `VAULT_ADDR`: HashiCorp Vault address +- `VAULT_TOKEN`: HashiCorp Vault token + +### Certificate Templates + +The tool uses JSON templates to define certificate properties: + +- `root-template.json`: Defines root CA certificate properties +- `intermediate-template.json`: Defines intermediate CA certificate properties (when using --intermediate-key-id) +- `leaf-template.json`: Defines leaf certificate properties + +Templates are located in `pkg/certmaker/templates/`. + +### Provider-Specific Configuration Examples + +#### AWS KMS + +```shell +export KMS_TYPE=awskms +export AWS_REGION=us-east-1 +export ROOT_KEY_ID=alias/root-key +export KMS_INTERMEDIATE_KEY_ID=alias/intermediate-key +export LEAF_KEY_ID=alias/leaf-key +``` + +#### Google Cloud KMS + +```shell +export KMS_TYPE=gcpkms +export ROOT_KEY_ID=projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY_NAME/cryptoKeyVersions/VERSION +export LEAF_KEY_ID=projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY_NAME/cryptoKeyVersions/VERSION +export KMS_INTERMEDIATE_KEY_ID=projects/PROJECT_ID/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY_NAME/cryptoKeyVersions/VERSION +``` + +#### Azure KMS + +```shell +export KMS_TYPE=azurekms +export ROOT_KEY_ID=azurekms:name=root-key;vault=fulcio-keys +export KMS_INTERMEDIATE_KEY_ID=azurekms:name=leaf-key;vault=fulcio-keys +export LEAF_KEY_ID=azurekms:name=leaf-key;vault=fulcio-keys +export AZURE_TENANT_ID=83j229-83j229-83j229-83j229-83j229 +``` + +#### HashiCorp Vault KMS + +```shell +export KMS_TYPE=hashivault +export ROOT_KEY_ID=transit/keys/root-key +export KMS_INTERMEDIATE_KEY_ID=transit/keys/intermediate-key +export LEAF_KEY_ID=transit/keys/leaf-key +export VAULT_ADDR=http://vault:8200 +export VAULT_TOKEN=token +``` + +### Example Usage + +Example with AWS KMS: + +```bash +fulcio-certificate-maker create \ + --kms-type awskms \ + --aws-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: + +```bash +fulcio-certificate-maker create \ + --kms-type azurekms \ + --azure-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 \ + --intermediate-cert intermediate.pem +``` + +Example with GCP KMS: + +```bash +fulcio-certificate-maker create \ + --kms-type gcpkms \ + --gcp-credentials-file ~/.config/gcloud/application_default_credentials.json \ + --root-key-id projects//locations//keyRings//cryptoKeys/fulcio-key1/cryptoKeyVersions/ \ + --intermediate-key-id projects//locations//keyRings//cryptoKeys/fulcio-key1/cryptoKeyVersions/ \ + --leaf-key-id projects//locations//keyRings//cryptoKeys/fulcio-key1/cryptoKeyVersions/ \ + --root-cert root.pem \ + --leaf-cert leaf.pem \ + --intermediate-cert intermediate.pem +``` + +Example with HashiCorp Vault KMS: + +```bash +fulcio-certificate-maker create \ + --kms-type hashivault \ + --vault-address http://vault:8200 \ + --vault-token token \ + --root-key-id "transit/keys/root-key" \ + --leaf-key-id "transit/keys/leaf-key" \ + --intermediate-key-id "transit/keys/intermediate-key" \ + --root-cert root.pem \ + --leaf-cert leaf.pem \ + --intermediate-cert intermediate.pem +```