Cosign KMS plugin

The DigiCert® Software Trust Manager Cosign KMS plugin enables you to sign and verify OCI container images, software bills of materials (SBOMs), attestations, and arbitrary blobs using Cosign with signing keys securely managed in DigiCert® Software Trust Manager. Private keys never leave DigiCert's cloud-based hardware security modules (HSMs), ensuring that all cryptographic operations are performed securely within the Software Trust Manager.

The plugin connects Cosign to the DigiCert® Software Trust Manager API through the standard Sigstore KMS plugin protocol. Distributed as a single, self-contained Go binary, it requires no PKCS#11 shared library or CGO dependencies and runs on Windows, Linux, and macOS, including ARM64.

Important

The Cosign KMS plugin feature is supported with Cosign version 3.x and later.

The plugin supports:

Signing and verifying using digicert:// key references — no PKCS#11 shared library required.
RSA and EC key algorithms
OCI container images, SBOMs, attestations, and blob signing
Cross-platform support for Windows, Linux, and macOS, including ARM64 architectures

Overview

Operation	Cosign command	Software Trust Manager operation
Create a keypair	`cosign generate-key-pair --kms digicert://...`	Generates a new RSA/ECDSA keypair in Software Trust Manager
Get public key	(automatic, used by sign/verify)	Reads the keypair's certificate or raw public key
Sign	`cosign sign / sign-blob / attest`	Signs a digest on the Software Trust Manager cloud HSM
Verify	`cosign verify / verify-blob / verify-attestation`	Verifies locally, or via the Software Trust Manager verify API

Before you begin

Requirement	Notes
Cosign	Cosign v3.x and later release.
Docker or OCI-compatible client	Required to build/push images that will be signed.
OCI registry	Any OCI 1.1+ registry -- Docker Hub, AWS ECR, Azure ACR, GCR, GitHub Packages, or self-hosted.
DigiCert ONE with Software Trust Manager access	API key Client authentication certificate
A keypair	Provision one in the Software Trust Manager portal ahead of time, or generate one on demand with `cosign generate-key-pair` or generate keypair using SMCTL command. . Retrieve existing aliases with `smctl keypair list`.

Cosign KMS digicert plugin supported algorithms

Supported key types

