Skip to main content

Sign container images using SMCTL

DigiCert​​®​​ Software Trust Manager supports native container image signing using SMCTL. You can use the simplified signing workflow to sign OCI container images without installing or configuring third-party signing tools or plugins. This workflow enables container signing directly through SMCTL while keeping the signing key managed by Software Trust Manager.

SMCTL supports the following signature formats:

  • COSE

  • JWS

  • OCI (Cosign-compatible)

Note

To sign a container image, use the smctl sign command with the --simple option to sign a container image without using third-party signing tools or libraries.

Before you begin

Ensure that:

  • SMCTL version 1.7.0 or later is installed and configured.

  • You are authenticated to Software Trust Manager.

  • You have access to a Software Trust Manager key pair that can be used for signing.

  • You have the fully qualified OCI image reference for the container image you want to sign.

Step 1 Identify the container image

Obtain the fully qualified OCI image reference, including the registry, organization, repository, and version.

docker.io/<organization>/<repository>:<version>

For example:

smctl sign --simple \

  --input-uri
docker.io/<organization>/<repository>:<version>

Step 2 Specify a signing key pair

Identify the Software Trust Manager key pair alias that you want to use to sign the container image.

smctl sign --simple \

  --input-uri
docker.io/<organization>/<repository>:<version> \

  --keypair-alias
<STM-keypair-alias> \

Step 3 Specify the signature format and sign the container image

  1. Specify one of the following values for --signature-format:

    - cose — Creates a COSE Sign1 signature.

    - jws — Creates a JWS/Notation signature.

    - oci — Creates a Cosign-compatible OCI signature.

  2. Run the commands. For example:

    smctl sign --simple \

  --input-uri
docker.io/<organization>/<repository>:<version> \

  --keypair-alias
<STM-keypair-alias> \

  --signature-format
<cose|jws|oci>

Additional signing options

SMCTL provides additional options for configuring container signing workflows, including:

Important

The following signing options works only when the signature format is oci (or if the signature format is unspecified, since oci is the default):

  • --embed-certificate

  • --embed-certificate-chain

  •  --oci-annotation

  • --new-bundle-format

  • --upload-tlog

  • --rekor-url

  • --rekor-api-version

  • --rekor-token

  • --rekor-tls-cert

  • --rekor-tls-key

  • --rekor-ca-cert

Command

Description

--embed-certificate

Embed the signing certificate in a Cosign-style signature. Default value is true.

--embed-certificate-chain

Embed the full certificate chain in a Cosign-style signature. Default value is true.

 --input-uri 

OCI image reference to sign.

-k, --keypair-alias

Provide the keypair alias to be used for signing.

--new-bundle-format

Default value is true. The DSSE bundle format is the default behavior. If you want the legacy cosign v2 .sig format, then you need to explicitly pass --new-bundle-format=false.

--new-bundle-format requires Cosign 3.0.0 or later.

   --oci-annotation stringArray

OCI image annotation as key=value pair (cosign-style). You can specify this option multiple times.

--rekor-api-version

Rekor API version to use. (Default value: v1)

--rekor-ca-cert

CA certificate for Rekor TLS verification.

 --rekor-tls-cert

TLS certificate for Rekor client authentication.

--rekor-tls-key

TLS key for Rekor client authentication.

 --rekor-token

Authentication token for Rekor.

 --rekor-url 

Rekor transparency log URL. Default to rekor.sigstore.dev

--signature-format

Signature envelope format: cose (pure COSE Sign1), jws (Notation), or oci (Cosign-compatible). Default value is oci if the flag is omitted entirely.

--upload-tlog 

Upload signature to Rekor transparency log (Cosign-style).

--cose-annotation

the COSE-format equivalent of --oci-annotation (only valid with --signature-format cose)

--jws-metadata

the JWS-format equivalent of --oci-annotation (only valid with --signature-format jws)

--recursive

signs all images in a multi-arch image, cosign-style (only valid with --signature-format oci )

--output-payload

writes the signed payload to a file, equivalent to cosign's --output-payload (only valid with --signature-format oci )

--registry-username

registry authentication credentials

--registry-password

registry authentication credentials

In this section: