Notary Project | A set of specifications and tools intended to provide a cross-industry standard for securing software supply chains. – Notary Project

Blog: Ratify Joins the Notary Project - Strengthening Software Supply Chain Security Together!

Mon, 02 Jun 2025 00:00:00 +0000

We’re excited to announce that Ratify has officially joined the Notary Project as a subproject after the vote passed in the community! 🎉 This marks a significant step forward in our shared mission to deliver secure, transparent, and trusted software supply chain for the cloud-native ecosystem.

The Notary Project is building a set of specifications and reference implementations to secure the integrity of container images and other OCI artifacts. With Ratify’s addition, we expand our surface to policy-based verification and extensibility, helping organizations validate signatures, SBOM, vulnerability scanning report, and other security metadata of container images in CI/CD and before deploying to Kubernetes.

Why Ratify?

Ratify is an extensible verification framework for container images and other artifacts that can examine and author policies to audit existing resources in Kubernetes and CI/CD. Ratify can use and manage any number of custom verifiers for image metadata like signatures, SBOMs, vulnerability scan reports, and so on.

Ratify has been widely adopted by cloud providers and organizations to enforce verification of OCI artifacts across environments. As part of the Notary Project, Ratify brings:

An end-to-end policy-driven verification capabilities
Extensible plugin support for different verifiers (e.g., Notation, Cosign, SBOM, vulnerability report, custom plugins) and various cloud providers (AWS, Azure, Alibaba Cloud, Venafi, etc.)
Enforcement at admission control when users deploying an untrusted application in Kubernetes
Cross-tool ecosystem support for Gatekeeper, Trivy, etc.

These Ratify repositories have been transferred to Notary Project organization:

What This Means for the Community

By welcoming Ratify as an official subproject, the Notary Project now offers a broader and more opinionated solution stack for securing software supply chain:

Notation enables signing of OCI artifacts in CI/CD pipelines.
Ratify enforces signature and other supply chain metadata verification policies in container runtime, Kubernetes, and CI/CD pipelines.

We also want to thank the contributors from Microsoft, Alibaba Cloud, and the wider community for their work on Ratify—and for their continued commitment to open governance by donating the project to Notary Project.

What Should Ratify Users Know

For Ratify users, the Helm repo of Ratify has been changed from https://ratify-project.github.io/ratify to https://notaryproject.github.io/ratify. Please refer to Ratify documentation to use the latest repo.

What’s Next?

The Ratify maintainers has been collaborating with Notary Project maintainers to align roadmaps, documentation, and release processes. You can expect:

Continued development under the Notary Project GitHub org
Unified communication channels in Notary Project including commmunity meetings, Slack channel, social media, etc.
Closer integration between Ratify and Notation.

Please join us in welcoming Ratify to the community! 🙌

Blog: Announcing Notation v2.0.0-alpha.1 to enable signing and verification of any arbitrary blob files!

Tue, 18 Mar 2025 00:00:00 +0000

We are thrilled to announce the release of Notation v2.0.0-alpha.1, marking a significant milestone in our commitment to enhancing artifact signing and verification. This alpha release also introduces several improvements designed to provide a more versatile and efficient experience for our users.

Key Highlights

Breaking Changes

In notation v1.x, the notation sign command defaults to storing signatures using the OCI referrers tag schema for maximum compatibility. As of this release, the default behavior has changed to use the OCI referrers API since most of the popular registries are compliant with OCI v1.1. However, users can still opt for the referrers tag schema using --force-referrers-tag true if needed.

Expanded support for signing any arbitrary blob files

In addition to container images and OCI artifacts, Notation now enables signing and verification of arbitrary blob files. This enhancement broadens the scope of artifacts you can securely manage, offering greater flexibility in your workflows. The new notation blob command, along with its subcommands (sign, verify, policy, and inspect), facilitates these operations. It enables users to sign and verify arbitrary files such as SBOMs, GitHub release assets, tarballs, and other archive files.

Compliant with OCI v1.1 Standard

Aligning with the latest OCI specifications v1.1, Notation v2.0.0-alpha.1 adopts the OCI Referrers API for storing signatures by default. This shift ensures seamless integration with OCI v1.1-compliant registries, enhancing compatibility, portability, and adherence to industry standards. Unlike traditional method of storing signature separately as an additional tag sha-xxx using Referrers Tag Schema, referrers API allow signatures to be linked to the signed artifact in the registry. The Referrers API also provides a structured way to query signatures (and other related metadata) for a given artifact. Instead of listing all blobs in a registry, tools can directly fetch only the relevant signatures using the referrers API, improving signing and verification efficiency.

For registries requiring the previous referrers tag schema, users can still opt-in using the --force-referrers-tag flag during the signing process. Notation will fallback to Referrers Tag Schema if the registry doesn’t support Referrers API.

The Notary Project signature is now a referrer of the subject image signed by notation. Refer to this conceptual doc for more details.

See a sample signature using the Referrers API below:

$ notation list ghcr.io/ratify-project/ratify@sha256:5b7efcef535eff574e064b2c0682b8a86abbeff03569a7ec78e9110fff1d8730
ghcr.io/ratify-project/ratify@sha256:5b7efcef535eff574e064b2c0682b8a86abbeff03569a7ec78e9110fff1d8730
└── application/vnd.cncf.notary.signature
└── sha256:d3c2a0b8a30aec45558f97da8577d633e5cc09bd0bf8c622896c890bf7828752

Notary Project signature manifest:

{
schemaVersion: 2,
mediaType: "application/vnd.oci.image.manifest.v1+json",
config: {
mediaType: "application/vnd.cncf.notary.signature",
digest: "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
size: 2,
},
layers: [
{
mediaType: "application/cose",
digest: "sha256:a9dfe9f9a8c19c164642630454e0e1bf2ec0df9e385e8f4be2dda5ee322a2cb7",
size: 2378,
},
],
subject: {
mediaType: "application/vnd.oci.image.index.v1+json",
digest: "sha256:5b7efcef535eff574e064b2c0682b8a86abbeff03569a7ec78e9110fff1d8730",
size: 2385,
},
annotations: {
"io.cncf.notary.x509chain.thumbprint#S256": "[\"2d71bdf96b97ee0189350a583164b7f278a9fcbb1908bc1de115e6f70d860014\"]",
"org.opencontainers.image.created": "2025-01-30T23:39:00Z",
},
}

Delta CRL Support

To optimize security and performance, this release introduces support for Delta Certificate Revocation Lists (CRLs). Delta CRLs allow Notation to process only the changes since the last CRL update, resulting in faster and more efficient revocation checks. This enhancement reduces bandwidth usage and accelerates the verification process, ensuring up-to-date validation of certificates.

Getting Started with Notation v2.0.0-alpha.1

We encourage you to explore these new features and enhancements by downloading Notation v2.0.0-alpha.1 from our GitHub releases page. You can also follow the installation guidance for detailed instruction. As this is an alpha release, we welcome your feedback to help us refine and improve the maturity. Please report any issues or suggestions on our GitHub issues page.

Thank you for your continued support and contributions to the Notary Project. Together, we’re advancing the security and integrity of software supply chains.

Join us at KubeCon EU in London

Join two sessions at KubeCon EU in London to explore the challenges, lessons learned, and benefits of using the Notary Project. Dive deep into its mission and strategy, security audit, new use cases, and roadmap.

Notary Project: The Key To Secure Software Supply Chain - Yi Zha, Microsoft & Guillaume Gill, OrangeLogic: April 4, 2025 13:45 - 14:15 BST, ICC Capital Suite 14-16, Level 3
Project Lightning Talk: Notary Project: Securing Binary Artifacts with Fine-grained Control - Yi Zha, Maintainer: April 1, 2025 10:13 - 10:18 BST, Platinum Suite, Level 3

Meet the Notary Project maintainers and ask us anything at our kiosk (18A) located at Level 1, Hall Entrance N8-N9. We’ll be there every afternoon from April 2 to April 4!

Blog: Notary Project Completes Its Second Audit!

Tue, 21 Jan 2025 00:00:00 +0000

This blog post was original published on OSTIF blog by Helen Woeste, Communications Manager, the Open Source Technology Improvement Fund.

OSTIF is proud to share the results of our second security audit of Notary Project. You can read the Audit Report HERE. Notary Project is “a set of specifications and tools intended to provide a cross-industry standard for securing software supply chains by using authentic container images and other OCI artifacts.” With the help of Quarkslab and the Cloud Native Computing Foundation (CNCF), this project continues to provide users with trusted software supply chain management.

Audit Process

This audit of Notary Project was specifically scoped around two new cryptographic features.
The audit team, Quarkslab, was chosen for their practical cryptography experience to work on this engagement.
The audit report presents how Quarkslab installed and performed discovery of Notary Project tooling Notation, reviewed the code structure and quality, and analyzed the timestamping and certificate revocation.
The audit team also created multiple figures to help illustrate Notation with examples of overall project functionality, flow of certificate chain verification, and a global overview of the CRL verification.

Audit Results

11 findings with Security Impact and Recommended Fixes
- 1 Medium, 1 Low, 9 Informational
- 2 CVEs issued for audit findings:
  - CVE-2024-56138: Notation-go timestamp signature generation lacks certificate revocation check.
  - CVE-2024-51491: Notation-go process crash during CRL-based revocation check on OS using separate mount point for temp directory.
