1CONTAINERS-POLICY.JSON(5)(policy.json) CONTAINERS-POLICY.JSON(5)(policy.json)
2Miloslav Trmač September 2016
6
9 containers-policy.json - syntax for the signature verification policy
10 file
11
14 Signature verification policy files are used to specify policy, e.g.
15 trusted keys, applicable when deciding whether to accept an image, or
16 individual signatures of that image, as valid.
17 The default policy is stored (unless overridden at compile-time) at
20 /etc/containers/policy.json; applications performing verification may
21 allow using a different policy instead.
22
25 The signature verification policy file, usually called policy.json,
26 uses a JSON format. Unlike some other JSON files, its parsing is
27 fairly strict: unrecognized, duplicated or otherwise invalid fields
28 cause the entire file, and usually the entire operation, to be
29 rejected.
30 The purpose of the policy file is to define a set of policy require‐
33 ments for a container image, usually depending on its location (where
34 it is being pulled from) or otherwise defined identity.
35 Policy requirements can be defined for:
38 · An individual scope in a transport. The transport values are
41 the same as the transport prefixes when pushing/pulling images
42 (e.g. docker:, atomic:), and scope values are defined by each
43 transport; see below for more details.
44 Usually, a scope can be defined to match a single image, and various
48 prefixes of
49 such a most specific scope define namespaces of matching images. - A
50 default policy for a single transport, expressed using an empty string
51 as a scope - A global default policy.
52 If multiple policy requirements match a given image, only the require‐
55 ments from the most specific match apply, the more general policy
56 requirements definitions are ignored.
57 This is expressed in JSON using the top-level syntax
60 {
63 "default": [/* policy requirements: global default */]
64 "transports": {
65 transport_name: {
66 "": [/* policy requirements: default for transport $transport_name */],
67 scope_1: [/* policy requirements: default for $scope_1 in $transport_name */],
68 scope_2: [/*…*/]
69 /*…*/
70 },
71 transport_name_2: {/*…*/}
72 /*…*/
73 }
74 }
75 The global default set of policy requirements is mandatory; all of the
79 other fields (transports itself, any specific transport, the trans‐
80 port-specific default, etc.) are optional.
81
84 atomic:
85 The atomic: transport refers to images in an Atomic Registry.
86 Supported scopes use the form hostname[:port][/namespace[/imagestream
89 [:tag]]], i.e. either specifying a complete name of a tagged image, or
90 prefix denoting a host/namespace/image stream.
91 Note: The hostname and port refer to the Docker registry host and port
94 (the one used e.g. for docker pull), not to the OpenShift API host and
95 port.
96 dir:
99 The dir: transport refers to images stored in local directories.
100 Supported scopes are paths of directories (either containing a single
103 image or subdirectories possibly containing images).
104 Note: The paths must be absolute and contain no symlinks. Paths violat‐
107 ing these requirements may be silently ignored.
108 The top-level scope "/" is forbidden; use the transport default scope
111 "", for consistency with other transports.
112 docker:
115 The docker: transport refers to images in a registry implementing the
116 "Docker Registry HTTP API V2".
117 Scopes matching individual images are named Docker references in the
120 fully expanded form, either using a tag or digest. For example,
121 docker.io/library/busybox:latest (not busybox:latest).
122 More general scopes are prefixes of individual-image scopes, and spec‐
125 ify a repository (by omitting the tag or digest), a repository names‐
126 pace, or a registry host (by only specifying the host name).
127 oci:
130 The oci: transport refers to images in directories compliant with "Open
131 Container Image Layout Specification".
132 Supported scopes use the form directory:tag, and directory referring to
135 a directory containing one or more tags, or any of the parent directo‐
136 ries.
137 Note: See dir: above for semantics and restrictions on the directory
140 paths, they apply to oci: equivalently.
141 tarball:
144 The tarball: transport refers to tarred up container root filesystems.
145 Scopes are ignored.
148
151 Using the mechanisms above, a set of policy requirements is looked up.
152 The policy requirements are represented as a JSON array of individual
153 requirement objects. For an image to be accepted, all of the require‐
154 ments must be satisfied simulatenously.
155 The policy requirements can also be used to decide whether an individ‐
158 ual signature is accepted (= is signed by a recognized key of a known
159 author); in that case some requirements may apply only to some signa‐
160 tures, but each signature must be accepted by at least one requirement
161 object.
162 The following requirement objects are supported:
165 insecureAcceptAnything
168 A simple requirement with the following syntax
169 {"type":"insecureAcceptAnything"}
172 This requirement accepts any image (but note that other requirements in
176 the array still apply).
177 When deciding to accept an individual signature, this requirement does
180 not have any effect; it does not cause the signature to be accepted,
181 though.
182 This is useful primarily for policy scopes where no signature verifica‐
185 tion is required; because the array of policy requirements must not be
186 empty, this requirement is used to represent the lack of requirements
187 explicitly.
188 reject
191 A simple requirement with the following syntax:
192 {"type":"reject"}
195 This requirement rejects every image, and every signature.
199 signedBy
202 This requirement requires an image to be signed with an expected iden‐
203 tity, or accepts a signature if it is using an expected identity and
204 key.
205 {
208 "type": "signedBy",
209 "keyType": "GPGKeys", /* The only currently supported value */
210 "keyPath": "/path/to/local/keyring/file",
211 "keyData": "base64-encoded-keyring-data",
212 "signedIdentity": identity_requirement
213 }
214 Exactly one of keyPath and keyData must be present, containing a GPG
218 keyring of one or more public keys. Only signatures made by these keys
219 are accepted.
220 The signedIdentity field, a JSON object, specifies what image identity
223 the signature claims about the image. One of the following alterna‐
224 tives are supported:
225 · The identity in the signature must exactly match the image
228 identity. Note that with this, referencing an image by digest
229 (with a signature claiming a repository:tag identity) will
230 fail.
231 {"type":"matchExact"}
235 · If the image identity carries a tag, the identity in the sig‐
239 nature must exactly match; if the image identity uses a digest
240 reference, the identity in the signature must be in the same
241 repository as the image identity (using any tag).
242 (Note that with images identified using digest references, the digest
246 from the reference is validated even before signature verification
247 starts.)
248 {"type":"matchRepoDigestOrExact"}
251 · The identity in the signature must be in the same repository
255 as the image identity. This is useful e.g. to pull an image
256 using the :latest tag when the image is signed with a tag
257 specifing an exact image version.
258 {"type":"matchRepository"}
262 · The identity in the signature must exactly match a specified
266 identity. This is useful e.g. when locally mirroring images
267 signed using their public identity.
268 {
272 "type": "exactReference",
273 "dockerReference": docker_reference_value
274 }
275 · The identity in the signature must be in the same repository
279 as a specified identity. This combines the properties of
280 matchRepository and exactReference.
281 {
285 "type": "exactRepository",
286 "dockerRepository": docker_repository_value
287 }
288 If the signedIdentity field is missing, it is treated as matchRepoDige‐
292 stOrExact.
293 Note: matchExact, matchRepoDigestOrExact and matchRepository can be
296 only used if a Docker-like image identity is provided by the transport.
297 In particular, the dir: and oci: transports can be only used with exac‐
298 tReference or exactRepository.
299
302 It is strongly recommended to set the default policy to reject, and
303 then selectively allow individual transports and scopes as desired.
304 A reasonably locked-down system
307 (Note that the /*…*/ comments are not valid in JSON, and must not be
308 used in real policies.)
309 {
312 "default": [{"type": "reject"}], /* Reject anything not explicitly allowed */
313 "transports": {
314 "docker": {
315 /* Allow installing images from a specific repository namespace, without cryptographic verification.
316 This namespace includes images like openshift/hello-openshift and openshift/origin. */
317 "docker.io/openshift": [{"type": "insecureAcceptAnything"}],
318 /* Similarly, allow installing the “official” busybox images. Note how the fully expanded
319 form, with the explicit /library/, must be used. */
320 "docker.io/library/busybox": [{"type": "insecureAcceptAnything"}]
321 /* Other docker: images use the global default policy and are rejected */
322 },
323 "dir": {
324 "": [{"type": "insecureAcceptAnything"}] /* Allow any images originating in local directories */
325 },
326 "atomic": {
327 /* The common case: using a known key for a repository or set of repositories */
328 "hostname:5000/myns/official": [
329 {
330 "type": "signedBy",
331 "keyType": "GPGKeys",
332 "keyPath": "/path/to/official-pubkey.gpg"
333 }
334 ],
335 /* A more complex example, for a repository which contains a mirror of a third-party product,
336 which must be signed-off by local IT */
337 "hostname:5000/vendor/product": [
338 { /* Require the image to be signed by the original vendor, using the vendor's repository location. */
339 "type": "signedBy",
340 "keyType": "GPGKeys",
341 "keyPath": "/path/to/vendor-pubkey.gpg",
342 "signedIdentity": {
343 "type": "exactRepository",
344 "dockerRepository": "vendor-hostname/product/repository"
345 }
346 },
347 { /* Require the image to _also_ be signed by a local reviewer. */
348 "type": "signedBy",
349 "keyType": "GPGKeys",
350 "keyPath": "/path/to/reviewer-pubkey.gpg"
351 }
352 ]
353 }
354 }
355 }
356 Completely disable security, allow all images, do not trust any signatures
360 {
361 "default": [{"type": "insecureAcceptAnything"}]
362 }
363
367 atomic(1)
368
371 August 2018, Rename to containers-policy.json(5) by Valentin Rothberg
372 vrothberg@suse.com ⟨mailto:vrothberg@suse.com⟩
373 September 2016, Originally compiled by Miloslav Trmač mitr@redhat.com
376 ⟨mailto:mitr@redhat.com⟩
377Page ManCONTAINERS-POLICY.JSON(5)(policy.json)