Skip to content

Commit fbdd040

Browse files
lumjjblumjjb
committed
Added +encrypted mediatype
Signed-off-by: Brandon Lum <[email protected]>
1 parent 775207b commit fbdd040

File tree

6 files changed

+158
-1
lines changed

6 files changed

+158
-1
lines changed

‎annotations.md

+4
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,10 @@ This specification defines the following annotation keys, intended for but not l
4040
```
4141
* **org.opencontainers.image.title** Human-readable title of the image (string)
4242
* **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
43+
* **org.opencontainers.image.org.opencontainers.image.enc.keys.pkcs7** Base64 comma separated [PKCS7(RFC2315)](https://tools.ietf.org/html/rfc2315) encrypted messages that contain wrapped PrivateLayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
44+
* **org.opencontainers.image.org.opencontainers.image.enc.keys.jwe** Base64 comma separated [JWE(RFC7516)](https://tools.ietf.org/html/rfc7516) encrypted messages that contain wrapped PrivateLayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
45+
* **org.opencontainers.image.org.opencontainers.image.enc.keys.openpgp** Base64 comma separated [OpenPGP(RFC4880)](https://tools.ietf.org/html/rfc4880) encrypted messages that contain wrapped PrivateLayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
46+
* **org.opencontainers.image.org.opencontainers.image.enc.pubopts** Base64 encoded PublicLayerBlockCipherOptions JSON object for [encryption](layer.md#layer-encryption)
4347
4448
## Back-compatibility with Label Schema
4549

‎layer.md

+98-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This document describes how to serialize a filesystem and filesystem changes lik
44
One or more layers are applied on top of each other to create a complete filesystem.
55
This document will use a concrete example to illustrate how to create and consume these filesystem layers.
66

7-
This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/vnd.oci.image.layer.v1.tar+gzip`, `application/vnd.oci.image.layer.v1.tar+zstd`, `application/vnd.oci.image.layer.nondistributable.v1.tar`, `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`, and `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd` [media types](media-types.md).
7+
This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/vnd.oci.image.layer.v1.tar+gzip`, `application/vnd.oci.image.layer.v1.tar+zstd`, `application/vnd.oci.image.layer.nondistributable.v1.tar`, `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`, `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd`, `application/vnd.oci.image.layer.v1.tar+encrypted`, `application/vnd.oci.image.layer.v1.tar+gzip+encrypted`, `application/vnd.oci.image.layer.nondistributable.v1.tar+encrypted` and `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+encrypted` [media types](media-types.md).
88

99
## `+gzip` Media Types
1010

@@ -16,6 +16,13 @@ This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/
1616
* The media type `application/vnd.oci.image.layer.v1.tar+zstd` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been compressed with [zstd][rfc8478].
1717
* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been compressed with [zstd][rfc8478].
1818

19+
## `+encrypted` Media Types
20+
21+
* The media type `application/vnd.oci.image.layer.v1.tar+encrypted` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been [encrypted](#layer-encryption).
22+
* The media type `application/vnd.oci.image.layer.v1.tar+gzip+encrypted` represents an `application/vnd.oci.image.layer.v1.tar+gzip` payload which has been [encrypted](#layer-encryption).
23+
* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+encrypted` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been [encrypted](#layer-encryption).
24+
* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+encrypted` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` payload which has been [encrypted](#layer-encryption).
25+
1926
## Distributable Format
2027

2128
* Layer Changesets for the [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` MUST be packaged in [tar archive][tar-archive].
@@ -332,6 +339,96 @@ Implementations SHOULD NOT upload layers tagged with this media type; however, s
332339

333340
[Descriptors](descriptor.md) referencing non-distributable layers MAY include `urls` for downloading these layers directly; however, the presence of the `urls` field SHOULD NOT be used to determine whether or not a layer is non-distributable.
334341

342+
343+
# Layer Encryption
344+
345+
To be able to protect the confidentiality of the data in layers, encryption of the layer data blobs can be done to prevent unauthorized access to layer data. Encryption is performed on the data blob of a layer by specifying a mediatype with the `+encrypted` suffix. For example, `application/vnd.oci.image.layer.v1.tar+encrypted` is an layer representation of an encrypted `application/vnd.oci.image.layer.v1.tar` layer.
346+
347+
When using the `+encrypted` mediatype, the layer data blobs are encrypted. In order to decrypt an image, the encryption metadata is required.
348+
349+
## Encryption Metadata
350+
351+
The encryption metadata consists of 2 parts: PublicLayerBlockCipherOptions and PrivateLayerBlockCipherOptions. The PublicLayerBlockCipherOptions contain encryption metadata that is public, i.e. cipher type, HMAC, etc. and PrivateLayerBlockCipherOptions contains the encryption metadata which should be confidential, i.e. symmetric key, nonce (optional), etc. These are stored in the respective [**org.opencontainers.image.enc** prefixed annotations](annotations.md).
352+
353+
Below are golang definitions of these JSON objects:
354+
355+
```
356+
// LayerCipherType is the ciphertype as specified in the layer metadata
357+
type LayerCipherType string
358+
359+
// PublicLayerBlockCipherOptions includes the information required to encrypt/decrypt
360+
// an image which are public and can be deduplicated in plaintext across multiple
361+
// recipients
362+
type PublicLayerBlockCipherOptions struct {
363+
// CipherType denotes the cipher type according to the list of OCI suppported
364+
// cipher types.
365+
CipherType LayerCipherType `json:"cipher"`
366+
367+
// Hmac contains the hmac string to help verify encryption
368+
Hmac []byte `json:"hmac"`
369+
370+
// CipherOptions contains the cipher metadata used for encryption/decryption
371+
// This field should be populated by Encrypt/Decrypt calls
372+
CipherOptions map[string][]byte `json:"cipheroptions"`
373+
}
374+
375+
// PrivateLayerBlockCipherOptions includes the information required to encrypt/decrypt
376+
// an image which are sensitive and should not be in plaintext
377+
type PrivateLayerBlockCipherOptions struct {
378+
// SymmetricKey represents the symmetric key used for encryption/decryption
379+
// This field should be populated by Encrypt/Decrypt calls
380+
SymmetricKey []byte `json:"symkey"`
381+
382+
// Digest is the digest of the original data for verification.
383+
// This is NOT populated by Encrypt/Decrypt calls
384+
Digest digest.Digest `json:"digest"`
385+
386+
// CipherOptions contains the cipher metadata used for encryption/decryption
387+
// This field should be populated by Encrypt/Decrypt calls
388+
CipherOptions map[string][]byte `json:"cipheroptions"`
389+
}
390+
```
391+
392+
Details of the algorithms and protocols used in the encryption of the data blob are defined in these JSON objects. Here are some examples of the Public/Private LayerBlockCipherOptions.
393+
- The `cipher` field specifies the encryption algorithm to use according to the [list of cipher types supported](#cipher-types).
394+
- The `symkey` field specifies the base64 encoded bytes of the symmetric key used in decryption.
395+
- The `cipherOptions` field specifies additional parameters used in the decryption process of the specified algorithm. This should be in accordance with the RFC standard of the algorithm used.
396+
```
397+
PublicLayerBlockCipherOption
398+
{
399+
"cipher": "AES_256_CTR_HMAC_SHA256",
400+
"hmac": "M0M5OTA5QUZFQzI1MzU0RDU1MURBRTIxNTkwQkIyNkUzOEQ1M0YyMTczQjhEM0RDM0VFRTRDMDQ3RTdBQjFDMQ=="
401+
"cipheroptions": {}
402+
}
403+
404+
PrivateLayerBlockCipherOption
405+
{
406+
"symkey": "54kiln1USEaKnlYhKdz+aA==",
407+
"cipheroptions": {
408+
"nonce": "AdcRPTAEhXx6uwuYcOquNA==",
409+
...
410+
}
411+
}
412+
413+
```
414+
415+
The PublicLayerBlockCipherOptions JSON object is stored base64 encoded in the layer annotation **org.opencontainers.image.enc.pubopts**.
416+
417+
The PrivateLayerBlockCipherOptions JSON object is not stored in plaintext due to the sensitive nature of the contents. Instead, the object goes through a cryptographic wrapping process. This ensures that only authorized parties are able to decrypt the layers, the decryption metadata objects are wrapped as encrypted messages to the authorized recipients in accordance with encrypted message standards such as [OpenPGP(RFC4880)](https://tools.ietf.org/html/rfc4880), [PKCS7(RFC2315)](https://tools.ietf.org/html/rfc2315), [JWE(RFC7516)](https://tools.ietf.org/html/rfc7516).
418+
419+
The following annotations are used to communicate these encrypted messages:
420+
- `org.opencontainers.image.enc.keys.pkcs7` - An array of base64 comma separated encrypted messages that contain PrivateLayerBlockCipherOptions to perform decryption of the layer data in accordance with [PKCS7(RFC2315)](https://tools.ietf.org/html/rfc2315)
421+
- `org.opencontainers.image.enc.keys.jwe` - An array of base64 comma separated encrypted messages that contain PrivateLayerBlockCipherOptions to perform decryption of the layer data in accordance with [JWE(RFC7516)](https://tools.ietf.org/html/rfc7516)
422+
- `org.opencontainers.image.enc.keys.openpgp` - An array of base64 comma separated encrypted messages that contain PrivateLayerBlockCipherOptions to perform decryption of the layer data in accordance with [OpenPGP(RFC4880)](https://tools.ietf.org/html/rfc4880)
423+
- `org.opencontainers.image.enc.keys.*` - An array of base64 comma separated encrypted messages that contain PrivateLayerBlockCipherOptions to perform decryption of the layer data in accordance with an appropriate standard of specified protocol.
424+
425+
The decryption of the image can be performed by unwrapping the PrivateLayerBlockCipherOptions using the `org.opencontainers.image.enc.keys.*` annotations and using the appropriate cipher with the unwrapped PrivateLayerBlockCipherOptions to decrypt the layer data blob.
426+
427+
### Cipher Types
428+
429+
The current list of cipher types supported are:
430+
- `AES_256_CTR_HMAC_SHA256` - Encryption with `AES_256_CTR` algorithm [FIPS-197](https://csrc.nist.gov/csrc/media/publications/fips/197/final/documents/fips-197.pdf) with Encrypt-then-mac [RFC7366](https://tools.ietf.org/html/rfc7366). The protocols used in this cipher type is in accordance to FIPS 140-2 compliant standards.
431+
335432
[libarchive-tar]: https://github.com/libarchive/libarchive/wiki/ManPageTar5#POSIX_ustar_Archives
336433
[gnu-tar-standard]: http://www.gnu.org/software/tar/manual/html_node/Standard.html
337434
[rfc1952_2]: https://tools.ietf.org/html/rfc1952

‎media-types.md

+4
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ The following media types identify the formats described here and their referenc
1313
- `application/vnd.oci.image.layer.nondistributable.v1.tar`: ["Layer", as a tar archive with distribution restrictions](layer.md#non-distributable-layers)
1414
- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`: ["Layer", as a tar archive with distribution restrictions](layer.md#gzip-media-types) compressed with [gzip][rfc1952]
1515
- `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd`: ["Layer", as a tar archive with distribution restrictions](layer.md#zstd-media-types) compressed with [zstd][rfc8478]
16+
- `application/vnd.oci.image.layer.v1.tar+encrypted` : ["Layer", as an encrypted tar archive](layer.md#enc-media-types)
17+
- `application/vnd.oci.image.layer.v1.tar+gzip+encrypted` : ["Layer", as an encrypted gzipped tar archive](layer.md#enc-media-types)
18+
- `application/vnd.oci.image.layer.nondistributable.v1.tar+encrypted` : ["Layer", as an encrypted tar archive with distribution restrictions](layer.md#enc-media-types)
19+
- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+encrypted` : ["Layer", as an encrypted gzipped tar archive with distribution restrictions](layer.md#enc-media-types)
1620

1721
## Media Type Conflicts
1822

‎specs-go/v1/annotations.go

+12
Original file line numberDiff line numberDiff line change
@@ -53,4 +53,16 @@ const (
5353

5454
// AnnotationDescription is the annotation key for the human-readable description of the software packaged in the image.
5555
AnnotationDescription = "org.opencontainers.image.description"
56+
57+
// AnnotationEncryptionKeysPkcs7 is the annotation key for the base64 encoded encrypted
58+
// messages containing metadata for decrypting encrypted data blobs.
59+
AnnotationEncryptionKeysPkcs7 = "org.opencontainers.image.enc.keys.pkcs7"
60+
61+
// AnnotationEncryptionKeysJwe is the annotation key for the base64 encoded encrypted
62+
// messages containing metadata for decrypting encrypted data blobs.
63+
AnnotationEncryptionKeysJwe = "org.opencontainers.image.enc.keys.jwe"
64+
65+
// AnnotationEncryptionKeysOpenPgp is the annotation key for the base64 encoded encrypted
66+
// messages containing metadata for decrypting encrypted data blobs.
67+
AnnotationEncryptionKeysOpenPgp = "org.opencontainers.image.enc.keys.openpgp"
5668
)

‎specs-go/v1/encryption.go

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Copyright 2016 The Linux Foundation
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package v1
16+
17+
// LayerBlockCipherOptions includes the information required to encrypt/decrypt
18+
// layer blob data.
19+
type LayerBlockCipherOptions struct {
20+
CipherType string `json:'cipher'`
21+
SymmetricKey []byte `json:'symkey'`
22+
CipherOptions map[string][]byte `json:'cipheroptions'`
23+
}

‎specs-go/v1/mediatype.go

+17
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ const (
3030
// MediaTypeImageLayer is the media type used for layers referenced by the manifest.
3131
MediaTypeImageLayer = "application/vnd.oci.image.layer.v1.tar"
3232

33+
// MediaTypeImageLayerEnc is the media type used for encrypted layers
34+
// referenced by the manifest.
35+
MediaTypeImageLayerEnc = "application/vnd.oci.image.layer.v1.tar+encrypted"
36+
3337
// MediaTypeImageLayerGzip is the media type used for gzipped layers
3438
// referenced by the manifest.
3539
MediaTypeImageLayerGzip = "application/vnd.oci.image.layer.v1.tar+gzip"
@@ -38,6 +42,10 @@ const (
3842
// layers referenced by the manifest.
3943
MediaTypeImageLayerZstd = "application/vnd.oci.image.layer.v1.tar+zstd"
4044

45+
// MediaTypeImageLayerGzipEnc is the media type used for encrypted
46+
// gzipped layers referenced by the manifest.
47+
MediaTypeImageLayerGzipEnc = "application/vnd.oci.image.layer.v1.tar+gzip+encrypted"
48+
4149
// MediaTypeImageLayerNonDistributable is the media type for layers referenced by
4250
// the manifest but with distribution restrictions.
4351
MediaTypeImageLayerNonDistributable = "application/vnd.oci.image.layer.nondistributable.v1.tar"
@@ -52,6 +60,15 @@ const (
5260
// restrictions.
5361
MediaTypeImageLayerNonDistributableZstd = "application/vnd.oci.image.layer.nondistributable.v1.tar+zstd"
5462

63+
// MediaTypeImageLayerNonDistributableEnc is the media type for encrypted
64+
// layers referenced by the manifest but with distribution restrictions.
65+
MediaTypeImageLayerNonDistributableEnc = "application/vnd.oci.image.layer.nondistributable.v1.tar+encrypted"
66+
67+
// MediaTypeImageLayerNonDistributableGzipEnc is the media type for
68+
// gzipped and encrypted layers referenced by the manifest but with
69+
// distribution restrictions.
70+
MediaTypeImageLayerNonDistributableGzipEnc = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+encrypted"
71+
5572
// MediaTypeImageConfig specifies the media type for the image configuration.
5673
MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"
5774
)

0 commit comments

Comments
 (0)