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, run the notation plugin install command to directly install a plugin either from a URL or from the host file system. This will create a {plugin-name} directory in {NOTATION_LIBEXEC}/plugins/ if the directory does not exist. The supported plugin file formats are .zip, .tar.gz and single plugin executable file. 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.
Warning
Before creating the{plugin-name} directory, confirm you are using a name that follows the naming structure for plugins. Plugins that do not follow the naming structure will not be recognized by notation.
Usage
Install a plugin from file system:
notation plugin install --file <file_path>
Install a plugin from URL:
notation plugin install --sha256sum <digest> --url <HTTPS_URL>
plugin
The following examples show how to install each plugin on a Linux AMD64 machine. To install a plugin on other operating systems and architectures, please get the URL or plugin binary file from plugin vendors' website.Install Notation AWS Signer plugin
To find out more about the AWS Signer plugin, please refer to their official documentation.
Install from file system
wget https://d2hvyiie56hcat.cloudfront.net/linux/amd64/plugin/latest/notation-aws-signer-plugin.zip
notation plugin install --file notation-aws-signer-plugin.zip
Successfully installed plugin com.amazonaws.signer.notation.plugin, version 1.0.298
Upon successful execution, the plugin is copied to Notation’s plugin directory.
Install Notation Azure Key Vault Plugin (v1.0.2)
To find out more about the Azure Key Vault Plugin, please refer to this GitHub repository.
Install from URL:
notation plugin install --url https://github.com/Azure/notation-azure-kv/releases/download/v1.0.2/notation-azure-kv_1.0.2_linux_amd64.tar.gz --sha256sum f2b2e131a435b6a9742c202237b9aceda81859e6d4bd6242c2568ba556cee20e
Downloading plugin from https://github.com/Azure/notation-azure-kv/releases/download/v1.0.2/notation-azure-kv_1.0.2_linux_amd64.tar.gz
Download completed
Successfully installed plugin azure-kv, version 1.0.2
Install from local file:
notation plugin install --file notation-azure-kv_1.0.2_linux_amd64.tar.gz
Successfully installed plugin azure-kv, version 1.0.2
Install Notation Venafi Plugin (v0.3.0)
To find out more about the Venafi Plugin, please refer to this GitHub repository.
Install from URL:
notation plugin install --url https://github.com/Venafi/notation-venafi-csp/releases/download/v0.3.0/notation-venafi-csp-linux-amd64.tar.gz --sha256sum 03771794643f18c286b6db3a25a4d0b8e7c401e685b1e95a19f03c9356344f5a
Successfully installed plugin venafi-csp, version 0.3.0-release
Install from local file:
notation plugin install --file notation-venafi-csp-linux-amd64.tar.gz
Successfully installed plugin venafi-csp, version 0.3.0-release
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 1.0.2 [SIGNATURE_GENERATOR.RAW] <nil>
com.amazonaws.signer.notation.plugin AWS Signer plugin for Notation 1.0.298 [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>
venafi-csp Sign artifacts with keys in Venafi CodeSign Protect 0.3.0-release [SIGNATURE_GENERATOR.ENVELOPE SIGNATURE_VERIFIER.TRUSTED_IDENTITY SIGNATURE_VERIFIER.REVOCATION_CHECK] <nil>
Uninstall a plugin
To uninstall a plugin, use notation plugin uninstall.
notation plugin uninstall <plugin_name>
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.