Review and Recommendations for 2 New Cryptographic Features
- Timestamping Support
  - Time-Stamp Protocol Compliance
  - Time Stamp Analysis in Notation
- Revocation Checking with Certificate Revocation List
  - Certificate Revocation List Compliance
  - CRL Analysis in Notation
Future Security Work Recommendations

This was Notary Project’s third security audit and second audit in partnership with OSTIF.
Practicing mature security practices, the three audits were all undertaken after implementation of new features with security impact.
Notary Project’s efforts to provide secure code to users was observable to the audit team and is reflected by the reported findings and further recommendations for future security work.

Thank you to the individuals and groups that made this engagement possible:

Notary Project maintainers and community, notably: Pritesh Bandi, Junjie Gao, Vani Rao, Shiwei Zhang, Yi Zha, Patrick Zheng, and Feynman Zhou
Quarkslab: Dahmun Goudarzi, Sébastien Rolland, and Ramtine Tofighi Shirazi
Cloud Native Computing Foundation (CNCF)

Blog: Notary Project announces Notation v1.3.0 and tspclient-go v1.0.0!

Fri, 17 Jan 2025 00:00:00 +0000

The Notary Project maintainers are thrilled to announce the latest releases, including notation v1.3.0, notation-go v1.3.0, notation-core-go v1.2.0 and tspclient-go v1.0.0!

These new versions are production ready and have successfully completed a comprehensive security audit. Check out the security audit report for more details. Our commitment to providing secure and high-quality signing and verification tools for our users has never been stronger!

Notable Capabilities in these Releases

Here are the major capabilities and features included in these releases.

The first major release of `tspclient-go` library

Looking for a robust implementation of RFC 3161 Timestamp Protocol Client in Go? The library tspclient-go is the answer. Here is why:

RFC 3161 Compliance: Adheres to the specification RFC 3161 for timestamping clients. Supports timestamping with popular public TSAs like DigiCert and GlobalSign.
Secure: Implements secure communication protocols, ensuring the integrity and authenticity of timestamps.
Minimal Dependencies: Uses only standard Go libraries. Less dependencies, more secure.
High Test Coverage: Boasts up to 95% test coverage.
Security Audited: Passed a comprehensive security audit with no advisories, ensuring a high quality bar.
Ease of Use: Seamlessly integrates into Go applications with a straightforward API.

Notary Project’s timestamping feature is built on this library.

Certificate Revocation checking using Certificate Revocation List (CRL)

Certificate revocation checking enhances security by ensuring that compromised or expired certificates are not used, thereby maintaining the integrity and trustworthiness of digital signatures. It also helps organizations comply with security standards and regulations. With this release, Notation implements the Notary Project CRL specification with CRL cache support. Notation now supports two certificate revocation checking methods: Online Certificate Status Protocol (OCSP) and CRL. OCSP is preferred, but if unavailable, CRLs are used as a fallback. For more details on CRL cache directories, visit this link.

By default, Notary Project trust policies enforce revocation checking, so users do not need to configure it. For more details on fine-tuning revocation settings, visit this link.

Get started with Notation v1.3.0

You can follow the quick start guide to try Notation v1.3.0 for basic signing and verification workflow.

What’s next

The Notary Project maintainers are considering the following features for future milestones. Feel free to reach out on the Slack channel or GitHub issues to ask questions, provide feedback, or share ideas.

Sign and verify arbitrary blobs
Attestations

And more!

Acknowledgements

The Notary Project release team wants to thank the entire Notary Project community for all the activity and engagement that has been vital for helping the project grow and reach this milestone.

We are especially grateful to the CNCF for funding the security audit, the OSTIF for arranging it, and Quarkslab for conducting and releasing the audit report.

Blog: Notary Project announces Specification v1.1.0 and Notation v1.2.0!

Fri, 30 Aug 2024 00:00:00 +0000

The Notary Project maintainers are excited to announce new releases, including Notary Project specifications v1.1.0, notation v1.2.0, notation-go v1.2.0, and notation-core-go v1.1.0. These versions are now ready for production use!

Deprecation

The experimental flag --allow-referrers-api used by notation sign and notation verify commands is now deprecated. See Support OCI specification v1.1.0 for details.

Notable Capabilities in this Release

Here are some of the major capabilities and features included in this release.

Notary Project specifications

The Notary Project specifications now include support for RFC 3161 timestamping and introduce Notation plugin conventions in the plugin specification.

Support OCI specification v1.1.0

In Feb 2024, the Open Container Initiative (OCI) community released version 1.1.0, which includes the OCI image specification v1.1.0 and the OCI distribution specification v1.1.0. Notation now adheres to the OCI spec v1.1.0, leading to the deprecation of the experimental flag --allow-referrers-api. A new flag, --force-referrers-tag (default to true), has been introduced to the notation sign command. Using the default true value, the referrers tag schema is always used for storing signatures in registries. You can set the value to false to use the referrers API for signature storage if the target registry supports the referrers API (if it does not, the referrers tag fallback will be used). In contrast, the notation verify/list/inspect commands will attempt to use the referrers API first and automatically fall back to the referrers tag schema if the referrers API is not supported by the registry.

[!NOTE] We will change the default value of --force-referrers-tag to false in Notation v2.0 release, making referrers API usage as the default.

Support for RFC 3161 compliant timestamping

Since this release, Notation supports RFC 3161 compliant timestamping. Digital signatures must be generated within the certificate’s validity period, as expired certificates compromise the signature’s trustworthiness. Timestamping extends the trust of signatures created within certificate validity, allowing successful signature verification even after certificates have expired. Notation’s timestamping feature is built on top of the tspclient-go library.

Learn more at the document how to sign and verify artifacts in OCI-compliant registries with timestamping.

Other changes

Notation CLI now offers the armv7 binary, enabling its usage in environments such as Internet of Things (IoT) or embedded systems.

Get started with Notation v1.2.0

You can follow the quick start guide to try Notation v1.2.0 for basic signing and verification workflow.

What’s next

Revocation checking using Certificate Revocation List (CRL)
Sign and verify arbitrary blobs
Attestations

And more!

Acknowledgements

The Notary Project release team wants to thank the entire Notary Project community for all the activity and engagement that has been vital for helping the project grow and reach this milestone.

Blog: Bitnami now uses Notation for signing and verifying containers and Helm charts on Docker Hub

Mon, 18 Mar 2024 00:00:00 +0000

Bitnami-packaged open source software container images and Helm charts available in DockerHub are now signed by Notation.

Bitnami provides the latest versions of pre-packaged, hardened, ready-to-deploy open source software application packages that enable developers to hit the ground running when building new applications and services on any platform. Bitnami open source software packages are highly popular with developers with over 500 million pulls per month and over 2 billion computer hours per year. This strong developer community of Bitnami has leveraged its robust application catalog to build millions of applications for almost 20 years now.

