docs: adds readme for fulcio-certificate-maker.

Signed-off-by: ianhundere <138915+ianhundere@users.noreply.github.com>
sigstore · Jan 14, 2025 · c4290e9 · c4290e9
1 parent 8bec25f
commit c4290e9
Show file tree

Hide file tree

Showing 2 changed files with 181 additions and 0 deletions.
diff --git 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-<os>.sig`) using the artifact signing key:

diff --git a/docs/certificate-maker.md 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/<project_id>/locations/<location>/keyRings/<keyring>/cryptoKeys/fulcio-key1/cryptoKeyVersions/<version> \
+  --intermediate-key-id projects/<project_id>/locations/<location>/keyRings/<keyring>/cryptoKeys/fulcio-key1/cryptoKeyVersions/<version> \
+  --leaf-key-id projects/<project_id>/locations/<location>/keyRings/<keyring>/cryptoKeys/fulcio-key1/cryptoKeyVersions/<version> \
+  --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
+```