6f9067
% CONTAINERS-POLICY.JSON(5) policy.json Man Page
d82e54
% Miloslav Trmač
d82e54
% September 2016
d82e54
d82e54
# NAME
6f9067
containers-policy.json - syntax for the signature verification policy file
d82e54
d82e54
## DESCRIPTION
d82e54
d82e54
Signature verification policy files are used to specify policy, e.g. trusted keys,
d82e54
applicable when deciding whether to accept an image, or individual signatures of that image, as valid.
d82e54
d82e54
The default policy is stored (unless overridden at compile-time) at `/etc/containers/policy.json`;
d82e54
applications performing verification may allow using a different policy instead.
d82e54
d82e54
## FORMAT
d82e54
d82e54
The signature verification policy file, usually called `policy.json`,
d82e54
uses a JSON format.  Unlike some other JSON files, its parsing is fairly strict:
d82e54
unrecognized, duplicated or otherwise invalid fields cause the entire file,
d82e54
and usually the entire operation, to be rejected.
d82e54
d82e54
The purpose of the policy file is to define a set of *policy requirements* for a container image,
d82e54
usually depending on its location (where it is being pulled from) or otherwise defined identity.
d82e54
d82e54
Policy requirements can be defined for:
d82e54
d82e54
- An individual *scope* in a *transport*.
d82e54
  The *transport* values are the same as the transport prefixes when pushing/pulling images (e.g. `docker:`, `atomic:`),
d82e54
  and *scope* values are defined by each transport; see below for more details.
d82e54
d82e54
  Usually, a scope can be defined to match a single image, and various prefixes of
d82e54
  such a most specific scope define namespaces of matching images.
