Skip to main content

Sign containers with CoSign from Sigstore using PKCS11 library

CoSign is an open-source command line utility used to sign container images. Cosign is designed to enhance the security of container images by providing a simple and efficient way to sign and verify them. It leverages the concept of digital signatures, where the you sign the container image with your private key, and the recipient can verify your signature using the corresponding public key. This process helps prevent man-in-the-middle (MITM) attacks and ensures that the images have not been modified or compromised during distribution.

Follow these instructions to sign directly with CoSign and securely reference your private key stored in Software Trust Manager using our PKCS11 library. Alternatively, Software Trust Manager offers container signing via Docker Notary or Podman.

Tip

Signing with containers with Cosign is only compatible on Linux.

Sigstore

Sigstore allows software developers to securely sign software artifacts such as release files, container images, binaries, bill of material manifests, and more. Signing materials are then stored in a tamper-resistant public log.

Cosign

Cosign supports container signing, verification, and storage in an OCI registry. Cosign aims to make signatures invisible to infrastructure. Cosign works with PKCS#11 to enable DigiCert​​®​​ Software Trust Manager to be used via our PKCS11 (smpkcs11) library.

Prerequisites

Load the virtual token from Cosign

To verify that the DigiCert​​®​​ Software Trust Manager virtual token can be loaded from cosign:

cosign pkcs11-tool list-tokens --module-path </path/of/smpkcs11.so>

Command output:

Listing tokens of PKCS11 module '/home/user/smpkcs11.so'
Token in slot 0
        Label: Virtual PKCS#11 Token
        Manufacturer: DigiCert
        Model: DigiCert PKCS#11
        S/N: SS0123456789

Fetch keypairs

You need access to your keys on your DigiCert​​®​​ Software Trust Manager account to use them for signing.

To fetch all the keys on your DigiCert​​®​​ Software Trust Manager account:

cosign pkcs11-tool list-keys-uris --module-path /path/to/smpkcs11.so --slot-id 0 --pin anything

Command output:

Listing URIs of keys in slot '0' of PKCS11 module '/home/user/smpkcs11.so'
Object 0
        Label: kaiv-static-1
        ID: 30303138663333352d316337302d343162662d386537662d363939643264316261663963
        URI: pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%30%30%31%38%66%33%33%35%2d%31%63%37%30%2d%34%31%62%66%2d%38%65%37%66%2d%36%39%39%64%32%64%31%62%61%66%39%63;object=kaiv-static-1?module-path=/home/user/smpkcs11.so&pin-value=anything
Object 1
        Label: rotchk3
        ID: 30303839633736392d363836632d343566612d393138362d336239633935393535343036
        URI: pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%30%30%38%39%63%37%36%39%2d%36%38%36%63%2d%34%35%66%61%2d%39%31%38%36%2d%33%62%39%63%39%35%39%35%35%34%30%36;object=rotchk3?module-path=/home/user/smpkcs11.so&pin-value=anything
Object 2
        Label: kpGrp
        ID: 30313034306236622d363265372d343464302d616536382d376237643139343436656436
        URI: pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%30%31%30%34%30%62%36%62%2d%36%32%65%37%2d%34%34%64%30%2d%61%65%36%38%2d%37%62%37%64%31%39%34%34%36%65%64%36;object=kpGrp?module-path=/home/user/smpkcs11.so&pin-value=anything
Object 3
        Label: ECDSASystemUserKP5
        ID: 30313232306135312d313538642d346135392d623839622d653063613339663662306564
        URI: pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%30%31%32%32%30%61%35%31%2d%31%35%38%64%2d%34%61%35%39%2d%62%38%39%62%2d%65%30%63%61%33%39%66%36%62%30%65%64;object=ECDSASystemUserKP5?module-path=/home/user/smpkcs11.so&pin-value=anything

Sign

To sign a container image:

cosign sign --key "<key path>" localhost:5000/hello-world

Command sample:

cosign sign --key "pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%37%35%62%63%39%38%32%35%2d%65%39%32%33%2d%34%63%34%32%2d%39%65%30%33%2d%33%39%62%64%38%30%38%66%32%62%66%32;object=anshuman_rsa_3072_1?module-path=/home/user/smpkcs11.so&pin-value=anything" localhost:5000/hello-world

Command output:

Pushing signature to: localhost:5000/hello-world

Verify signature

To verify signed container image:

cosign verify --key "<key path>" localhost:5000/hello-world

Command sample:

cosign verify --key "pkcs11:token=Virtual%20PKCS%2311%20Token;slot-id=0;id=%37%35%62%63%39%38%32%35%2d%65%39%32%33%2d%34%63%34%32%2d%39%65%30%33%2d%33%39%62%64%38%30%38%66%32%62%66%32;object=john_doe_rsa_3072_1?module-path=/home/user/smpkcs11.so&pin-value=anything" localhost:5000/hello-world

Command output:

Verification for localhost:5000/hello-world:latest --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

[{"critical":{"identity":{"docker-reference":"localhost:5000/hello-world"},"image":{"docker-manifest-digest":"sha256:28a1207f180f1062559d6140e60de73b3ef1bb1e013fe84d7b183597cc134c7a"},"type":"cosign container image signature"},"optional":{"Subject":""}}]

Related articles

Troubleshooting

: