Venafi CodeSign Protect Signature and Verification Plugin for the Notation CLI.

This is a plugin that aims to be compliant with the plugin spec.

Signature Format Compatibility

Type	Supported
JWS	✔
COSE Sign1	✔

Plugin Spec Compatibility

Capability	Compatibility
keySpec	RSA-2048, RSA-3072, RSA-4096, EC-256, EC-384, EC-521
hashAlgorithm	SHA-256
signingAlgorithm	RSASSA-PSS-SHA-256, ECDSA-SHA-256
pluginCapability	SIGNATURE_GENERATOR.ENVELOPE, SIGNATURE_VERIFIER.TRUSTED_IDENTITY, SIGNATURE_VERIFIER.REVOCATION_CHECK
signatureEnvelopeType	application/jose+json (JWS), application/cose (COSE)
extendedAttributes	com.venafi.notation.plugin.x5u (only generated with TPP 23.1+ for experimental identity validation support)
signingScheme	notary.x509

Getting Started:

The following summarizes the steps to configure the Venafi CodeSign Protect notation plugin and sign and verify a container image. The following steps are based off of the Notation hello-signing example.

• This plugin leverages the Venafi vSign SDK, which means you'll need to meet the pre-requisites as well as customize the config.ini in terms of tpp_url, access_token, and tpp_project.
• Install notation CLI. Version v1.0.1 has been tested. Note that make install creates the plugin directory structure based on a MacOS environment. Update the Makefile based on your OS. It then copies the plugin to the appropriate location based on the notation plugin directory structure spec.

Installation

Install the notation-venafi-csp plugin for remote signing and verification, depending on your requirements:

Windows PowerShell

• First, ensure you are using an administrative shell
• Run the following command:

  Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://github.com/venafi/notation-venafi-csp/install/install.ps1'))
  

MacOS and Linux

• Run the following command:

  curl -sfL https://github.com/venafi/notation-venafi-csp/install/install.sh | sh -
  

Build and Install from Source

git clone https://github.com/venafi/notation-venafi-csp.git
cd notation-venafi-csp
make build
make install

• Install Docker Desktop for local docker operations
• Create and run an OCI-compatible registry on your development system using an open source registry implementation.

  docker run -d -p 5001:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true --name registry registry
  

• Build and Push the net-monitor software

docker build -t localhost:5001/net-monitor:v1 https://github.com/wabbit-networks/net-monitor.git#main
docker push localhost:5001/net-monitor:v1

• Get the digest value of localhost:5001/net-monitor:v1:

docker inspect localhost:5001/net-monitor:v1 -f '{{ .Id }}'
sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a

• List the image, and any associated signatures. At this point there shouldn't be any signatures

IMAGE=localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
notation ls $IMAGE

• Create a trust policy In order to verify the container image, you need to configure the trust policy to specify trusted identities which sign the artifacts, and level of signature verification to use. Follow the Manage trust policies guide to understand and implement Notation trust policy.

{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "wabbit-networks-images",
            "registryScopes": [ "*" ],
            "signatureVerification": {
                "level" : "strict" 
            },
            "trustStores": [ "ca:wabbit-networks.io" ],
            "trustedIdentities": [
                "*"
            ]
        }
    ]
}

As an example, you can use notation policy import to import the trust policy configuration from the above JSON file:

notation policy import ./trustpolicy.json

Remotely sign with Venafi CodeSign Protect

• Obtain certificate

You should use the certificate label that matches the Venafi CodeSign Protect environment obtained using pkcs11config:

pkcs11config getcertificate <...>

• Add the Key Id to the keys and certs

notation key add --default "vsign-rsa2048-cert" --plugin venafi-csp --id "vsign-rsa2048-cert" --plugin-config "config"="/path/to/vsign/config.ini"
notation certificate add --type ca --store example.com /path/to/chain.crt

Note: A best practice for Key Id naming would be to use the certificate label that matches the Venafi CodeSign Protect environment

• List the keys and certs to confirm

notation key list
notatation certificate list

• Sign the container image with default signature manifest as image

notation sign --key "vsign-rsa2048-cert" $IMAGE

• Confirm that there is one signature

notation ls $IMAGE
localhost:5001/net-monitor@sha256:073b75987e95b89f187a89809f08a32033972bb63cda279db8a9ca16b7ff555a
└── application/vnd.cncf.notary.v2.signature
    └── sha256:ba3a68a28648ba18c51a479145fca60d96b43dc96c6ab22f412c89ac56a9038b

• Verify the container image signature

notation verify $IMAGE

Signature verification succeeded for sha256:73b3c3f2200bc6c161663b88b1fde3b3ed486518d6b6453fccdfdbbaefa09c7b

Note: Verification does perform additional checks such as verifying the revocation status of the code signing certificate, as well as validating that the certificate does exist in CodeSign Protec via PKS for identity validation purposes when using TPP 23.1+.