d82e54
- A default policy for a single transport, expressed using an empty string as a scope
d82e54
- A global default policy.
d82e54
d82e54
If multiple policy requirements match a given image, only the requirements from the most specific match apply,
d82e54
the more general policy requirements definitions are ignored.
d82e54
d82e54
This is expressed in JSON using the top-level syntax
d82e54
```js
d82e54
{
d82e54
    "default": [/* policy requirements: global default */]
d82e54
    "transports": {
d82e54
        transport_name: {
d82e54
            "": [/* policy requirements: default for transport $transport_name */],
d82e54
            scope_1: [/* policy requirements: default for $scope_1 in $transport_name */],
d82e54
            scope_2: [/*…*/]
d82e54
            /*…*/
d82e54
        },
d82e54
        transport_name_2: {/*…*/}
d82e54
        /*…*/
d82e54
    }
d82e54
}
d82e54
```
d82e54
d82e54
The global `default` set of policy requirements is mandatory; all of the other fields
d82e54
(`transports` itself, any specific transport, the transport-specific default, etc.) are optional.
d82e54
d82e54
d82e54
## Supported transports and their scopes
d82e54
d82e54
### `atomic:`
d82e54
d82e54
The `atomic:` transport refers to images in an Atomic Registry.
d82e54
d82e54
Supported scopes use the form _hostname_[`:`_port_][`/`_namespace_[`/`_imagestream_ [`:`_tag_]]],
d82e54
i.e. either specifying a complete name of a tagged image, or prefix denoting
d82e54
a host/namespace/image stream.
d82e54
d82e54
*Note:* The _hostname_ and _port_ refer to the Docker registry host and port (the one used
d82e54
e.g. for `docker pull`), _not_ to the OpenShift API host and port.
d82e54
d82e54
### `dir:`
d82e54
d82e54
The `dir:` transport refers to images stored in local directories.
d82e54
d82e54
Supported scopes are paths of directories (either containing a single image or
d82e54
subdirectories possibly containing images).
d82e54
d82e54
*Note:* The paths must be absolute and contain no symlinks. Paths violating these requirements may be silently ignored.
d82e54
d82e54
The top-level scope `"/"` is forbidden; use the transport default scope `""`,
d82e54
for consistency with other transports.
d82e54
d82e54
### `docker:`
d82e54
d82e54
The `docker:` transport refers to images in a registry implementing the "Docker Registry HTTP API V2".
d82e54
d82e54
Scopes matching individual images are named Docker references *in the fully expanded form*, either
d82e54
using a tag or digest. For example, `docker.io/library/busybox:latest` (*not* `busybox:latest`).
d82e54
d82e54
More general scopes are prefixes of individual-image scopes, and specify a repository (by omitting the tag or digest),
d82e54
a repository namespace, or a registry host (by only specifying the host name).
d82e54
d82e54
### `oci:`
d82e54
d82e54
The `oci:` transport refers to images in directories compliant with "Open Container Image Layout Specification".
d82e54
d82e54
Supported scopes use the form _directory_`:`_tag_, and _directory_ referring to
d82e54
a directory containing one or more tags, or any of the parent directories.
d82e54
d82e54
*Note:* See `dir:` above for semantics and restrictions on the directory paths, they apply to `oci:` equivalently.
d82e54
d82e54
### `tarball:`
d82e54
d82e54
The `tarball:` transport refers to tarred up container root filesystems.
d82e54
d82e54
Scopes are ignored.
d82e54
d82e54
## Policy Requirements
d82e54
d82e54
Using the mechanisms above, a set of policy requirements is looked up.  The policy requirements
d82e54
are represented as a JSON array of individual requirement objects.  For an image to be accepted,
d82e54
*all* of the requirements must be satisfied simulatenously.
d82e54
d82e54
The policy requirements can also be used to decide whether an individual signature is accepted (= is signed by a recognized key of a known author);
d82e54
in that case some requirements may apply only to some signatures, but each signature must be accepted by *at least one* requirement object.
d82e54
d82e54
The following requirement objects are supported:
d82e54
d82e54
### `insecureAcceptAnything`
d82e54
d82e54
A simple requirement with the following syntax
d82e54
d82e54
```json
d82e54
{"type":"insecureAcceptAnything"}
d82e54
```
d82e54
d82e54
This requirement accepts any image (but note that other requirements in the array still apply).
d82e54
d82e54
When deciding to accept an individual signature, this requirement does not have any effect; it does *not* cause the signature to be accepted, though.
d82e54
d82e54
This is useful primarily for policy scopes where no signature verification is required;
d82e54
because the array of policy requirements must not be empty, this requirement is used
d82e54
to represent the lack of requirements explicitly.
d82e54
d82e54
### `reject`
d82e54
d82e54
A simple requirement with the following syntax:
d82e54
d82e54
```json
d82e54
{"type":"reject"}
d82e54
```
d82e54
d82e54
This requirement rejects every image, and every signature.
d82e54
d82e54
### `signedBy`
d82e54
d82e54
This requirement requires an image to be signed with an expected identity, or accepts a signature if it is using an expected identity and key.
d82e54
d82e54
```js
d82e54
{
d82e54
    "type":    "signedBy",
d82e54
    "keyType": "GPGKeys", /* The only currently supported value */
d82e54
    "keyPath": "/path/to/local/keyring/file",
d82e54
    "keyData": "base64-encoded-keyring-data",
d82e54
    "signedIdentity": identity_requirement
d82e54
}
d82e54
```
d82e54
d82e54
d82e54
Exactly one of `keyPath` and `keyData` must be present, containing a GPG keyring of one or more public keys.  Only signatures made by these keys are accepted.
d82e54
d82e54
The `signedIdentity` field, a JSON object, specifies what image identity the signature claims about the image.
d82e54
One of the following alternatives are supported:
d82e54
d82e54
- The identity in the signature must exactly match the image identity.  Note that with this, referencing an image by digest (with a signature claiming a _repository_`:`_tag_ identity) will fail.
d82e54
d82e54
  ```json
d82e54
  {"type":"matchExact"}
d82e54
  ```
d82e54
- If the image identity carries a tag, the identity in the signature must exactly match;
d82e54
  if the image identity uses a digest reference, the identity in the signature must be in the same repository as the image identity (using any tag).
d82e54
d82e54
  (Note that with images identified using digest references, the digest from the reference is validated even before signature verification starts.)
d82e54
d82e54
  ```json
d82e54
  {"type":"matchRepoDigestOrExact"}
d82e54
  ```
d82e54
- The identity in the signature must be in the same repository as the image identity.  This is useful e.g. to pull an image using the `:latest` tag when the image is signed with a tag specifing an exact image version.
d82e54
d82e54
  ```json
d82e54
  {"type":"matchRepository"}
d82e54
  ```
d82e54
- The identity in the signature must exactly match a specified identity.
d82e54
  This is useful e.g. when locally mirroring images signed using their public identity.