Algorithm	Key sizes / curves
RSA	2048, 3072, 4096 bit (PKCS#1 v1.5)
ECDSA	P-256, P-384, P-521

Ed25519 and post-quantum algorithms (ML-DSA, SLH-DSA) are not supported.

Note

You do not need to specify a hash algorithm. The plugin automatically selects the appropriate algorithm based on the key type and size, ensuring compatibility with cosign and Go's standard cryptographic libraries.

Key type	Key size / curve	Hash used for signing
RSA	2048 / 3072 / 4096	SHA-256 (fixed, regardless of key size)
ECDSA	P-256	SHA-256
ECDSA	P-384	SHA-384
ECDSA	P-521	SHA-512

Note

The cosign KMS plugin protocol's public-key method returns only a raw crypto.PublicKey, not a certificate chain. If you need certificate-based verification, export the certificate separately from Software Trust Manager (e.g. via smctl keypair export-cert) and pass it explicitly with --cert/--cert-chain.

Install cosign KMS plugin

Download cosign KMS plugin
1. In the Software Trust menu, go to Resources > Client tool repository.
2. Select the Client tools tab.
3. Select the download icon next to Cosign KMS plugin.
  Download the appropriate binary for your platform.
  Platform
  Binary name
  Linux 64-bit / ARM64
  sigstore-kms-digicert
  macOS (Universal)
  sigstore-kms-digicert
  Windows 64-bit/ARM64
  sigstore-kms-digicert.exe
Place the binary on PATH
Cosign has no plugin install subcommand. Cosign's KMS plugin protocol resolves a key reference scheme (the part before ://, e.g. digicert) to a binary named sigstore-kms-<scheme> and looks it up on the process PATH. Place the downloaded binary somewhere on PATH.
Example 1. Linux / macOS
```
chmod +x sigstore-kms-digicert
sudo mv sigstore-kms-digicert /usr/local/bin/
```
Example 2. Windows (PowerShell)
```
Move-Item .\sigstore-kms-digicert.exe "C:\Program Files\DigiCert\sigstore-kms-digicert.exe"
$env:PATH += ";C:\Program Files\DigiCert"
```
Verify the installation
Confirm the binary is discoverable and the correct version is installed:
```
sigstore-kms-digicert version
```
To validate the end-to-end configuration, generate a test keypair or perform a sign-and-verify round trip using an existing key.

Platform	Binary name
Linux 64-bit / ARM64	`sigstore-kms-digicert`
macOS (Universal)	`sigstore-kms-digicert`
Windows 64-bit/ARM64	`sigstore-kms-digicert.exe`

Environment variables

Set the required environment variables before running any commands.

(Optional) Logging

Variable	Description	Default
`SM_HOME`	Base directory for config and logs	`~/.signingmanager`
`SM_LOG_LEVEL`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`	`info`
`SM_LOG_DIR`	Directory for log files	`$SM_HOME/logs`
`SM_LOG_OUTPUT`	Log destination: `file`, `stdout`, `stderr`, `discard`	`file`

(Optional) Authentication

Variable	Description	Default
`SM_DYNAMIC_AUTH`	Enable UCM (DigiCert ONE Clients) dynamic authentication	`false`

Quick Setup

Linux / macOS

export SM_HOST="https://clientauth.one.digicert.com"
export SM_API_KEY="YOUR_API_KEY"
export SM_CLIENT_CERT_FILE="/etc/digicert/client.p12"
export SM_CLIENT_CERT_PASSWORD="YOUR_CERT_PASSWORD"

Windows (PowerShell)

$env:SM_HOST                  = "https://clientauth.one.digicert.com"
$env:SM_API_KEY               = "YOUR_API_KEY"
$env:SM_CLIENT_CERT_FILE      = "C:\DigiCert\client.p12"
$env:SM_CLIENT_CERT_PASSWORD  = "YOUR_CERT_PASSWORD"

Key reference URI and key generation

URI Format

All cosign commands that accept --key or --kms reference an Software Trust Manager keypair using a digicert:// URI:

digicert://alias/<alias-name>
digicert://id/<keypair-uuid>
digicert://<host>/alias/<alias-name>
digicert://<host>/id/<keypair-uuid>

- alias/<name> looks up the keypair by its Software Trust Manager alias (see smctl keypair list).

- id/<uuid>looks up the keypair by its Software Trust Manager keypair ID.

- The optional <host> segment overrides SM_HOST for that single command -- useful for multi-region Software Trust Manager deployments without changing the environment.

Examples:

cosign sign --key "digicert://alias/my-cosign-key" <IMAGE DIGEST>
cosign sign --key "digicert://id/8a3b1c2d-4e5f-6789-abcd-ef0123456789" <IMAGE DIGEST>
cosign sign --key "digicert://stm-one.nl.digicert.com/alias/my-cosign-key" <IMAGE DIGEST>

Generate a new keypair

Cosign’s generate-key-pair command does not provide a mechanism for passing algorithm, key size, or curve parameters to a KMS plugin. To support these options, the plugin accepts them as query parameters in the key URI instead.

digicert://alias/<name>?key_alg=<RSA|ECDSA>&key_size=<bits>&curve=<P256|P384|P521>

Query parameter	Applies to	Values	Default
`key_alg`	both	`RSA` or `ECDSA`c	`RSA`
`key_size`	RSA only	`2048`, `3072`, `4096`	`3072`
`curve`	ECDSA only	`P256`, `P384`, `P521`	`P256`

Optionally, a certificate can be generated for the new keypair at the same time:

Query parameter	Description	Default
`cert_profile_id`	Certificate profile UUID. Specify this parameter to generate a certificate for the key.	(none -- no cert generated)
`cert_alias`	Alias for the generated certificate.	`<keypair-alias>_cosign`
`set_as_default`	Whether to set the newly generated certificate as the default certificate for the keypair.	`true`

Examples:

# Default: RSA-3072
cosign generate-key-pair --kms "digicert://alias/my-cosign-key"

# RSA-4096
cosign generate-key-pair --kms "digicert://alias/my-rsa-key?key_alg=rsa&key_size=4096"

# ECDSA P-384
cosign generate-key-pair --kms "digicert://alias/my-ecdsa-key?key_alg=ecdsa&curve=P384"

# ECDSA P-256 with an accompanying certificate
cosign generate-key-pair --kms "digicert://alias/my-ecdsa-key?key_alg=ecdsa&curve=P256&cert_profile_id=<PROFILE_UUID>"

Note

Always quote the --kms/--key value. Unquoted & and ? characters have special meaning in both POSIX shells and PowerShell.

The plugin supports generating only RSA and ECDSA keys. Because cosign does not support Ed25519 or post-quantum algorithms (ML-DSA and SLH-DSA), requests for these key types are rejected with a clear error message.

In this section: