atomic-trust (1) - Linux Manuals

atomic-trust: Manage system container trust policy

NAME

atomic-trust - Manage system container trust policy

SYNOPSIS

atomic trust add|delete|default|reset|show [-h|--help] [-j|--json] [--raw] [-k|--pubkeys KEY1 [-k|--pubkeys KEY2,...]] [-f|--pubkeysfile KEY1 [f|--pubkeysfile KEY2,...]] [--keytype GPGKeys] [-t|--type signedBy|insecureAcceptAnything|reject] [-s|--sigstore <https://URL[:PORT][/PATH]|file:///PATH>] [--sigstoretype web|atomic|local] REGISTRY[/REPOSITORY]

DESCRIPTION

atomic trust manages the trust policy of the host system. Trust policy describes a registry scope (registry and/or repository) that must be signed by public keys. Trust is defined in /etc/containers/policy.json. Trust is enforced when a user attempts to pull an image from a registry.

Trust scope is evaluated by most specific to least specific. In other words, policy may be defined for an entire registry, but refined for a particular repository in that registry. See below for examples.

Trust type provides a way to whitelist ("insecureAcceptAnything") or blacklist ("reject") registries.

Signature servers, or sigstores, configure where image signatures are served for a particular registry scope. This cofiguration is a flat list of arbitrarily named YAML files in /etc/containers/registries.d/. Filenames must end in .yaml. A sigstore may be either an absolute path to a local directory (file:///PATH) or a remote web server ( <https://URL>).

Trust may be updated using the command atomic trust add for an existing trust scope.

The default trust policy is managed by the default command. Options are accept or reject.

The default /etc/containers/policy.json file may be overriden using environment variable TRUST_POLICY. This is typically only useful for testing.

OPTIONS

-h --help
  Print usage statement.

-k --pubkeys
  A reference to a local file, download URL to an exported public key or a
  local user GPG keyring ID (see output of 'gpg2 --list-keys'). Keys are
  parsed and encoded inline with policy.json. Option may be used multiple
  times to require an image be sigend by multiple keys. One of
  --pubkeys or --pubkeysfile is required for signedBy type. This
  option is recommended over --pubkeysfile.

-f --pubkeysfile
  A path to an exported public key on the local system. Key paths
  will be referenced in policy.json. Any path may be used but path
  /etc/pki/containers is recommended. Option may be used multiple times to
  require an image be sigend by multiple keys. One of --pubkeys or
  --pubkeysfile is required for signedBy type.

--keytype
  The public key type. Default: GPGKeys (only supported value)

-t --type
  The trust type for this policy entry. Accepted values:
 signedBy (default): Require signatures with corresponding list of
                      public keys
 insecureAcceptAnything: do not require any signatures for this
                          registry scope
 reject: do not accept images for this registry scope

-u --sigstore
  A path or remote URL where signatures are found. Prefix filesystem path with
  file:///PATH and remote web server with  <https://URL[:PORT][/PATH/TO/SIGNATURES>].

-s --sigstoretype
  Type of signature transport. Accepted values:
 web (default): remote web server
 atomic: OpenShift-based Atomic Registry API
 local: Local filesystem path

delete OPTIONS

--save-sigstore
  Do not remove local sigstore configuration.

default OPTIONS

The default trust policy is managed by the default command. Options are accept or reject.

show OPTIONS

--raw
  Output trust policy file as raw JSON

-j --json
  Output trust as JSON for machine parsing

reset

Resets policy.json to the default. Removes all YAML files in
  /etc/containers/registries.d/ except default.yaml.

EXAMPLES

Add public key trust to specific registry repository

atomic trust add \
       --pubkeys /etc/pki/containers/foo [at] example.com \
       --sigstore https://s3.bucket/foobar/sigstore/ \
       docker.io/foobar

Modify a trust scope, adding a second public key and changing the sigstore web server

atomic trust add \
       --pubkeys https://example.com/keys/example.pub \
       --pubkeys /etc/pki/containers/foo [at] example.com \
       --sigstore https://server.example.com/foobar/sigstore/ \
       docker.io/foobar

Accept all unsigned images from a registry

atomic trust add --type insecureAcceptAnything docker.io

Remove a trust scope

atomic trust delete docker.io

Remove a trust scope but retain the sigstore configuration

atomic trust delete docker.io --sigstore

Modify default trust policy

atomic trust default reject

Display system trust policy

atomic trust show

Display trust policy file

atomic trust show --raw

Display trust as JSON

atomic trust show --json

HISTORY

September 2016, originally compiled by Aaron Weitekamp (aweiteka at redhat dot com)