This page explains advanced uses of Notary client for users who are running their own Notary service. Make sure you have first read and understood how to run your own Notary service before continuing.
This document’s command examples omit the -s
and -d
flags. If you do not know what these options do, read the Getting Started docs or run notary --help
before continuing. Once you understand what these flags do, you must provide your own values for these options while following this document. You can also configure these options, see advanced configuration options for more information.
Before adding and signing content to a collection, you must first initialize that collection.
$ notary init example.com/collection
No root keys found. Generating a new root key...
You are about to create a new root signing key passphrase. This passphrase
is used to protect the most sensitive key in your signing system.
Choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There is no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 1f54328:
Repeat passphrase for new root key with ID 1f54328:
Enter passphrase for new targets key with ID 1df39fc (example.com/collection):
Repeat passphrase for new targets key with ID 1df39fc (example.com/collection):
Initializing a trusted collection generates the following items; all keys use asymmetric algorithms, but there is no requirement that they all use the same algorithm:
root
key is generated. This key is used as the default root of trust for all your trusted collections.targets
key and a snapshot
key. The same password encrypts both of these as the security profile of them (when both held by the author of the trusted collection) is identical. This is why are not prompted for a snapshot key password.timestamp
key. This is generated by the server on a request from the client, returning just the public key. The server holds the private key and signs timestamps on behalf of the user.To add targets to a trusted collection with notary CLI:
$ notary add example.com/collection v1 my_file.txt
This adds the local file my_file.txt
(which must exist relative to the current working directory), under the target name v1
, to the example.com/collection
collection we set up. The contents of the local file are not actually added to the collection - a “target” consists of the file path and one or more checksums of the contents.
This is an offline command, and we must run a notary publish example.com/collection
for the add to take effect.
To remove targets, we use the notary remove
command, specifying the GUN and target name.
$ notary remove example.com/collection v1
Removing a target is also an offline command that requires a notary publish example.com/collection
to take effect.
By default, the notary client is responsible for managing the private keys for root, targets, snapshot roles. All of these keys are generated by default when initializing a new trusted collection. The keys are located in the notary trust_dir
directory. In addition, if delegation roles exist, those roles’ keys are to also managed by the notary client.
The notary server is always responsible for managing the timestamp key. However, it is possible for the notary server to manage the snapshot key, if the snapshot key is rotated from the notary client to server, as described in the following subsection.
In case of potential compromise, notary provides a CLI command for rotating keys. You can use the notary key rotate
command to rotate the targets or snapshot keys.
While the snapshot key is managed by the notary client by default, use the notary key rotate snapshot -r
command to rotate the snapshot key to the server, such that the notary server can sign snapshots. This is particularly useful when using delegations with a trusted collection, so that delegates never need access to the snapshot key to push their updates to the collection.
New collections created by a Docker 1.11 Engine client cause the server manage to the snapshot key by default. To reclaim control of the snapshot key on the client, use the notary key rotate
command without the -r
flag.
The targets key must be locally managed - to rotate the targets key, for instance in case of compromise, use the notary key rotate targets
command without the -r
flag.
Notary can be used with Yubikey 4 keys, via a PKCS11 interface when the Yubikey has CCID mode enabled. The Yubikey is prioritized to store root keys, and requires user touch-input for signing. Yubikey support is included with the Docker Engine 1.11 client for use with Docker Content Trust.
Yubikey support requires Yubico PIV libraries (bundled with the PIV tools) to be available in standard library locations.
Delegation roles simplify collaborator workflows in notary trusted collections, and also allow for fine-grained permissions within a collection’s contents across delegations. In essence, delegation roles are restricted versions of the targets role that are only allowed to sign targets within certain filepaths.
A delegation role is given its own keys, such that each collaborator can keep his own private key without the administrator having to share the targets key or allow a collaborator write access to all targets of the collection.
Before adding any delegations, you should rotate the snapshot key to the server. This is done by default for new collections created with a Docker Engine 1.11 client. Delegation roles do not require the snapshot key to publish their own targets to the collection, since the server can publish the valid snapshot with the delegation targets:
$ notary key rotate example.com/collection snapshot -r
Here, -r
specifies to rotate the key to the remote server.
When adding a delegation, your must acquire a x509 certificate with the public key of the user you wish to delegate to. The user who assumes this delegation role must hold the private key to sign content with notary.
Once you’ve acquired the delegate’s x509 certificate, you can add a delegation for this user:
$ notary delegation add example.com/collection targets/releases cert.pem --paths="delegation/path"
The preceding example illustrates a request to add the delegation targets/releases
to the GUN example.com/collection
. The delegation name must be prefixed by targets/
to be valid, since all delegations are restricted versions of the target role. The command adds the public key contained in the x509 cert cert.pem
to the targets/releases
delegation.
For the targets/releases
delegation role to sign content, the delegation user must possess the private key corresponding to this public key. This command restricts this delegation to only publish content under pathnames prefixed by delegation/path
. With the given path of “delegation/path”, the targets/releases
role could sign paths like “delegation/path/content.txt”, “delegation/path_file.txt” and “delegation/path.txt”. You can add more paths in a comma-separated list under --paths
, or pass the --all-paths
flag to allow this delegation to publish content under any pathname.
After publishing, you can view delegations using a list command:
$ notary delegation list example.com/collection
ROLE PATHS KEY IDS THRESHOLD
---------------------------------------------------------------------------------------------------------------
targets/releases delegation/path 729c7094a8210fd1e780e7b17b7bb55c9a28a48b871b07f65d97baf93898523a 1
You can see the targets/releases
with its paths and key IDs. If you wish to modify these fields, you can do so with additional notary delegation add
or notary delegation remove
commands on this role.
A threshold of 1
indicates that only one of the keys specified in KEY IDS
is required to publish to this delegation. Thresholds other than 1 are not currently supported. To remove a delegation role entirely, or just individual keys and/or paths, use the notary delegation remove
command:
$ notary delegation remove example.com/user targets/releases
Are you sure you want to remove all data for this delegation? (yes/no)
yes
Forced removal (including all keys and paths) of delegation role targets/releases to repository "example.com/user" staged for next publish.
You can remove individual keys and/or paths by passing keys as arguments, and/or paths under the --paths
flag. Use --all-paths
to clear all paths for this role. If you specify all key IDs currently in the delegation role, you delete the role entirely.
To add targets to a specified delegation role, we can use the notary add
command with the --roles
flag.
You must have imported an appropriate delegation key for this role. To do so, you can run notary key import <KEY_FILE> --role user
with the private key PEM file, or drop the private key PEM in private/tuf_keys
as <KEY_ID>.key
with the role
PEM header set to user
.
$ notary add example/collections delegation/path/target delegation_file.txt --roles=targets/releases
In the preceding example, you add the target delegation/path/target
to collection example/collections
staged for next publish. The file delegation_file.txt
is a target delegation/path/target
using the delegation role targets/releases
. This target’s path is valid because it is prefixed by the delegation role’s valid path.
The notary list
and notary remove
commands can also take the --roles
flag to specify roles to list or remove targets from. By default, this operates over the base targets
role.
To remove this target from our delegation, use the notary remove
command with the same flag:
$ notary remove example/collections delegation/path/target --roles=targets/releases
Docker Engine 1.10 and above supports the usage of the targets/releases
delegation as the canonical source of a trusted image tag, if it exists.
When running docker pull
with Docker Content Trust on Docker Engine 1.10, Docker attempts to search the targets/releases
role for the signed image tag, and falls back to the default targets
role if it does not exist. When searching the default targets
role, Docker 1.10 may pick up on other non-targets/releases
delegation roles’ signed images if they exist for this tag. In Docker 1.11, this behavior is changed such that all docker pull
commands with Docker Content Trust must pull tags only signed by the targets/releases
delegation role or the targets
base role.
When running docker push
with Docker Content Trust, Docker Engine 1.10 attempts to sign and push with the targets/releases
delegation role if it exists, otherwise falling back to the targets
role. In Docker 1.11, a docker push
attempts to sign and push with all delegation roles directly under targets (ex: targets/role
but not targets/nested/role
) that the user has signing keys for. If delegation roles exist but the user does not have signing keys, the push fails. If no delegation roles exist, the push attempts to sign with the base targets
role.
To use the targets/releases
role for pushing and pulling images with content trust, follow the steps above to add and publish the delegation role with notary. When adding the delegation, the --all-paths
flag should be used to allow signing all tags.
Notary stores state in its trust_dir
directory, which is ~/.notary
by default or usually ~/.docker/trust
when enabling docker content trust. Within this directory, trusted_certificates
stores certificates for bootstrapping trust in a collection, tuf
stores TUF metadata and changelists to be applied to a GUN, and private
stores private keys.
The root_keys
subdirectory within private
stores root private keys, while tuf_keys
stores targets, snapshots, and delegations private keys.
docker, notary, notary-client, docker content trust, content trust, power user, advanced
© 2019 Docker, Inc.
Licensed under the Apache License, Version 2.0.
Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.
Docker, Inc. and other parties may also have trademark rights in other terms used herein.
https://docs.docker.com/notary/advanced_usage/