1POLICY.JSON(5) September 2016 POLICY.JSON(5)
2
6 policy.json - syntax for the signature verification policy file
7
10 Signature verification policy files are used to specify policy, e.g.
11 trusted keys, applicable when deciding whether to accept an image, or
12 individual signatures of that image, as valid.
13 The default policy is stored (unless overridden at compile-time) at
16 /etc/containers/policy.json; applications performing verification may
17 allow using a different policy instead.
18
21 The signature verification policy file, usually called policy.json,
22 uses a JSON format. Unlike some other JSON files, its parsing is
23 fairly strict: unrecognized, duplicated or otherwise invalid fields
24 cause the entire file, and usually the entire operation, to be
25 rejected.
26 The purpose of the policy file is to define a set of policy
29 requirements for a container image, usually depending on its location
30 (where it is being pulled from) or otherwise defined identity.
31 Policy requirements can be defined for:
34 · An individual scope in a transport. The transport values are
37 the same as the transport prefixes when pushing/pulling images
38 (e.g. docker:, atomic:), and scope values are defined by each
39 transport; see below for more details.
40 Usually, a scope can be defined to match a single image, and various
44 prefixes of
45 such a most specific scope define namespaces of matching images. - A
46 default policy for a single transport, expressed using an empty string
47 as a scope - A global default policy.
48 If multiple policy requirements match a given image, only the
51 requirements from the most specific match apply, the more general
52 policy requirements definitions are ignored.
53 This is expressed in JSON using the top-level syntax
56 {
59 "default": [/* policy requirements: global default */]
60 "transports": {
61 transport_name: {
62 "": [/* policy requirements: default for transport $transport_name */],
63 scope_1: [/* policy requirements: default for $scope_1 in $transport_name */],
64 scope_2: [/*…*/]
65 /*…*/
66 },
67 transport_name_2: {/*…*/}
68 /*…*/
69 }
70 }
71 The global default set of policy requirements is mandatory; all of the
75 other fields (transports itself, any specific transport, the
76 transport-specific default, etc.) are optional. <!-- NOTE: Keep this
77 in sync with transports/transports.go! -->
78
80 atomic:
81 The atomic: transport refers to images in an Atomic Registry.
82 Supported scopes use the form hostname[:port][/namespace[/imagestream
85 [:tag]]], i.e. either specifying a complete name of a tagged image, or
86 prefix denoting a host/namespace/image stream.
87 Note: The hostname and port refer to the Docker registry host and port
90 (the one used e.g. for docker pull), not to the OpenShift API host and
91 port.
92 dir:
95 The dir: transport refers to images stored in local directories.
96 Supported scopes are paths of directories (either containing a single
99 image or subdirectories possibly containing images).
100 Note: The paths must be absolute and contain no symlinks. Paths
103 violating these requirements may be silently ignored.
104 The top-level scope "/" is forbidden; use the transport default scope
107 "", for consistency with other transports.
108 docker:
111 The docker: transport refers to images in a registry implementing the
112 "Docker Registry HTTP API V2".
113 Scopes matching individual images are named Docker references in the
116 fully expanded form, either using a tag or digest. For example,
117 docker.io/library/busybox:latest (not busybox:latest).
118 More general scopes are prefixes of individual-image scopes, and
121 specify a repository (by omitting the tag or digest), a repository
122 namespace, or a registry host (by only specifying the host name).
123 oci:
126 The oci: transport refers to images in directories compliant with "Open
127 Container Image Layout Specification".
128 Supported scopes use the form directory:tag, and directory referring to
131 a directory containing one or more tags, or any of the parent
132 directories.
133 Note: See dir: above for semantics and restrictions on the directory
136 paths, they apply to oci: equivalently.
137 tarball:
140 The tarball: transport refers to tarred up container root filesystems.
141 Scopes are ignored.
144
147 Using the mechanisms above, a set of policy requirements is looked up.
148 The policy requirements are represented as a JSON array of individual
149 requirement objects. For an image to be accepted, all of the
150 requirements must be satisfied simulatenously.
151 The policy requirements can also be used to decide whether an
154 individual signature is accepted (= is signed by a recognized key of a
155 known author); in that case some requirements may apply only to some
156 signatures, but each signature must be accepted by at least one
157 requirement object.
158 The following requirement objects are supported:
161 insecureAcceptAnything
164 A simple requirement with the following syntax
165 {"type":"insecureAcceptAnything"}
168 This requirement accepts any image (but note that other requirements in
172 the array still apply).
173 When deciding to accept an individual signature, this requirement does
176 not have any effect; it does not cause the signature to be accepted,
177 though.
178 This is useful primarily for policy scopes where no signature
181 verification is required; because the array of policy requirements must
182 not be empty, this requirement is used to represent the lack of
183 requirements explicitly.
184 reject
187 A simple requirement with the following syntax:
188 {"type":"reject"}
191 This requirement rejects every image, and every signature.
195 signedBy
198 This requirement requires an image to be signed with an expected
199 identity, or accepts a signature if it is using an expected identity
200 and key.
201 {
204 "type": "signedBy",
205 "keyType": "GPGKeys", /* The only currently supported value */
206 "keyPath": "/path/to/local/keyring/file",
207 "keyData": "base64-encoded-keyring-data",
208 "signedIdentity": identity_requirement
209 }
210 <!-- Later: other keyType values -->
212 Exactly one of keyPath and keyData must be present, containing a GPG
214 keyring of one or more public keys. Only signatures made by these keys
215 are accepted.
216 The signedIdentity field, a JSON object, specifies what image identity
219 the signature claims about the image. One of the following
220 alternatives are supported:
221 · The identity in the signature must exactly match the image
224 identity. Note that with this, referencing an image by digest
225 (with a signature claiming a repository:tag identity) will
226 fail.
227 {"type":"matchExact"}
231 · If the image identity carries a tag, the identity in the
235 signature must exactly match; if the image identity uses a
236 digest reference, the identity in the signature must be in the
237 same repository as the image identity (using any tag).
238 (Note that with images identified using digest references, the digest
242 from the reference is validated even before signature verification
243 starts.)
244 {"type":"matchRepoDigestOrExact"}
247 · The identity in the signature must be in the same repository
251 as the image identity. This is useful e.g. to pull an image
252 using the :latest tag when the image is signed with a tag
253 specifing an exact image version.
254 {"type":"matchRepository"}
258 · The identity in the signature must exactly match a specified
262 identity. This is useful e.g. when locally mirroring images
263 signed using their public identity.
264 {
268 "type": "exactReference",
269 "dockerReference": docker_reference_value
270 }
271 · The identity in the signature must be in the same repository
275 as a specified identity. This combines the properties of
276 matchRepository and exactReference.
277 {
281 "type": "exactRepository",
282 "dockerRepository": docker_repository_value
283 }
284 If the signedIdentity field is missing, it is treated as
288 matchRepoDigestOrExact.
289 Note: matchExact, matchRepoDigestOrExact and matchRepository can be
292 only used if a Docker-like image identity is provided by the transport.
293 In particular, the dir: and oci: transports can be only used with
294 exactReference or exactRepository. <!-- ### `signedBaseLayer` -->
295
297 It is strongly recommended to set the default policy to reject, and
298 then selectively allow individual transports and scopes as desired.
299 A reasonably locked-down system
302 (Note that the /*…*/ comments are not valid in JSON, and must not be
303 used in real policies.)
304 {
307 "default": [{"type": "reject"}], /* Reject anything not explicitly allowed */
308 "transports": {
309 "docker": {
310 /* Allow installing images from a specific repository namespace, without cryptographic verification.
311 This namespace includes images like openshift/hello-openshift and openshift/origin. */
312 "docker.io/openshift": [{"type": "insecureAcceptAnything"}],
313 /* Similarly, allow installing the “official” busybox images. Note how the fully expanded
314 form, with the explicit /library/, must be used. */
315 "docker.io/library/busybox": [{"type": "insecureAcceptAnything"}]
316 /* Other docker: images use the global default policy and are rejected */
317 },
318 "dir": {
319 "": [{"type": "insecureAcceptAnything"}] /* Allow any images originating in local directories */
320 },
321 "atomic": {
322 /* The common case: using a known key for a repository or set of repositories */
323 "hostname:5000/myns/official": [
324 {
325 "type": "signedBy",
326 "keyType": "GPGKeys",
327 "keyPath": "/path/to/official-pubkey.gpg"
328 }
329 ],
330 /* A more complex example, for a repository which contains a mirror of a third-party product,
331 which must be signed-off by local IT */
332 "hostname:5000/vendor/product": [
333 { /* Require the image to be signed by the original vendor, using the vendor's repository location. */
334 "type": "signedBy",
335 "keyType": "GPGKeys",
336 "keyPath": "/path/to/vendor-pubkey.gpg",
337 "signedIdentity": {
338 "type": "exactRepository",
339 "dockerRepository": "vendor-hostname/product/repository"
340 }
341 },
342 { /* Require the image to _also_ be signed by a local reviewer. */
343 "type": "signedBy",
344 "keyType": "GPGKeys",
345 "keyPath": "/path/to/reviewer-pubkey.gpg"
346 }
347 ]
348 }
349 }
350 }
351 Completely disable security, allow all images, do not trust any signatures
355 {
356 "default": [{"type": "insecureAcceptAnything"}]
357 }
358
362 atomic(1)
363
366 September 2016, Originally compiled by Miloslav Trmač ⟨mitr@redhat.com⟩
367Miloslav Trmač policy.json Man Page POLICY.JSON(5)