Install and manage notation plugins

Plugins for notation provide functionality and integration with key stores and signing services. For example:

• The notation-azure-kv plugin allows you to sign a Notation-generated payload with a private key in Azure Key Vault.
• The AWS Signer plugin for Notation lets you sign and verify images using Notation with keys and certificates managed by AWS Signer, a signing service.
• The Venafi CodeSign Protect plugin for Notation enables the secure signing and verification of images using the Venafi CodeSign Protect platform.

Install a plugin

To install a plugin, download the plugin binary, create a {plugin-name} directory in {NOTATION_LIBEXEC}/plugins/, and add the plugin binary to that directory. Alternatively, if you are using an application that bundles a plugin and the notation binary together, such as AWS Signer, see the installation instructions from the vendor.

The following example downloads and installs version 0.6.0 of notation-azure-kv plugin for on macOS with Apple Silicon using the default location for the Notation installation.

curl -Lo notation-azure-kv_0.6.0_darwin_arm64.tar.gz "https://github.com/Azure/notation-azure-kv/releases/download/v0.6.0/notation-azure-kv_0.6.0_darwin_arm64.tar.gz"
mkdir -p ~/Library/Application\ Support/notation/plugins/azure-kv
tar xvzf notation-azure-kv_0.6.0_darwin_arm64.tar.gz -C ~/Library/Application\ Support/notation/plugins/azure-kv notation-azure-kv

To confirm you plugin is installed, run notation plugin list. For example:

notation plugin list

Confirm the plugin is listed in the output. For example:

$ notation plugin list
NAME                                 DESCRIPTION                                           VERSION          CAPABILITIES                                                             ERROR
azure-kv                             Sign artifacts with keys in Azure Key Vault           0.6.0            [SIGNATURE_GENERATOR.RAW]                                                                     <nil>
com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation                        1.0.290          [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>
venafi-csp                           Sign artifacts with keys in Venafi CodeSign Protect   0.2.0-release    [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>

Uninstall a plugin

To remove a plugin, delete the entire {NOTATION_LIBEXEC}/plugins/{plugin-name}/ directory.

To confirm your plugin is uninstalled, run notation plugin list. For example:

notation plugin list

Plugin naming structure

The notation CLI strictly follows the Notary Project specification for plugins. This includes the naming structure for the plugin binary and the plugin directory. All plugins must be named notation-{plugin-name} and placed in the {NOTATION_LIBEXEC}/plugins/{plugin-name}/ directory. Also, you can’t modify the filename of the plugin binary from the tar.gz file when installing a plugin.

For example, the full path to the notation-azure-kv plugin is {NOTATION_LIBEXEC}/plugins/azure-kv/notation-azure-kv.

If the plugin name or plugin directory does not match the naming structure or the plugin name is altered, notation will not recognize the plugin.

Security best practices for plugins

Plugins are binaries that run on your host and can receive sensitive information from notation such as signatures, private keys, and payload data. As a result, it is strongly recommended that you follow these security best practices when using plugins:

• Ensure that you only download plugins and their checksums from known, trusted sources
• When available, use checksum verification or signature verification to confirm the plugin binary is not corrupted

Available plugins

The following plugins are currently available for notation:

• AWS Signer plugin for Notation. For more details on using this plugin for sign and verify images, see Notation with AWS Signer
• notation-azure-kv. For more details on using this plugin, see Sign a Notation-generated payload with a certificate in Azure Key Vault.
• Venafi CodeSign Protect plugin for Notation that leverages the Venafi CodeSign Protect platform. For more details on using this plugin, see the usage instructions.