d82e54
d82e54
  ```js
d82e54
  {
d82e54
      "type": "exactReference",
d82e54
      "dockerReference": docker_reference_value
d82e54
  }
d82e54
  ```
d82e54
- The identity in the signature must be in the same repository as a specified identity.
d82e54
  This combines the properties of `matchRepository` and `exactReference`.
d82e54
d82e54
  ```js
d82e54
  {
d82e54
      "type": "exactRepository",
d82e54
      "dockerRepository": docker_repository_value
d82e54
  }
d82e54
  ```
d82e54
d82e54
If the `signedIdentity` field is missing, it is treated as `matchRepoDigestOrExact`.
d82e54
d82e54
*Note*: `matchExact`, `matchRepoDigestOrExact` and `matchRepository` can be only used if a Docker-like image identity is
d82e54
provided by the transport.  In particular, the `dir:` and `oci:` transports can be only
d82e54
used with `exactReference` or `exactRepository`.
d82e54
d82e54
d82e54
d82e54
## Examples
d82e54
d82e54
It is *strongly* recommended to set the `default` policy to `reject`, and then
d82e54
selectively allow individual transports and scopes as desired.
d82e54
d82e54
### A reasonably locked-down system
d82e54
d82e54
(Note that the `/*`…`*/` comments are not valid in JSON, and must not be used in real policies.)
d82e54
d82e54
```js
d82e54
{
d82e54
    "default": [{"type": "reject"}], /* Reject anything not explicitly allowed */
d82e54
    "transports": {
d82e54
        "docker": {
d82e54
            /* Allow installing images from a specific repository namespace, without cryptographic verification.
d82e54
               This namespace includes images like openshift/hello-openshift and openshift/origin. */
d82e54
            "docker.io/openshift": [{"type": "insecureAcceptAnything"}],
d82e54
            /* Similarly, allow installing the “official” busybox images.  Note how the fully expanded
d82e54
               form, with the explicit /library/, must be used. */
d82e54
            "docker.io/library/busybox": [{"type": "insecureAcceptAnything"}]
d82e54
            /* Other docker: images use the global default policy and are rejected */
d82e54
        },
d82e54
        "dir": {
d82e54
            "": [{"type": "insecureAcceptAnything"}] /* Allow any images originating in local directories */
d82e54
        },
d82e54
        "atomic": {
d82e54
            /* The common case: using a known key for a repository or set of repositories */
d82e54
            "hostname:5000/myns/official": [
d82e54
                {
d82e54
                    "type": "signedBy",
d82e54
                    "keyType": "GPGKeys",
d82e54
                    "keyPath": "/path/to/official-pubkey.gpg"
d82e54
                }
d82e54
            ],
d82e54
            /* A more complex example, for a repository which contains a mirror of a third-party product,
d82e54
               which must be signed-off by local IT */
d82e54
            "hostname:5000/vendor/product": [
d82e54
                { /* Require the image to be signed by the original vendor, using the vendor's repository location. */
d82e54
                    "type": "signedBy",
d82e54
                    "keyType": "GPGKeys",
d82e54
                    "keyPath": "/path/to/vendor-pubkey.gpg",
d82e54
                    "signedIdentity": {
d82e54
                        "type": "exactRepository",
d82e54
                        "dockerRepository": "vendor-hostname/product/repository"
d82e54
                    }
d82e54
                },
d82e54
                { /* Require the image to _also_ be signed by a local reviewer. */
d82e54
                    "type": "signedBy",
d82e54
                    "keyType": "GPGKeys",
d82e54
                    "keyPath": "/path/to/reviewer-pubkey.gpg"
d82e54
                }
d82e54
            ]
d82e54
        }
d82e54
    }
d82e54
}
d82e54
```
d82e54
d82e54
### Completely disable security, allow all images, do not trust any signatures
d82e54
d82e54
```json
d82e54
{
d82e54
    "default": [{"type": "insecureAcceptAnything"}]
d82e54
}
d82e54
```
6f9067
## SEE ALSO
d82e54
  atomic(1)
d82e54
6f9067
## HISTORY
6f9067
August 2018, Rename to containers-policy.json(5) by Valentin Rothberg <vrothberg@suse.com>
6f9067
d82e54
September 2016, Originally compiled by Miloslav Trmač <mitr@redhat.com>