First pass draft

lumjjb · lumjjb · commit e12b51e6446e · 2019-09-30T16:07:12.000-04:00
Signed-off-by: Brandon Lum &lt;lumjjb@gmail.com&gt;
diff --git a/layer.md b/layer.md
@@ -4,7 +4,7 @@ This document describes how to serialize a filesystem and filesystem changes lik
 One or more layers are applied on top of each other to create a complete filesystem.
 This document will use a concrete example to illustrate how to create and consume these filesystem layers.
 
-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).
+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+enc`, `application/vnd.oci.image.layer.v1.tar+gzip+enc`, `application/vnd.oci.image.layer.nondistributable.v1.tar+enc` and `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+enc` [media types](media-types.md).
 
 ## `+gzip` Media Types
 
@@ -16,6 +16,13 @@ This section defines the `application/vnd.oci.image.layer.v1.tar`, `application/
 * 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].
 * 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].
 
+## `+enc` Media Types
+
+* The media type `application/vnd.oci.image.layer.v1.tar+enc` represents an `application/vnd.oci.image.layer.v1.tar` payload which has been [encrypted](#layer-encryption).
+* The media type `application/vnd.oci.image.layer.v1.tar+gzip+enc` represents an `application/vnd.oci.image.layer.v1.tar+gzip` payload which has been [encrypted](#layer-encryption).
+* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+enc` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar` payload which has been [encrypted](#layer-encryption).
+* The media type `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+enc` represents an `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip` payload which has been [encrypted](#layer-encryption).
+
 ## Distributable Format
 
 * 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,38 @@ Implementations SHOULD NOT upload layers tagged with this media type; however, s
 
 [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.
 
+
+# Layer Encryption
+
+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 `+enc` suffix. For example, `application/vnd.oci.image.layer.v1.tar+enc` is an layer representation of an encrypted `application/vnd.oci.image.layer.v1.tar` layer. 
+
+When using the `+enc` mediatype, the layer data blobs are encrypted with a symmetric encryption algorithm (i.e. AES_128_GCM, AES_128_CBC, etc.) according to the [IANA Registry](https://www.iana.org/assignments/aead-parameters/aead-parameters.xhtml). 
+
+Details of the algorithms and protocols used in the encryption of the data blob are defined in a JSON object below. We note that:
+- The `cipher` field specifies the encryption algorithm in accordance with the [IANA Registry](https://www.iana.org/assignments/aead-parameters/aead-parameters.xhtml).
+- The `symkey` field specifies the base64 encoded bytes of the symmetric key used in decryption.
+- 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.
+```
+{
+    "cipher": "AES_128_GCM",
+    "symkey": "54kiln1USEaKnlYhKdz+aA==",
+    "cipheroptions": {
+        "nonce": "AdcRPTAEhXx6uwuYcOquNA==",
+        ...
+    }
+}
+```
+
+Due to the precense of sensitive information in this sturcture, to ensure 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). 
+
+The following annotations are used to communicate these encrypted messages:
+- `org.opencontainers.image.enc.keys.pkcs7` - An array of base64 comma separated encrypted messages that contain LayerBlockCipherOptions to perform decryption of the layer data in accordance with [PKCS7(RFC2315)](https://tools.ietf.org/html/rfc2315)
+- `org.opencontainers.image.enc.keys.jwe` - An array of base64 comma separated encrypted messages that contain LayerBlockCipherOptions to perform decryption of the layer data in accordance with [JWE(RFC7516)](https://tools.ietf.org/html/rfc7516)
+- `org.opencontainers.image.enc.keys.openpgp` - An array of base64 comma separated encrypted messages that contain LayerBlockCipherOptions to perform decryption of the layer data in accordance with [OpenPGP(RFC4880)](https://tools.ietf.org/html/rfc4880)
+- `org.opencontainers.image.enc.keys.*` - An array of base64 comma separated encrypted messages that contain LayerBlockCipherOptions to perform decryption of the layer data in accordance with an appropriate standard of specified protocol.
+
+The decryption of the image can be performed by unwrapping the LayerBlockCipherOptions using the `org.opencontainers.image.enc.keys.*` annotations and using the appropriate cipher with the unwrapped LayerBlockCipherOptions to decrypt the layer data blob.
+
 [libarchive-tar]: https://github.com/libarchive/libarchive/wiki/ManPageTar5#POSIX_ustar_Archives
 [gnu-tar-standard]: http://www.gnu.org/software/tar/manual/html_node/Standard.html
 [rfc1952_2]: https://tools.ietf.org/html/rfc1952
diff --git a/specs-go/v1/annotations.go b/specs-go/v1/annotations.go
@@ -53,4 +53,16 @@ const (
 
 	// AnnotationDescription is the annotation key for the human-readable description of the software packaged in the image.
 	AnnotationDescription = "org.opencontainers.image.description"
+
+	// AnnotationEncryptionKeysPkcs7 is the annotation key for the base64 encoded encrypted
+	// messages containing metadata for decrypting encrypted data blobs.
+	AnnotationEncryptionKeysPkcs7 = "org.opencontainers.image.enc.keys.pkcs7"
+
+	// AnnotationEncryptionKeysJwe is the annotation key for the base64 encoded encrypted
+	// messages containing metadata for decrypting encrypted data blobs.
+	AnnotationEncryptionKeysJwe = "org.opencontainers.image.enc.keys.jwe"
+
+	// AnnotationEncryptionKeysOpenPgp is the annotation key for the base64 encoded encrypted
+	// messages containing metadata for decrypting encrypted data blobs.
+	AnnotationEncryptionKeysOpenPgp = "org.opencontainers.image.enc.keys.openpgp"
 )
diff --git a/specs-go/v1/encryption.go b/specs-go/v1/encryption.go
@@ -0,0 +1,23 @@
+// Copyright 2016 The Linux Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package v1
+
+// LayerBlockCipherOptions includes the information required to encrypt/decrypt
+// layer blob data.
+type LayerBlockCipherOptions struct {
+	CipherType    string            `json:'cipher'`
+	SymmetricKey  []byte            `json:'symkey'`
+	CipherOptions map[string][]byte `json:'cipheroptions'`
+}
diff --git a/specs-go/v1/mediatype.go b/specs-go/v1/mediatype.go
@@ -30,6 +30,10 @@ const (
 	// MediaTypeImageLayer is the media type used for layers referenced by the manifest.
 	MediaTypeImageLayer = "application/vnd.oci.image.layer.v1.tar"
 
+	// MediaTypeImageLayerEnc is the media type used for encrypted layers
+	// referenced by the manifest.
+	MediaTypeImageLayerEnc = "application/vnd.oci.image.layer.v1.tar+enc"
+
 	// MediaTypeImageLayerGzip is the media type used for gzipped layers
 	// referenced by the manifest.
 	MediaTypeImageLayerGzip = "application/vnd.oci.image.layer.v1.tar+gzip"
@@ -38,6 +42,10 @@ const (
 	// layers referenced by the manifest.
 	MediaTypeImageLayerZstd = "application/vnd.oci.image.layer.v1.tar+zstd"
 
+	// MediaTypeImageLayerGzipEnc is the media type used for encrypted
+	// gzipped layers referenced by the manifest.
+	MediaTypeImageLayerGzipEnc = "application/vnd.oci.image.layer.v1.tar+gzip+enc"
+
 	// MediaTypeImageLayerNonDistributable is the media type for layers referenced by
 	// the manifest but with distribution restrictions.
 	MediaTypeImageLayerNonDistributable = "application/vnd.oci.image.layer.nondistributable.v1.tar"
@@ -52,6 +60,15 @@ const (
 	// restrictions.
 	MediaTypeImageLayerNonDistributableZstd = "application/vnd.oci.image.layer.nondistributable.v1.tar+zstd"
 
+	// MediaTypeImageLayerNonDistributableEnc is the media type for encrypted
+	// layers referenced by the manifest but with distribution restrictions.
+	MediaTypeImageLayerNonDistributableEnc = "application/vnd.oci.image.layer.nondistributable.v1.tar+enc"
+
+	// MediaTypeImageLayerNonDistributableGzipEnc is the media type for
+	// gzipped and encrypted layers referenced by the manifest but with
+	// distribution restrictions.
+	MediaTypeImageLayerNonDistributableGzipEnc = "application/vnd.oci.image.layer.nondistributable.v1.tar+gzip+enc"
+
 	// MediaTypeImageConfig specifies the media type for the image configuration.
 	MediaTypeImageConfig = "application/vnd.oci.image.config.v1+json"
 )