In December 2023, we announced that Tanzu Application Catalog, the enterprise edition of Bitnami Application Catalog, started making use of Notation as a tool for signing and verifying open container initiative (OCI) artifacts (e.g. container images, Helm charts, and metadata bundles.

Now, we are happy to have extended our collaboration with Notation and announce the extension of this capability to the community edition of Bitnami-packaged container images and Helm charts in DockerHub as well.

To know more about the benefits that the Bitnami users stand to enjoy with this integration and to learn how to verify the signature of a Bitnami-package, check out this blog.

If you are interested in learning more about Tanzu Application Catalog, check out their product webpage and additional resources.

Blog: Notary Project announces Notation v1.1.0!

Thu, 08 Feb 2024 00:00:00 +0000

The Notary Project maintainers are proud to announce new releases for its sub-projects, including Notary Project specifications v1.1.0, notation v1.1.0, notation-go v1.1.0, and notation-core-go v1.0.2, Notation GitHub Actions v1.0.1 which are ready for production use!

Meanwhile, a new library notation-plugin-framework-go released the first release v1.0.0. It contains framework required to create notation plugins as per Notation Plugin specification.

Notable Capabilities in this Release

Here are some of the major capabilities and features included in this release.

Easier plugin management functionalities

Notation has an extensible design based on a plugin framework. This framework provides plugin interfaces for users and vendors to implement their own integration with key/certificate management solutions or signing services.

In this release, Notation offers Notation plugin management capabilities to simplify the plugin user experience.

Added new command notation plugin install. Users are now able to install a notation plugin directly from a URL or from their file system. Supported plugin installation formats are .zip, .tar.gz, and single plugin executable file. See an example usage below:

$ notation plugin install --file <file_path>

$ notation plugin install --sha256sum <digest> --url <HTTPS_URL>

Added new command notation plugin uninstall. Users are now able to uninstall a notation plugin by providing the plugin name. See an example usage below:

notation plugin uninstall <plugin_name>

The following plugins have been well tested with Notation plugin commands by Notary Project maintainers:

Specifications

For plugin vendors who want to package and distribute a Notation plugin, Notation Plugin specification defines the plugin conventions to ensure plugins are delivered in a consistent format and compatible with notation plugin management commands.

Get started with Notation v1.1.0

You can follow this quick start to try Notation v1.1.0 on your terminal.

The default Notation CLI setup action in Notation GitHub Actions has also been updated to v1.1.0. It enables users to install Notation and its plugin, sign and verify OCI artifacts in GitHub Actions workflow with ease.

To get started with Notation v1.1.0 in a CI/CD workflow, you can find the Notation GitHub Actions in the Marketplace.

What’s next

Sign and verify arbitrary blobs
Timestamping support
Improve error messages and verbose logs

And more!

Acknowledgements

The Notary Project release team wants to thank the entire Notary Project community for all the activity and engagement that has been vital for helping the project grow and reach this major milestone.

Blog: VMware Tanzu Application Catalog now uses Notation for signing and verifying OCI artifacts

Tue, 19 Dec 2023 00:00:00 +0000

VMware Tanzu Application Catalog, the enterprise edition of Bitnami Application Catalog, now leverages Notation as a tool for signing and verifying open container initiative (OCI) artifacts (e.g. container images, Helm charts, and metadata bundles).

Tanzu Application Catalog enables enterprises to build their own private catalog of custom-packaged open source application components that are continuously maintained and verifiably tested for use in production environments. Built by leveraging Bitnami’s expertise in packaging hundreds of open source software applications and delivering them to millions of developers, Tanzu Application Catalog aims to address the open source software needs of enterprises by providing them with customized ready-to-deploy open source applications along with extensive metadata for efficient risk assessment.

With this integration, Notation plays a key role in Tanzu Application Catalog’s mission of making open source software enterprise ready.

What Tanzu Application Catalog achieves by using Notation

Ensure content integrity: By signing their OCI artifacts using Notation, Tanzu Application Catalog team can help ensure the integrity of the OCI artifacts they deliver to their customers. Tanzu team uses Notation to sign their OCI artifacts, creating a unique fingerprint for each version of the artifact. Any tampering with the OCI artifact will result in a failed verification, alerting users to potential security threats.
Verify authenticity: Knowing the source of OCI artifacts is crucial for security and compliance of enterprises. Notation, a client from the Notary Project, helps generate cryptographic signatures to verify artifact authenticity by validating signer’s cryptographic identity. Validation helps ensures that the signed applications are built by trusted sources, i.e. Tanzu Application Catalog in this case, reducing the risk of deploying unapproved software.
Interoperability across tools and platforms: Notary Project along with its client tool Notation has standardized signature format. This standardization enables interoperability across different tools, registries, container orchestrators, and platforms that support the OCI image format.

Thus, Notation, with its standards-based tooling for signing and verifying artifacts, helps Tanzu Application Catalog achieve improved security while delivering compliant open source software artifacts for mission critical production use cases.

To read more about how Tanzu Application Catalog leverages Notation, check out this blog.

If you are interested in learning more about Tanzu Application Catalog, check out their product webpage and additional resources.

Blog: Notary Project featured on the Enlightning Podcast

Wed, 04 Oct 2023 00:00:00 +0000

Notary Project maintainers Toddy Mladenov and Milind Gokarn talk with host Whitney Lee about the Notary Project on the Enlightning Podcast. This wide-ranging discussion covers everything from the project history, to concepts, and to the future of the project.

Blog: Notary Project announces a major release!

Tue, 22 Aug 2023 00:00:00 +0000

The Notary Project maintainers are proud to announce a major release, including Notary Project specifications v1.0.0, notation v1.0.0, notation-go v1.0.0, and notation-core-go v1.0.0 which are ready for production use!

What is Notary Project and Notation?

As containers and cloud native artifacts become common deployment units, users want to make sure that they are authentic in their environments. The Notary Project is a set of specifications and tools intended to provide cross-industry standards for securing software supply chains through signing and verification, signature portability, and key/certificate management.

Notation is a sub-project of Notary Project, which consists of the notation CLI and two Golang libraries which implement the latest Notary Project specifications. Notation was started in Dec 2019 and the code has matured through a series of minor and RC releases over the last few years; The first version of the CLI and libraries v0.7.0-alpha.1 was released in Oct 2021. Several alpha, beta, and RC releases later, the binaries reached the final v1.0.0-RC.7 release in May 2023.

To learn more about the Notary Project, see the Notary Project Overview and the FAQ.

Notable Capabilities in this Release

Here are some of the major capabilities and features included in this release.

Specifications

Notary Project specifications reached its major release. All specifications, requirements, scenarios, threat model, and security audit reports are available in this release. ISVs and tool developers that want to interoperate with the Notary Project signatures and tooling should use the specifications to ensure compatibility.

Signing and verification functionalities

From the software producer’s perspective, signing a software artifact enables their consumers to detect tampering and ensure authenticity of the artifact. Signing software can also increase trust when distributing software artifacts to consumers. Notary Project provides the following core capabilities for the signing experience:

Sign artifacts using signing keys stored securely in a key management system (KMS) or a signing service. See the available plugins in the section Extensibility: plugin support for Notation
Sign artifacts as well as list and inspect signatures stored in OCI-compliant registries
- Compliant with image-spec v1.0.2
- Compliant with distribution-spec v1.0.1
- Compatible with image-spec v1.1.0-rc4
- Compatible with distribution-spec v1.1.0-rc3 (limited to referrers tag schema)
Support two signature envelope formats
- COSE: COSE is an efficient, binary envelope format that can be used for variety of scenarios ranging from signing traditional software to IoT workloads running on low-powered devices.
- JWS: JWS is a widely used JSON-based envelope format that can be used for interoperability with existing applications and various authentication schemes including OIDC.

From the software consumer’s perspective, verifying the signature of a signed artifact ensures its integrity and authenticity. Notary Project provides the following core capabilities for verification experience:

Verify signatures using trust store and trust policy. This also includes fine-tuned OCI repository specific trust policies and support for various enforcement levels (e.g. enforce, permissive, audit) to enable a wide range of scenarios.
notation policy command can be used to simplify the experience of importing and inspecting the trust policy.

Experimental features

Experimental features are intended for testing and evaluation purposes only and should not be used in production environments. Users can enable experimental features in Notation CLI by setting the environment variable NOTATION_EXPERIMENTAL to 1 as shown below.

export NOTATION_EXPERIMENTAL=1

There are two major features which are marked as experimental.

Signing, listing, and verifying artifacts with OCI image layout before they are pushed to a registry. This enables users sign and verify artifacts stored on the local file system.
OCI distribution referrers API. This allows the Notation CLI to fetch a list of signatures in an efficient and clean manner.

Extensibility: plugin support for Notation

Notation has an extensible design based on a plugin framework. This framework provides plugin interfaces for users and vendors to implement their own integrations with key/certificate management solutions or signing services. Currently, Notation has the following plugins available.

Integration with admission controller for Kubernetes usage

To enable users to verify and secure image deployment on Kubernetes, the Notary Project maintainers worked with the Ratify and Kyverno teams to provide solutions for verifying images signed by Notation before deploying them to Kubernetes. Users have two different options to build a complete end-to-end image integrity workflow for their environments. For more details, see:

Built-in security

As part of our commitment to security, the Notary Project maintainers engaged with CNCF to set up continuous fuzzing of the source code and completed a security audit in 2023. All vulnerabilities found during the testing and the audit were fixed before the release of the libraries and the CLI. Below are links to the security reports:

What’s next

Sign and verify arbitrary blobs
GitHub Actions and other CI/CD integration for signing and verification
HashiCorp Vault plugin (experimental)
Plugin lifecycle management
Timestamping support
Manage trust policy via CLI commands

Acknowledgements

The Notary Project release team wants to thank the entire Notary Project community for all the activity and engagement that has been vital for helping the project grow and reach this major milestone.

Try it now

You can follow this interactive tutorial to try Notation CLI v1.0.0 in an online cloud playground or follow the quick start on your computer.

Blog: Announcing results of Notation security audit 2023

Thu, 06 Jul 2023 00:00:00 +0000

In early 2023, Notary Project, under the guidance of Cloud Native Computing Foundation began work with Ada Logics to perform the first security audit of the Notation libraries and CLI. The Notation libraries and CLI are a reference implementation of the latest Notary Project specifications. Ada Logics discovered seven issues and those issues have been fixed by Notary Project maintainers. This blog post summarizes the overall findings and notes a few things learnt from the security audit result.

We are very grateful to the CNCF for funding this work, the OSTIF for arranging the audit, and Ada Logics for conducting and releasing the security audit.

Summary of findings

Ada Logics identified seven issues of varying severity:

one high-severity issue
two moderate-severity issues
three low-severity issues
one informational issue

All issues were fixed in Notation v1.0.0-RC.6. As a result, all subsequent releases of Notation CLI, including latest RC-7 and the upcoming 1.0.0 release, includes these fixes. The Notary Project maintainers created CVEs for three issues, and tracked the remaining four issues as non-CVEs involving documentation or CLI command flags name changes.

Below are the specific details for the seven issues identified in the security audit:

Potential endless data attack in notation ls, ADA-NOT-23-1, aka CVE-2023-33958, fixed in Notation-v1.0.0-RC.6.
Max allowed signatures could lead to an endless data attack, ADA-NOT-23-2, aka CVE-2023-33957, fixed in Notation-v1.0.0-RC.6.
Overwriting global variable could lead to undefined behavior of Notation in the future, ADA-NOT-23-3, fixed in Notation-v1.0.0-RC.6.
Insufficient security-relevant documentation findings, ADA-NOT-23-4, are fixed with documentation updates in securely deploy Notation.
Clear text storage of sensitive information in an environment variable, ADA-NOT-23-5, fixed by adding security best practice document on how to authenticate to OCI registries.
Insufficient verification of fetched artifact descriptor, ADA-NOT-23-6, aka CVE-2023-33959, fixed in Notation-v1.0.0-RC.6.
Denial of service from resource exhaustion in notation inspect, ADA-NOT-23-7, fixed in Notation-v1.0.0-RC.6.

Details by category of findings

Endless data attack can cause resource exhaustion leading to denial of service attack (ADA-NOT-23-1, ADA-NOT-23-2, and ADA-NOT-23-7)

This issue was initially reported for the notation list command which lists all signature artifacts associated with a signed image (OCI artifact). This issue can also affect other CLI commands such as notation inspect, or notation verify which pulls all signatures associated with an image. Refer to CVE-2023-33957 and CVE-2023-33958 for details. The concern was a threat actor could cause denial of service attack by associating large number of signatures to an OCI artifact, such as a container image, and causing Notation to endlessly enumerate all signatures. The fix was relatively straightforward to have a default configurable maximum limit of 100 signatures that Notation CLI will enumerate for any given operation. Users can adjust this number for their unique needs.

Overwriting a global variable could lead to undefined behavior (ADA-NOT-23-3)

Notation overwrites a global import identifier in the verification command. There is no current way to exploit this issue, but it could lead to undefined behavior of Notation in the future, if a contributor adds code that allows an attacker to trigger an issue. The issue is flagged informational since we have found no attack vector.

Insufficient documentation and non-descriptive CLI command (ADA-NOT-23-4 and ADA-NOT-23-5)

Notation maintainers have improved documentation to include security best practices for

Securely deploying Notation
Securely developing and managing plugins. Ensure plugins are downloaded from a trusted source
Renamed plain-http flag to insecure-registry to clarify that authenticating to registries over HTTP is insecure and should only be used for testing purposes

Validating unintended artifact (ADA-NOT-23-6)

This issue allowed threat actors, who have compromised the registry, to sign or verify the artifact other than intended one. Refer to CVE-2023-33959 for more details. The issue has been fixed in the notation-go library to validate that the descriptor signed or verified by Notation is the one provided by user.

Fuzzing

The Notary Project announced the completion of its fuzzing security audit in Mar 2023. The audit was also carried out by Ada Logics and is part of an initiative by the CNCF to bring fuzzing to the CNCF landscape. The fuzzing audit resulted in 20 fuzzers written for 3 Notation code repositories and 2 issues being identified and addressed including a critical security fix. The full report from the fuzzing audit is available here.

SLSA

Supply chain Levels for Software Artifacts (SLSA) is a check-list of standards and controls to prevent tampering, improve integrity, and secure software packages and infrastructure. It is organized into a series of levels that provide increasing integrity guarantees.

Notation build process does not generate provenance artifacts. The Notary Project maintainers have a plan to generate the provenance artifacts for Notation to ensure the origins of the binaries.

Conclusion

The Notary Project maintainers owe a huge thanks to the CNCF, OSTIF, and Ada Logics for sponsoring, facilitating, and conducting this security audit. Aside from their observations above, the auditors noted that Notation contributors follow high security standards and best practices for implementation.

If you have questions about the audit report, reach out to Notary Project maintainers in the #notary-project channel of the CNCF Slack workspace. If you find any security vulnerability, please use the GitHub Security Vulnerability Disclosure process for each one of the Notary Project repositories by following this guide.

Blog: Notation v1.0.0-RC.7 is available!

Sun, 28 May 2023 00:00:00 +0000

The Notation maintainers are pleased to announce the release of Notation v1.0.0-RC.7, including Notation CLI v1.0.0-rc.7, notation-go library v1.0.0-rc.6, and notation-core-go library v1.0.0-rc.4. This blog walks you through the updates in this release.

NOTE: Both Notation CLI v1.0.0-rc.7 and v1.0.0-rc.6 have the same functionalities. However, v1.0.0-rc.7 included an additional fix for an E2E test case.

What’s new

This release adds the following major changes:

Security advisory fixes: CVE-2023-33957, CVE-2023-33958, CVE-2023-33959
Notation commands support reading Docker credentials if the credentials store is not present
Renamed --plain-http to --insecure-registry to guide that it should only for testing
Improved error messages
Bug fixes
Updated dependencies

Notation commands support reading Docker credentials if credentials store is not present

Security best practices recommend that users configure a credentials store to securely manage credentials, especially in production environments. Notation commands use the following order to find credentials to authenticate with registries. Notation commands first look for credentials in its Notation’s config file, if absent Notation looks for credentials in docker config file, and if even that is not present, Notation uses the operating system default. This way, for users who do not configure explicit credentials in Notation, a successful docker login, will enable them to run notation sign/verify/list/inspect commands without the need to complete notation login first.

However, there may be cases where no credentials store is present, such as in a test environment. If no credentials store is present, Docker stores the credentials in the config files by default, see reference. Starting with Notation v1.0.0-RC.7, notation commands support reading credentials from the Docker config file if no credentials store is present. This way, a successful docker login, will enable users to run notation sign/verify/list/inspect commands without the need to complete notation login first. For example,

# No credentials store is present
docker login <registry>
notation sign --key <key_name> <image>
notation ls <image>
notation inspect <image>
notation verify <image>

Flag `--plain-http` was renamed to `--insecure-registry`

The original flag --plain-http and its description did not emphasize that it is an insecure way to connect to the registry, and it should only be used for testing purposes. With updated description and the name changed to --insecure-registry, it is now more intuitive and emphasized for users to understand the usage of this flag. Other than the name change, there is no difference between the two flags.

Known issue

An issue was reported on this version that notation login/logout commands failed to detect credentials store, which is actually present and used by Docker CLI. See details. This issue doesn’t impact other notation commands, so if you have successfully logged in registries using docker login, you can continue to use other Notation commands, for example, notation sign. If you want to fix the issue for notation login/logout, the workaround is to manually create or update config.json file with correct credentials store configuration, and store this file under notation configuration directory. For example:

{
"credsStore": "desktop.exe"
}

In above example, desktop.exe is the Docker credential store installed in Windows.

Credits

We would like to specially thank the Notary maintainers, contributors, and the broader Notary community for helping us throughout the release process with timely feedback, reviews, and testing and for all your support to help ensure a timely release. Sending credits to the following contributors who made great contributions to Notation v1.0.0-RC.7.

Download and give it a try

Follow this hands-on guide to get started.

Blog: Notation v1.0.0-RC.5 is available!

Thu, 18 May 2023 00:00:00 +0000

The Notation maintainers are pleased to announce v1.0.0-RC.5 for notation CLI and notation-go library. This blog walks you through the major updates in this release.

Major updates in notation CLI and notation-go library

Notation is a CLI tool to sign and verify OCI artifacts. The v1.0.0-RC.5 changes include but are not limited to the following. See the v1.0.0-RC.5 release notes for details.

Improve the output message for notation inspect and notation list when there is no signature associated with the image being referred
Update compatibility with the OCI distribution-spec 1.1.0-RC.2 and OCI image-spec v1.1.0-RC.3
Use SHA256 instead of insecure SHA1 for certificate thumbprint in notation inspect
Update OCI image-spec from 1.1.0-RC.2 to 1.1.0-RC.3

Notation-go is a collection of Golang libraries to support signing and verifying OCI artifacts. It is based on the Notary Project signature specification. Notation-go v1.0.0-RC.5 removes OCI artifact manifest type from Sign function.

Deprecate flag `--signature-manifest` in notation sign

Since v1.0.0-RC.5, Notation no longer supports creating signatures with OCI artifact manifest type in the signing process and deprecated the flag --signature-manifest from notation sign. Please note this is a breaking change in Notation v1.0.0-RC.5. We chose to make this deprecation before the v1.0.0 release due to the upstream changes in the OCI image-spec v1.1.0-rc.3 that removed the artifact manifest.

To mitigate the impact to Notation users, Notation v1.0.0-RC.5 is still able to read and verify the existing signatures stored with the OCI artifact manifest type in OCI v1.1.0-RC.1 compliant registries. OCI artifacts signed by earlier versions of Notation are still verifiable with Notation v1.0.0-RC.5.

Change default behavior and introduce a new flag `--allow-referrers-api`

Starting with Notation v1.0.0-RC.5 release, Notation will use the Referrers Tag Schema as the default behavior since most of the OCI registries are compatible with storing signatures using the Referrers Tag Schema. The Referrers API and its fallback strategy are still under development according to recent OCI Distribution Spec changes, so it is marked as experimental in Notation v1.0.0-RC.5.

In this context, Notation v1.0.0-RC.5 introduces a new experimental flag --allow-referrers-api to the following commands:

notation sign
notation verify
notation inspect
notation list

Specifically, users need to set the environment variable NOTATION_EXPERIMENTAL=1 to enable this new flag, then Notation attempts the Referrers API and fallback to Referrers Tag Schema on failure when using with OCI registry. Otherwise, Notation has deterministic behavior and uses Referrers Tag Schema by default.

Please note that users need to add this experimental flag --allow-referrers-api when verifying signatures with OCI v1.1 compliant registry after upgrading Notation from v1.0.0 RC.4.

Note

Referrers Tag Schema is described as <alg>-<ref>, such as sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa. For backwards compatibility, this behavior should work in existing OCI v1.0 compliant registries without any changes needed.

Credits

We would like to specially thank the Notary maintainers, contributors, and the broader Notary community for helping us throughout the release process with timely feedback, reviews, testing, and support to help ensure a timely release. Sending credits to the following contributors who made great contributions to v1.0.0-RC.5.

Download and give it a try

Follow this hands-on guide to get started.

Blog: Notation v1.0.0-RC.4 is available!

Fri, 21 Apr 2023 00:00:00 +0000

The Notation maintainers are pleased to announce the releases of Notation CLI v1.0.0-rc.4, notation-go v1.0.0-rc.4, and notation-core-go v1.0.0-rc.3. This blog walks you through the major updates of this release.

What’s new

This release adds the following significant enhancements:

Support validating certificate revocation with Online Certificate Status Protocol (OCSP)
Introduce switch NOTATION_EXPERIMENTAL=1 to enable experimental features
Introduce new CLI command notation policy to simplify trust policy configuration
Support OCI distribution referrers API
Introduce signing, listing and verification with OCI image layout for signing images before they are pushed in a registry as an experimental feature
Experimental flag --signature-manifest for notation sign command is now controlled by switch NOTATION_EXPERIMENTAL=1

Support validating Certificate revocation with OCSP

Notation now supports Certificate Revocation using Online Certificate Status Protocol(OCSP) for distributing certificate revocation information. Notation clients uses OCSP to query if any certificate used for signing has been revoked. Signers can revoke a certificate to inform verifiers that any signature generated by the certificate (beyond the revocation date) should no longer be trusted. To enforce validating certificate revocation, the verification level of trust policy must be set to strict as following. Depending on the trust policy verification level setting, notation verify command automatically validates the signatures and checks the revocation status. The verification process will fail if any certificate in the certificate chain has been revoked.

"signatureVerification": {
"level" : "strict"
}

Introduce switch `NOTATION_EXPERIMENTAL=1` to enable experimental features

Experimental features are intended for testing and evaluation purposes only and should not be used in production environments. You can now enable experimental features in Notation CLI by setting the NOTATION_EXPERIMENTAL environment variable to 1. Here’s an example of how to set the environment variable in Linux or macOS:

export NOTATION_EXPERIMENTAL=1

And here’s an example of how to set the environment variable in Windows PowerShell:

$env:NOTATION_EXPERIMENTAL=1

Once you’ve set the environment variable, you can use Notation with experimental features enabled. Here is the list of experimental features that Notation introduced:

Store signatures using artifact manifest (Require Registry support)
Signing, listing and verifying images as OCI image layout

Introduce new CLI command `notation policy` to simplify trust policy configuration

To simplify the user experience of managing trust policy configuration, we have introduced two new commands in the v1.0.0-rc.4 release: notation policy import and notation policy show.

Previously, users had to follow several steps to configure trust policy configuration in a JSON file, save the file with a specific name, ensure the file encoding was utf-8, and put the file in a specific directory that varied across different operating systems. With the notation policy import command, users can now import trust policy configuration directly from the JSON file after completing the first step above. Additionally, a health check is performed on the trust policy configuration during import to avoid configuration issues that may arise later. For example:

notation policy import my_policy.json

The notation policy show command allows users to easily view trust policy configuration and redirect the output to a file for sharing, updating, or other purposes. For example:

notation policy show

We will be introducing more commands in future releases. Stay tuned for updates on how we’re making it easier for you to manage your trust policy configuration.

Support OCI distribution 1.1 referrers API

The Referrers API is a new feature added in OCI distribution spec v1.1-rc.1, which allows clients to fetch a list of referrers in an efficient and clean manner. In the context of Notation, referrers are signatures that refer to the container image. Since this release, Notation verifies whether the Referrers API is available in the registry when pushing signatures into the registry. If the Referrers API is not available, Notation follows the fallback procedure and updates the image index pushed to a tag described by the referrers tag schema.

Introduce signing, listing and verification with OCI image layout as an experimental feature

Typically, images are pushed to registries before they are signed. The images you are going to sign could already be tampered with. These images could pass signature verification and be deployed in the production environment. To address this issue, we have introduced an experimental feature that allows users to sign images before pushing them to registries. This is especially valuable if the registries are not within your trust boundaries. The OCI image layout is a standard defined in the OCI image spec 1.0. It is essentially a directory structure that contains files and folders that refer to an OCI image. Here’s a glimpse of the experience on Linux, and we will release a tutorial for this feature soon.

# Enable experimental feature
export NOTATION_EXPERIMENTAL=1
# Create oci image layout as tarball file
docker buildx build . -f Dockerfile -o type=oci,dest=hello-world.tar -t hello-world:v1
# Extract tarball to a directory named hello-world, 
# so that the signatures can be associated with the image
tar -xf ./hello-world.tar -C hello-world
# Sign OCI image layout
notation sign --oci-layout ./hello-world:v1
# List signatures
notation list --oci-layout ./hello-world:v1
# Configure trust policy scope "local/hello-world" and verify signatures stored in OCI layout directory
notation verify --oci-layout ./hello-world:v1 --scope "local/hello-world"

After signing OCI image layout successfully, you can use tools like oras to push OCI image layout including signatures from local to remote registries.

# Use oras CLI to push OCI image layout to remote registries
oras cp --from-oci-layout -r ./hello-world:v1 ghcr.io/$username/hello-world:v1
# List the signature, which is exactly the same as you signed locally
notation list ghcr.io/$username/hello-world:v1
# Verify the image before deployment
notation verify ghcr.io/$username/hello-world:v1

Please give it a try and let us know your feedback. We will continue to iterate on it.

Other updates

Support username and password prompt using notation login command
Bug fixes

Credits

We would like to specially thank the Notation maintainers, contributors, and the broader Notation community for helping us throughout the release process with timely feedback, reviews, community testing and for all your support to help ensure a timely release. Sending credits to the following contributors who made great contributions to Notation RC.4.

Download and give it a try

Follow this hands-on guide to get started.

Blog: The Notary Project completes fuzzing security audit

Fri, 17 Mar 2023 00:00:00 +0000

Reviewed by Pritesh Bandi, Samir Kakkar, Shiwei Zhang, Toddy Mladenov, Vani Rao, Yi Zha

The Notary Project is happy to announce the completion of its fuzzing security audit. The audit was carried out by Ada Logics and is part of an initiative by the CNCF to bring fuzzing to the CNCF landscape. The audit spanned several months in late 2022 and early 2023 and resulted in 20 fuzzers written for 3 Notary sub-projects and 2 issues being identified and addressed including a critical security fix.

The full report from the audit is available here.

About the Notary Project

The Notary Project is an open standard and tooling for signing and verifying artifacts and safeguarding their distribution. It was started at Docker in 2015 and powers Docker Content Trust which is the docker trust set of commands. With the Notary Project, users can attest to the trustworthiness of data and verify the integrity of the signed data.

The Notary Project was accepted into the CNCF in October 2017 and is hosted as an incubating project. Contributors are both independent individuals and from organizations including Microsoft, AWS, and Docker. Notation-go and Notation-core-go are sub-projects of the Notary Project. The implementation is an effort to build a signing framework to be used with OCI v1.1 compliant registry, allowing signatures to easily be associated and distributed with images.

The fuzzing audit was performed on all three active code sub-projects listed below:

Notary: A server and a client for running and interacting with trusted collections.
Notation-go: a collection of libraries for supporting signing, verifying OCI artifacts. Based on the Notary standard.
Notation-core-go: Crypto library for signature envelope, and signature format specific implementation.

Fuzzing the Notary Project

Fuzzing is a way of testing software, whereby pseudo-random data is passed to a target API with the goal of detecting bugs and security issues. The pseudo-random data is created by a fuzzing engine that over time will generate test cases that uncover more of the code base. This type of fuzzing is called “coverage-guided fuzzing” and has been effective in finding bugs in software projects implemented in both memory-safe and memory-unsafe languages. This includes several other CNCF-hosted projects; Most recently, a security issue was found in containerd during its fuzzing audit.

There are several reasons why it’s important to fuzz your software and we’ll try to list some of the primary ones. First, due to empirical evidence where fuzzing is a proven technique for finding bugs and has found tens of thousands of bugs in security-critical software. Second, fuzzers find bugs that static analysis and manual auditing miss. This is because fuzzers rely on instrumenting and executing the code under analysis, which enables the fuzzers to have a different perspective than other analysis techniques and monitor deeper in the code, including third party dependencies. For example, a high severity bug in Istio CVE-2022-23645 was due to a fairly unintuitive behaviour that static and manual analysis are very unlikely to find. Third, fuzzing is intuitive in the sense that it’s closely related to unit- and integration-testing which makes it fit well with the developers workflow. Fourth, fuzzing is part of the secure development lifecycle for leading tech companies and has been for more than a decade.

A critical component of a robust fuzzing suite is making sure that the fuzzers run continuously. The auditors of the Notary Projects fuzzing audit integrated Notary, Notation-go, and Notation-core-go into OSS-Fuzz. OSS-Fuzz is an open-source project run by Google, which runs the fuzzers of critical open-source projects at scale with excessive computing, thus achieving much higher runtime results than developers would see when running the fuzzers locally. OSS-Fuzz is a critical piece of open-source fuzzing infrastructure and many other CNCF projects are integrated including Kubernetes, Helm, containerd, Argo, Flux, Envoy, Fluent-bit, and others.

Once the auditors had integrated the three Notation projects into OSS-Fuzz, they wrote the fuzzers covering all three projects and added them to the CNCF fuzzing repository, https://github.com/cncf/cncf-fuzzing. They then instructed OSS-Fuzz to pull them from there, allowing the fuzzers to run continuously during the audit as well as after the audit had concluded.

Findings

The fuzzing audit found two issues both of which had their root cause in 3rd-party dependencies. One of the issues was found to be a memory-exhaustion vulnerability in Notation-go and was assigned CVE-2023-25656. The vulnerability could be triggered by a specifically malicious security policy containing the char sequence =#. The issue has been fixed in Notation v1.0.0-rc.3 and later by denying any policy that contains that char sequence. The vulnerability has been disclosed in GHSA-87x9-7grx-m28v.

The second found issue was a slice bounds out of range panic, which was a functional bug and not a security issue. The root cause was in a 3rd-party dependency and the crash is recoverable. This issue has been fixed in notation-go v1.0.0-RC.3.

Contributing

Notary Project has various sub-projects, of which some of the new ones like Notation, Notation-go, and Notation-core-go are in active development. Your contributions to the Notary Project code and documentation are welcome; A great way to get started with contributing to the Notary Project is by joining the #notary-project channel in the CNCF Slack workspace. If you find a problem or would like to suggest an enhancement, you can create an issue or submit a pull request on the related sub-projects repository.

Blog: Notation v1.0.0-RC.3 is available!

Wed, 08 Mar 2023 00:00:00 +0000

The Notation maintainers are pleased to announce the release of Notation CLI v1.0.0-RC.3. This blog walks you through the major updates of this release.

What’s new

This release introduces a change to how signatures are stored in the registries to align with the OCI direction to use image manifest. The default type of signature manifest is changed to image manifest. The flag --signature-manifest for notation sign command is experimental for users who want to store signatures using artifact manifest. This change does not impact the validation of signatures.

Signing experience is continuously improved in this release. Less configuration steps were required before users run notation sign command.

About signature manifest

The signature is stored associated with signed artifacts in the OCI conformant registry. Since this release, the default type of signature manifest is changed from artifact manifest to image manifest. The signatures of the artifacts signed by previous releases of Notation (v1.0.0-RC.1 and v1.0.0-RC.2) can still be validated using the new release.

Users can still store signatures using artifact manifest by using an experimental flag --signature-manifest, for example:

notation sign --signature-manifest artifact localhost:net-monitor@sha256:xxx

There are no changes on signature verification. Use notation verify command as usual, for example:

notation verify localhost:net-monitor@sha256:xxx

Image manifest is commonly supported by a wide range of registries in the market. Users are strongly recommended to update to this release for using image manifest by default.

Sign artifacts using on-demand keys

This release introduces a new experience of signing artifacts using on-demand keys. Here are the steps of signing:

Create a private key and get the key identity from the Key Management System (KMS)

Sign artifacts with a single command, for example:

notation sign --id <key_id> --plugin <KMS_plugin> localhost:5000/net-monitor@sha256:xxx

Now users can pass the signing key to the notation sign command directly. This experience reduces the number of configuration steps required to setup signing.

Credits

Download and give it a try

Follow this hands-on guide to get started.

Blog: Notation v1.0.0-RC.2 is available!

Mon, 27 Feb 2023 00:00:00 +0000

The Notary v2 project maintainers are pleased to announce the release of Notation v1.0.0-RC.2, including Notation CLI, Notation-go, and Notation-core-go library. This is the first Notation release of 2023. This blog walks you through the major updates of this release.

What’s new

This release adds the following significant enhancements:

Inspecting signatures associated with signed artifacts
Storing signatures in the registry using OCI image manifest
Added user-defined metadata to signature payload
Add --debug and --verbose flags for troubleshooting

Improved usability and troubleshooting capability

For example, you can use notation inspect to get detailed information of signatures associated with the signed artifact in a human readable view.

$ notation inspect sample.registry.io/ratify-sample-repo:v1
Warning: Always inspect the artifact using digest(@sha256:...) rather than a tag(:v1) because resolved digest may not point to the same signed artifact, as tags are mutable.
Inspecting all signatures for signed artifact
sample.registry.io/ratify-sample-repo@sha256:5d7a0742f9c17400d21b29d2f27ed1b3429f0a71c5f53fb2a9ca3eff7850d2a6
└── application/vnd.cncf.notary.signature
└── sha256:d9d98d2b56b77f56ebe8e917643c6484017a39b89ff65e8b3449598d6b1adda5
├── media type: application/cose
├── signature algorithm: RSASSA-PSS-SHA-256
├── signed attributes
│ ├── signingScheme: notary.x509
│ ├── signingTime: Sun Feb 19 15:29:47 2023
│ └── expiry: Mon Jan 1 00:00:00 0001
├── user defined attributes
│ └── io.wabbit-networks.buildId: 123
├── unsigned attributes
│ └── signingAgent: Notation/1.0.0 kms/v0.4.0-beta.1
├── certificates
│ └── SHA1 fingerprint: def4344f733f1f57af3efd759b47c4576a10a723
│ ├── issued to: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ ├── issued by: CN=wabbit-networks.io,O=Notary,L=Seattle,ST=WA,C=US
│ └── expiry: Mon Feb 12 16:13:48 2024
└── signed artifact
├── media type: application/vnd.docker.distribution.manifest.v2+json
├── digest: sha256:5d7a0742f9c17400d21b29d2f27ed1b3429f0a71c5f53fb2a9ca3eff7850d2a6
└── size: 942

When verifying signatures associated with a signed artifact, users may want to get a list of the signed metadata included with the signature and use it evaluate additional decisions before using the signed image. A new flag --user-metadata was introduced to notation sign and notation verify in this release. Similar to annotations, you can easily add user-defined metadata to signature payload when signing an artifact or verify that provided key-value pairs are present in the payload of the valid signature.

$ notation verify --user-metadata io.wabbit-networks.buildId=123 sample.registry.io:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
Successfully verified signature for sample.registry.io:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
The artifact is signed with the following user metadata.
KEY VALUE
io.wabbit-networks.buildId 123

In addition, storing signatures in the registry using OCI image manifest was added into RC.2, you can use a flag --signature-manifest image to explicitly specify uploading image manifest to a registry when signing an artifact. This brings backward compatibility which enables Notation work with the registries that do not support OCI Spec v1.1 yet.

Last but not least, --debug and --verbose flags were added to all CLI commands, providing debug and troubleshooting capability for Notation CLI.

Ecosystem integration

Ratify is a verification engine for Kubernetes which enables verification of artifact security metadata and admits for deployment only those that comply with policies you create. Ratify v1.0.0 RC.1 integrated Notation-go v1.0.0-rc.2 which allows you to verify a container image signed by Notation.

Zot registry also integrates notation-go and supports storing signatures associated with the artifact. See this demo for details.

Going forward, Notation maintainers will work the community to support more ecosystem tooling and deliver consistent signing and verification experience, such as HashiCorp Vault KMS plugin, support Kyverno for Kubernetes policy management, and being compatible with more OCI registries.

Enhanced stability with more testing coverage

As the second RC release for v1.0.0, we aim to deliver a production-ready security product. Comparing with RC.1, the E2E testing framework built on ginkgo was set up in RC.2 and major test cases were added to Notation CLI. Meanwhile, unit test coverage was also increased by 5.92%. It definitely enhanced the program robustness and project stability.

Credits

Download and give it a try

You can also view the Release Notes of Notation v1.0.0-RC.2 to learn more about this release.

Start your container secure supply chain journey with Notation as it helps you safeguard your software supply chain and ensure integrity. Follow this hands-on guide to install and try Notation CLI v1.0.0-RC.2.

Blog: Notation signatures as ORAS and OCI artifacts

Mon, 21 Nov 2022 00:00:00 +0000

Notary and Notation

Notary project is a set of tools that helps you sign, store, and verify OCI artifacts using OCI-conformant registries.

Notation is an implementation of the Notary v2 specifications. As an implementation provides a CLI that adds signatures as standard items in the registry ecosystem, and can build a set of simple tooling for signing and verifying these signatures.

Notary v2 provides for multiple signatures of an OCI Artifact (including container images) to be persisted in an OCI conformant registry. Artifacts are signed with private keys, and validated with public keys.

To support user deployment flows, signing an OCI Artifact will not change the @digest or artifact :tag reference. To support content movement across multiple certification boundaries, artifacts and their signatures will be easily copied within and across OCI conformant registries.

To deliver on the Notary v2 goals of cross registry movement of artifacts with their signatures, changes to several projects are anticipated, including OCI distribution-spec, CNCF Distribution, OCI Artifacts, ORAS with further consumption from projects (e.g. containerd).

Already changes are coming in ORAS that unified the ORAS artifact spec into the new OCI artifact spec, to cover scenarios where images aren’t the only artifact to be distributed, such as signatures, SBOMs, attestation, etc. but that references container-related artifacts.

OCI and ORAS

Notation leverages ORAS to store signatures into OCI registries. The ORAS project is a set of tools and libraries that enable to use OCI registries to store arbitray artifacts. But what are OCI Registries?

The Open Container Initiative (OCI) defines the specifications and standards for container technologies. This includes the OCI Distribution Specification, the API for working with container registries. Registries that implement the distribution-spec are referred to as OCI Registries.

OCI and ORAS artifacts

The main OCI artifact type is the OCI image. With time, people used registries to store arbitrary artifacts, leveraging performance, security and reliability capabilities of registries. One growing example is artifacts for securing the sofware supply chain like SBOMS, signatures, attestations, scan results, etc.

The OCI artifacts project aims to generalize the artifact types that can be distributed by and stored into OCI registries. The image manifest has a config.mediaType field to differentiate between the various types of artifacts. This field is supposed to be filled by the authors of new artifact types, so ORAS did to support a wide range of artifact types.

It introduced the ORAS artifact specification and related application/vnd.cncf.oras.artifact.manifest.v1+json mediaType. This media type bases on the OCI image manifest but removes constraints such as a required config object and required & ordinal layers (more on the OCI image manifest spec here).

The ORAS artifact manifest adds a subject property supporting a graph of independently linked artifacts. It provides a means to define artifacts that can be related to an OCI image manifest, OCI image index or another ORAS artifact manifest (for example here a Notary V2 signature that references an image). By defining a new manifest, registries and clients opt-into new capabilities, without breaking existing behaviour, such as discovery provided by the ORAS referrers API.

Quickstart

Requirements

Run the demo

Run a local ORAS OCI regsitry:

export PORT=5000
export REGISTRY=localhost:${PORT}
docker run -d -p ${PORT}:5000 ghcr.io/oras-project/registry:v0.0.3-alpha

Build and push an OCI image to the local registry with a tag:

export REPO=${REGISTRY}/net-monitor
export IMAGE=${REPO}:v1
docker build -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main
docker push $IMAGE

See how the image is not signed (the are no signing artifacts on the local repository that reference the just pushed image):

notation list --plain-http $IMAGE

Generate a certificate key pair to sign the image:

notation cert generate-test --default "wabbit-networks.io"

Sign the image with the certificate key just created:

notation sign --plain-http $IMAGE

Now you need to configure the trust policy to specify trusted identities which sign the artifacts, and level of signature verification to use:

cat <<"EOF" > ~/.config/notation/trustpolicy.json
{
"version": "1.0",
"trustPolicies": [
{
"name": "wabbit-networks-images",
"registryScopes": [ "*" ],
"signatureVerification": {
"level" : "strict"
},
"trustStores": [ "ca:wabbit-networks.io" ],
"trustedIdentities": [
"*"
]
}
]
}
EOF

Verify that the image is signed, against the trust store.

notation verify --plain-http $IMAGE

But now, let’s get more detail and see what is a signature.

Inpspect the signature artifacts

As of now of Notation v0.12 a signature is an ORAS artifact-spec compatible OCI image, on an OCI registry that references an OCI image. As a digest makes unique an artifact (i.e. an image), the subject field of the signature image manifest references the signing content.

Let’s check that on our local registry!

Inspect with ORAS CLI

First, install a ORAS CLI release with version < 0.16.0.

Later we’ll see why not 0.16.

$ oras discover $IMAGE -o json
{
"referrers": [
{
"digest": "sha256:6131e049f4e045614d575ade11e9c9b44e6b7fb081fdd0b8a27f1726329eb5ab",
"mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json",
"artifactType": "application/vnd.cncf.notary.v2.signature",
"size": 512
},
{
"digest": "sha256:cdb664bc205fccbfc06cff7310ea42fe8cf483deb2c9e77a3c829c5d3ecde037",
"mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json",
"artifactType": "application/vnd.cncf.notary.v2.signature",
"size": 512
}
]
}

And you can see that the artifacts digests match the signatures pushed by Notation.

Now let’s see how is composed a application/vnd.cncf.notary.v2.signature manifest, by picking the first signature:

$ oras manifest fetch ${REPO}@$(oras discover $IMAGE -o json | jq -r '.referrers[0].digest') \
 | jq
{
"mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json",
"artifactType": "application/vnd.cncf.notary.v2.signature",
"blobs": [
{
"mediaType": "application/jose+json",
"digest": "sha256:187e7739f84c8b7770dacfda80917ac1c671b92de192bdadf16c87ca0611d846",
"size": 2120
}
],
"subject": {
"mediaType": "application/vnd.docker.distribution.manifest.v2+json",
"digest": "sha256:79cf36c749e0e7445335567b97719bddaf57d0f465f9f36bcbe7ce0a25d02ec6",
"size": 942
},
"annotations": {
"io.cncf.oras.artifact.created": "2022-11-14T18:38:51Z"
}
}

As you can see the subject field references the Docker image manifest v2 of the signed image.

Show me the code

Now let’s see what the notation sign command does. runSign() is the core part of the command:

func runSign(command *cobra.Command, cmdOpts *signOpts) error {
// initialize
 signer, err := cmd.GetSigner(&cmdOpts.SignerFlagOpts)
if err != nil {
return err
}
// core process
 desc, opts, err := prepareSigningContent(command.Context(), cmdOpts)
if err != nil {
return err
}
sig, err := signer.Sign(command.Context(), desc, opts)
if err != nil {
return err
}
// write out
 path := cmdOpts.output
if path == "" {
path = dir.Path.CachedSignature(digest.Digest(desc.Digest), digest.FromBytes(sig))
}
if err := osutil.WriteFile(path, sig); err != nil {
return err
}
if ref := cmdOpts.pushReference; cmdOpts.push && !(cmdOpts.Local && ref == "") {
if ref == "" {
ref = cmdOpts.reference
}
if _, err := pushSignature(command.Context(), &cmdOpts.SecureFlagOpts, ref, sig); err != nil {
return fmt.Errorf("fail to push signature to %q: %v: %v",
ref,
desc.Digest,
err,
)
}
}
fmt.Println(desc.Digest)
return nil
}

First, a signer is fetched. A signer here is a component that signs an artifact and generate and signature.

prepareSigningContent() prepares the manifest descriptor to be signed:

func prepareSigningContent(ctx context.Context, opts *signOpts) (notation.Descriptor, notation.SignOptions, error) {
manifestDesc, err := getManifestDescriptorFromContext(ctx, &opts.RemoteFlagOpts, opts.reference)
if err != nil {
return notation.Descriptor{}, notation.SignOptions{}, err
}
if identity := opts.originReference; identity != "" {
manifestDesc.Annotations = map[string]string{
"identity": identity,
}
}
var tsa timestamp.Timestamper
if endpoint := opts.timestamp; endpoint != "" {
if tsa, err = timestamp.NewHTTPTimestamper(nil, endpoint); err != nil {
return notation.Descriptor{}, notation.SignOptions{}, err
}
}
pluginConfig, err := cmd.ParseFlagPluginConfig(opts.pluginConfig)
if err != nil {
return notation.Descriptor{}, notation.SignOptions{}, err
}
return manifestDesc, notation.SignOptions{
Expiry: cmd.GetExpiry(opts.expiry),
TSA: tsa,
PluginConfig: pluginConfig,
}, nil
}

the signer signs artifacts and generates signatures by delegating the one or more operations to the named plugin that will only generate a raw signature given a payload to sign.

// Sign signs the artifact described by its descriptor and returns the marshalled envelope.
func (s *pluginSigner) Sign(ctx context.Context, desc notation.Descriptor, opts notation.SignOptions) ([]byte, error) {
metadata, err := s.getMetadata(ctx)
if err != nil {
return nil, err
}
if !metadata.SupportsContract(plugin.ContractVersion) {
return nil, fmt.Errorf(
"contract version %q is not in the list of the plugin supported versions %v",
plugin.ContractVersion, metadata.SupportedContractVersions,
)
}
if metadata.HasCapability(plugin.CapabilitySignatureGenerator) {
return s.generateSignature(ctx, desc, opts)
} else if metadata.HasCapability(plugin.CapabilityEnvelopeGenerator) {
return s.generateSignatureEnvelope(ctx, desc, opts)
}
return nil, fmt.Errorf("plugin does not have signing capabilities")
}

Finally, Notation will package this signature into a signature envelope, and generate and pushes the signature manifest, through pushSignature():

func pushSignature(ctx context.Context, opts *SecureFlagOpts, ref string, sig []byte) (notation.Descriptor, error) {
// initialize
 sigRepo, err := getSignatureRepository(opts, ref)
if err != nil {
return notation.Descriptor{}, err
}
manifestDesc, err := getManifestDescriptorFromReference(ctx, opts, ref)
if err != nil {
return notation.Descriptor{}, err
}
// core process
 // pass in nonempty annotations if needed
 sigMediaType, err := envelope.SpeculateSignatureEnvelopeFormat(sig)
if err != nil {
return notation.Descriptor{}, err
}
sigDesc, _, err := sigRepo.PutSignatureManifest(ctx, sig, sigMediaType, manifestDesc, make(map[string]string))
if err != nil {
return notation.Descriptor{}, fmt.Errorf("put signature manifest failure: %v", err)
}
return sigDesc, nil
}

Signing protocols: JOSE and COSE

As a detail, the supported signing protocols are JWS and COSE.

The JOSE Working Group produced a set of documents (RFC7515, RFC7516, RFC7517, RFC7518) that specified how to process encryption, signatures, and Message Authentication Code (MAC) operations and how to encode keys using JSON (like for JWS).

JWS represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures.

COSE describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. CBOR is a data format that was designed specifically to be small in terms of both messages transported and implementation size and to have a schema-free decoder.

CBOR extended the data model of JavaScript Object Notation (JSON) by allowing for binary data directly without first converting it into a base64-encoded text string, among other changes.

COSE is not a direct copy of the JOSE specification. In the process of creating COSE, decisions that were made for JOSE were re-examined.

What’s next

It happened that ORAS worked to unify their artifact specification into a new OCI standard specification (Reference Types for image and distribution specs).

We’re waiting to see a bump in the Notation Go library to support the new Reference Type (and then Notation CLI) of the ORAS Go library (now release candidate v2.0.0-rc.4).

ORAS CLI v0.16.0 already leverages OCI artifacts, and that’s why in this demonstration we picked a previous version, as we demonstrate ORAS Artifact-based signatures.

See you soon with updates on OCI Artifact-based signatures!

Blog: Announcing Notary v2 alpha 1

Tue, 26 Oct 2021 00:00:00 +0000

Notary v1, otherwise known as Docker Content Trust, was released at at a time when there was one primary registry: Docker Hub. A lot has changed since then, some design choices around Trust on First Use (TOFU), key management, and a lack of content promotion within and across registries have become limiting factors for Docker Content Trust and Notary v1.

At KubeCon EU 2019, container image signing was the main topic of interest for a small group in the community. By December 2019, a multi-cloud, multi-vendor meeting kicked off Notary v2, as it was clear the time had come to solve the container image signing problem. Since 2019, multiple prototypes have been built validating the intended experiences around the Notary v2 goals, including how The Update Framework metadata can be partitioned, supporting content promotion.

Today, we are happy to announce the alpha 1 release of the Notary v2 project is ready for your feedback.

Notary v2 enables signing of all artifacts (Container Images, Software Bill of Materials, Scan Results) stored in OCI Distribution based registries, with ORAS artifacts spec enhancements. A key tenet of Notary v2 is that it enables promotion of signed artifacts within and across registries, including air-gapped and private network environments.

In addition to signature promotion, Notary v2 focuses on ease of use, with minimal dependencies. While Notary v2 can integrate with other supply chain efforts, there are no additional services required to sign or validate an artifact. As artifacts get promoted, users/entities may add new signatures, attesting to the validity of the content for the target environment, enabling a secure supply chain workflow.

Through signing, users choose the artifacts they trust, from the entities they trust, decoupling location from identity.

The Notary v2 Alpha includes the following releases:

notation - CLI enabling test-cert creation, cert/key configuration, sign and verify capabilities.
notation-go-lib - a set of Go libraries that may be incorporated into other tools, providing sign, configuration and verify capabilities.
Notary v2 specs - providing the specifications, such as the signature specification

To get a sense for how users can use the notation cli, we’ll walk through a few quick examples.

Sign & Verify

Signing and verification with the notation cli is as simple as:

export IMAGE=localhost:5000/net-monitor:v1
notation cert generate-test --default "wabbit-networks.io"
notation sign $IMAGE
notation cert add --name "wabbit-networks.io" ~/.config/notation/certificate/wabbit-networks.io.crt
notation verify $IMAGE

Add and Sign other Supply Chain Artifacts

Notary v2 supports signing any artifacts stored in a registry, including SBOMs and Scan Results. Using notation-go-lib, tooling may incorporate these capabilities directly into various artifact CLIs.

export PRIVATE_REGISTRY=localhost:5050
export PRIVATE_REPO=${PRIVATE_REGISTRY}/net-monitor
export PRIVATE_IMAGE=${PRIVATE_REPO}:v1
# Simulate an SBOM
echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json
# Push to the registry with the oras cli
oras push $REPO \
 --artifact-type sbom/example \
 --subject $IMAGE \
 sbom.json:application/json
# Capture the digest of the SBOM, to sign it
SBOM_DIGEST=$(oras discover -o json \
 --artifact-type sbom/example \
 $IMAGE | jq -r ".references[0].digest")
notation sign $REPO@$SBOM_DIGEST
# Generate scan results with snyk
docker scan --json $IMAGE > scan-results.json
cat scan-results.json | jq
# Push the scan results to the registry, referencing the image
oras push $REPO \
 --artifact-type application/vnd.org.snyk.results.v0 \
 --subject $IMAGE \
 scan-results.json:application/json
# Capture the digest of the scan result, to sign the scan results
SCAN_DIGEST=$(oras discover -o json \
 --artifact-type application/vnd.org.snyk.results.v0 \
 $IMAGE | jq -r ".references[0].digest")
notation sign $REPO@$SCAN_DIGEST
# Only 1 tag, representing the one artifact
curl $PRIVATE_REGISTRY/v2/net-monitor/tags/list | jq
# Discover the additional attributes
oras discover -o tree $PRIVATE_IMAGE

Notation Alpha 1 Features

The Notation alpha 1 release supports the following Notary v2 goals:

Offline signature creation
Signatures attesting to authenticity and/or certification
Maintain the original artifact digest and collection of associated tags, supporting existing dev through deployment workflows
Multiple signatures per artifact, enabling the originating vendor signature, public registry certification and user/environment signatures
Signature persistance within an OCI distribution-spec based registry, with oras artifacts spec enhancements
Air-gapped environments, where the originating registry of content is not accessible
Artifact and signature copying within and across OCI distribution-spec based registries, with oras artifacts spec enhancements
Verification of signatures, through a configuration based policy

Future versions of Notation will include:

Certificate revocation
Verification through policy, enabling environment specific validations
OCI Distribution 1.0 support (registries that don’t yet support the oras artifacts spec enhancements)
TUF meta-data support, enabling compromise resilience, revocation of keys and artifacts, and timeliness guarantees

Getting Started

Here are some resources to help get started with Notation and Notary V2:

Notary Project | A set of specifications and tools intended to provide a cross-industry standard for securing software supply chains. – Notary Project

Blog: Ratify Joins the Notary Project - Strengthening Software Supply Chain Security Together!

Why Ratify?

What This Means for the Community

What Should Ratify Users Know

What’s Next?

Blog: Announcing Notation v2.0.0-alpha.1 to enable signing and verification of any arbitrary blob files!

Key Highlights

Breaking Changes

Expanded support for signing any arbitrary blob files

Compliant with OCI v1.1 Standard

Delta CRL Support

Getting Started with Notation v2.0.0-alpha.1

Join us at KubeCon EU in London

Blog: Notary Project Completes Its Second Audit!

Audit Process

Audit Results

Blog: Notary Project announces Notation v1.3.0 and tspclient-go v1.0.0!

Notable Capabilities in these Releases

The first major release of tspclient-go library

Certificate Revocation checking using Certificate Revocation List (CRL)

Get started with Notation v1.3.0

What’s next

Acknowledgements

Blog: Notary Project announces Specification v1.1.0 and Notation v1.2.0!

Deprecation

Notable Capabilities in this Release

Notary Project specifications

Support OCI specification v1.1.0

Support for RFC 3161 compliant timestamping

Other changes

Get started with Notation v1.2.0

What’s next

Acknowledgements

Blog: Bitnami now uses Notation for signing and verifying containers and Helm charts on Docker Hub

Blog: Notary Project announces Notation v1.1.0!

Notable Capabilities in this Release

Easier plugin management functionalities

Specifications

Get started with Notation v1.1.0

What’s next

Acknowledgements

Blog: VMware Tanzu Application Catalog now uses Notation for signing and verifying OCI artifacts

What Tanzu Application Catalog achieves by using Notation

Blog: Notary Project featured on the Enlightning Podcast

Blog: Notary Project announces a major release!

What is Notary Project and Notation?

Notable Capabilities in this Release

Specifications

Signing and verification functionalities

Experimental features

Extensibility: plugin support for Notation

Integration with admission controller for Kubernetes usage

Built-in security

What’s next

Acknowledgements

Try it now

Blog: Announcing results of Notation security audit 2023

Summary of findings

Details by category of findings

Endless data attack can cause resource exhaustion leading to denial of service attack (ADA-NOT-23-1, ADA-NOT-23-2, and ADA-NOT-23-7)

Overwriting a global variable could lead to undefined behavior (ADA-NOT-23-3)

Insufficient documentation and non-descriptive CLI command (ADA-NOT-23-4 and ADA-NOT-23-5)

Validating unintended artifact (ADA-NOT-23-6)

Fuzzing

SLSA

Conclusion

Blog: Notation v1.0.0-RC.7 is available!

What’s new

Notation commands support reading Docker credentials if credentials store is not present

Flag --plain-http was renamed to --insecure-registry

Known issue

Credits

Download and give it a try

Blog: Notation v1.0.0-RC.5 is available!

Major updates in notation CLI and notation-go library

Deprecate flag --signature-manifest in notation sign

Change default behavior and introduce a new flag --allow-referrers-api

Note

Credits

The first major release of `tspclient-go` library

Flag `--plain-http` was renamed to `--insecure-registry`

Deprecate flag `--signature-manifest` in notation sign

Change default behavior and introduce a new flag `--allow-referrers-api`

Introduce switch `NOTATION_EXPERIMENTAL=1` to enable experimental features

Introduce new CLI command `notation policy` to simplify trust policy configuration