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