Docker Security Team

Notary 0.2 – Delegations and more!

Docker Security Team

The Notary ™ project has been continuing to forge towards 1.0 and we’re pleased to announce our 0.2 release. In addition to various minor improvements and bugfixes we have added some significant features. Read on to find out more!


Up to now, collaboration in Notary has only been achievable via key sharing, which also necessitates giving other contributors unrestricted authorization to sign new image tags. While there were mechanisms to recover, it was a less than optimal situation.

Delegations enable a repository administrator to both segment and restrict individual contributor authorization. A delegation is a special role within Notary with its own set of keys, such that targets keys do not need to be shared.

Here’s a demo of delegations in action, using the targets/releases role to collaborate on pushing with Docker Content Trust:

In Docker 1.10, if the targets/releases role exists, your tags will automatically be using delegations with Docker Content Trust. With Notary 0.2, you’re free to make as many delegations as your heart desires, so jump right in and notary delegation add all you’d like!


Server snapshot signing

Until recently, users had to manage the root (offline) key, as well as the targets and snapshot keys (the two repository keys) for a repository. The Notary Server has always been responsible for managing the timestamp key and generating timestamps certifying the freshness of a repository.

Notary now supports rotating the snapshot key to become a server-managed key just like the timestamp key. Notary Server can now be responsible for generating and signing snapshots of the repository. This is a necessary feature to support delegations without requiring a repository owner to also share snapshot keys with delegated collaborators. Please see the demo above to see the server snapshot key rotation in conjunction with key delegation.


Consistent Downloads

Notary Server now supports consistent (content-addressable) download endpoints. Previously, a client could only pull the latest version of any metadata. On a very active repository, this metadata is very dynamic, and hence cached metadata would often be invalidated.

Now, any version of the metadata can be downloaded by its checksum. A client downloads the latest version of the timestamp metadata, which contains the checksum of the corresponding snapshot metadata. This checksum is different for every version of the snapshot metadata, meaning that the snapshot document with that checksum will never change, and can be cached forever, reducing load on the Notary Server.

For example, here is a sample NGINX caching reverse proxy configuration, where in the upstream block, server:4443 refers to the notary-server container, port 4443:

worker_processes 1;
events {
  worker_connections 1024;
http {
    proxy_cache_path  /tmp  levels=1:2    keys_zone=STATIC:10m
inactive=24h  max_size=1g;
    upstream backend {
      server server:4443;
    server {
      location ~ ^/v2/(.+)/_trust/tuf/(.+)\.([a-zA-Z0-9]+)\.json$ {
                proxy_set_header      Host $host;
                add_header            X-Proxy-Cache     $upstream_cache_status;
                proxy_cache           STATIC;
                proxy_cache_valid     200   30d;    
                proxy_cache_use_stale error timeout     invalid_header updating
                                                        http_500 http_502 http_503 http_504;
                proxy_pass            https://backend;
      location ~ ^/v2(.+)$ {
                proxy_pass https://backend;

In the future, this feature will enable downloading historical versions of a repository.


Official Server and Signer Images

With the release of Notary 0.2, we have also released official images of the Notary Server and Signer applications. This makes it easier for the security-minded to run their own Notary service to sign any data of their choosing. Both images can be found in the official notary repository on Docker Hub. All server images are prefixed with “server”, and similarly all signer images are prefixed with “signer”. The latest versions of each application are published as simply “server” and “signer” with no additional version.

While the official images come with a default configuration file (detailed in the hub), we highly recommend you mount your own configuration file into the container and pass it to the server or signer application.

$ docker run -v ./config/:/config/ notary:server -config=/config/server-config.json

While the notary github repository includes certificate and key fixtures, these are for local development and testing use only: you must also acquire and include your own root CA certificate, and certificates and keys for both the server and signer applications. These should be mounted into the containers in the location your configuration file specifies. While it is possible, and in some cases preferable to have the notary server speak plain HTTP to the outside world (for example, if your load balancer is doing TLS termination), the server and signer should always be configured to perform mutual TLS. This helps ensure the security of your signing and key generation operations.

The official images support HTTP Basic Authentication, and a token based authentication scheme. If you wish to use the token authentication scheme, you will have to provide your own token server. Notary uses the same token specification as the Docker Registry V2, for which the specification can be found here.


Learn More about Docker


2 thoughts on “Notary 0.2 – Delegations and more!

  1. Very good article, congratulations. I would like to ask you a simple question. When I upload an image from another host it is necessary to have notary installed completely or only the notary client ?. From already thank you very much.

Leave a Reply