SignPath

Crypto Providers  ❯   Notation Plugin

General instructions

notation is a command line tool to creating and verifying signatures of artifacts stored in an OCI registry. It is most commonly used for container images. See the section on signing container images with notation for more details.

Installation

Linux

The notation plugin can be installed using the following commands:

# download and extract the plugin binary
curl -s https://download.signpath.io/cryptoproviders/notation-plugin/6-latest/linux/x64/notation-signpath.tar.gz \
  | tar -C /tmp -xzf - notation-signpath

# install the plugin
notation plugin install --file /tmp/notation-signpath

# clean up
rm /tmp/notation-signpath

Verifying the notation-signpath signature

You can verify the signature of the notation-signpath executable using our public GPG key by also extracting the detached signature file notation-signpath.asc from the .tar.gz

curl -s ... | tar -C /tmp -xzf - notation-signpath notation-signpath.asc
gpg --verify /tmp/notation-signpath.asc /tmp/notation-signpath

Windows

The notation plugin can be installed using the following commands:

# download an extract the plugin binary
Invoke-WebRequest "https://download.signpath.io/cryptoproviders/notation-plugin/6-latest/windows/x64/notation-signpath.zip" `
  -OutFile "${env:TEMP}\notation-signpath.zip"
Expand-Archive -DestinationPath "${env:TEMP}\notation-signpath" "${env:TEMP}\notation-signpath.zip"

# install the plugin
notation plugin install --file "${env:TEMP}\notation-signpath\notation-signpath.exe"

# clean up
Remove-Item -Recurse -Confirm:$false ${env:TEMP}\notation-signpath*

Verifying the notation-signpath.exe signature

You can verify the signature of the notation-signpath.exe executable by calling

Get-AuthenticodeSignature "${env:TEMP}\notation-signpath\notation-signpath.exe"

Configuration

See SignPath Crypto Providers for general configuration options.

Usage

  • The available configuration values can also be passed in via the command line arguments --plugin-config "Key=<Value>".
  • The notation key id is comprised of the project slug and signing policy slug, separated by a forward slash, e.g. "MyProject/release-signing"
export IMAGE_DIGEST=`docker inspect --format='{{index .RepoDigests 0}}' "$FQN:$TAG"`

export SIGNPATH_API_TOKEN=...your-api-key...
notation sign \
  --signature-format cose \
  --id "$SIGNPATH_PROJECT_SLUG/$SIGNPATH_SIGNING_POLICY_SLUG" \
  --plugin signpath \
  --plugin-config "OrganizationId=$SIGNPATH_ORGANIZATION_ID" \
  $IMAGE_DIGEST

Image references

An image reference consists of the following parts:

  • Optionally, the registry host and port, e.g. docker.io or registry.mycompany.com:3000 - while the image is only available locally, this should be omitted
  • The namespace and/or repository, e.g. jetbrains/teamcity-server
  • The $tag identifying the version, e.g. latest

For images hosted on Docker Hub, the image reference is docker.io/$namespace/$repository:$tag, e.g. docker.io/jetbrains/teamcity-server:latest.

If you are using your own registry, specify the value you would use for Docker CLI commands, e.g. registry.mycompany.com/myrepo/myimage:latest.