Notary (software)

Notary (software)
Name	Notary
Title	Notary
Developer	Docker, Inc.; Cloud Native Computing Foundation
Released	2015
Programming language	Go
Operating system	Cross-platform
License	Apache License 2.0

Notary (software) Notary is a tool for publishing and verifying content trust metadata for container images and other artifacts. It enables maintainers to sign and distribute cryptographic metadata that clients can use to verify authenticity and integrity of artifacts retrieved from registries, package repositories, or content-addressable stores. Notary integrates with container ecosystems and signing workflows and was developed to address supply-chain concerns raised by high-profile incidents in software distribution.

Overview

Notary provides a metadata layer that sits adjacent to artifact storage services such as container registries and package repositories. It implements a signing and verification protocol inspired by widely cited secure distribution initiatives and threat analyses, aligning with mitigation patterns used in projects like Docker (software), Kubernetes, The Update Framework, OpenSSL-based ecosystems, and cloud provider signing solutions. Notary's design separates signing duties from storage responsibilities to reduce risks associated with key compromise, similar to approaches advocated in reports by National Institute of Standards and Technology and advisories from United States Cybersecurity and Infrastructure Security Agency.

Architecture and components

Notary is composed of a server component and a client command-line tool. The server implements a metadata store and provides endpoints compatible with the Notary API; the client issues signing, publishing, and verification operations. Core components include a metadata database, a signing service that handles offline and online keys, and a delegations mechanism to partition signing authority across teams or services. The architecture uses content-addressable digests produced by tools like rkt, Docker Engine, and OCI-compliant runtimes, and it commonly interoperates with registries such as Docker Hub, private Registry implementations, and enterprise artifact repositories like Harbor (software) and JFrog Artifactory.

Notary's deployment patterns mirror distributed system practices found in projects such as etcd and Consul (software), often relying on object storage or relational backends, load balancers used in Amazon Web Services, Google Cloud Platform, and Microsoft Azure deployments, and integration with identity systems like OAuth 2.0 providers, LDAP, and OpenID Connect.

Security model and cryptographic primitives

Notary's threat model emphasizes key compromise, replay attacks, and rollback attacks that have been analyzed in formal treatments like The Update Framework and advisories from CERT Coordination Center. The design uses asymmetric cryptography, typically implementing Ed25519 or RSA keys, with signatures over canonical serialized metadata. Notary relies on secure hash algorithms such as SHA-256 to produce content digests and to bind metadata to artifact payloads.

A distinctive element is separation of trust: root keys, targets keys, and snapshot/ timestamp keys provide role-based cryptographic separation inspired by TUF. The metadata format supports versioning and revocation semantics to prevent rollback attacks, and timestamps mitigate replay risks in the face of slow propagation. Notary deployments often integrate with hardware-backed key stores such as YubiKey, AWS KMS, Google Cloud KMS, and Azure Key Vault for enhanced protection against exfiltration. The project also acknowledges the need to rotate keys following guidance from NIST Special Publications and industry standards such as those produced by the IETF.

Use cases and integrations

Notary is used to sign container images, software packages, and binary artifacts in continuous delivery pipelines that incorporate systems like Jenkins, GitLab CI/CD, GitHub Actions, Azure DevOps, and Tekton (project). Integrations include signing hooks in build systems such as Bazel (build tool), Maven, and npm, and verification steps embedded in runtime platforms like Kubernetes admission controllers and OpenShift policy modules. Enterprise use often ties Notary verification into runtime authorization and policy enforcement products from vendors like Palo Alto Networks, Aqua Security, and Twistlock.

Notary also appears in software supply chain hardening initiatives championed by groups such as the Cloud Native Computing Foundation's SIGs and programs like sigstore, where comparable goals—to provide provenance, signing, and verification—are pursued. It can be used in concert with provenance formats like in-toto and attestation frameworks such as SLSA.

Development history and governance

Notary originated from work by Docker, Inc. to provide image signing and content trust capabilities and was first released in the mid-2010s. The project adopted design principles from academic and standards work including researchers at New York University, University of California, Berkeley, and the secure update community that produced The Update Framework. Governance transitioned toward open-source stewardship with involvement from the Cloud Native Computing Foundation ecosystem and contributors from companies including Google, IBM, Red Hat, and Amazon Web Services. Roadmap and maintenance have at times followed the governance patterns used by CNCF projects and other collaborative foundations such as Linux Foundation-hosted initiatives.

Development activity has produced forks and complementary projects; communities around supply-chain security have proposed successors and alternatives where different trust models or improved UX were desired, leading to new work under organizations including sigstore and vendor-specific efforts.

Adoption, deployments, and limitations

Adoption of Notary occurred primarily among users of Docker Hub, private registries, and enterprises seeking image provenance. Notable deployments included container registries used in large-scale cloud-native platforms and CI/CD pipelines at organizations adopting Kubernetes and OCI tooling. Limitations cited in community discussions include operational complexity of key management, scalability constraints for high-frequency metadata updates, and usability friction for teams unfamiliar with cryptographic workflows. These trade-offs motivated subsequent projects and standards work addressing developer experience, automated key lifecycle management, and tighter integration with cloud-native identity systems.

Despite adoption, some organizations migrated to newer models emphasizing ephemeral keys, transparency logs, and simpler signing UX implemented by projects associated with sigstore and industry initiatives such as SLSA, reflecting evolving best practices in software supply chain security.

Category:Software security