Updated to split public/private cipher options

Signed-off-by: Brandon Lum <[email protected]>

Author: lumjjb

annotations.md

@@ -40,9 +40,10 @@ This specification defines the following annotation keys, intended for but not l
     ```
 * **org.opencontainers.image.title** Human-readable title of the image (string)
 * **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
-* **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 LayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
-* **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 LayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
-* **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 LayerBlockCipherOptions JSON objects for [encryption](layer.md#layer-encryption)
+* **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)
+* **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)
+* **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)
+* **org.opencontainers.image.org.opencontainers.image.enc.pubopts** Base64 encoded PublicLayerBlockCipherOptions JSON object for [encryption](layer.md#layer-encryption)
 
 ## Back-compatibility with Label Schema
 

layer.md

@@ -339,32 +339,87 @@ Implementations SHOULD NOT upload layers tagged with this media type; however, s
 
 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). 
+When using the `+enc` mediatype, the layer data blobs are encrypted. In order to decrypt an image, the encryption metadata is required. 
 
-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).
+## Encryption Metadata
+
+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).
+
+Below are golang definitions of these JSON objects:
+
+```
+// PublicLayerBlockCipherOptions includes the information required to encrypt/decrypt
+// an image which are public and can be deduplicated in plaintext across multiple
+// recipients
+type PublicLayerBlockCipherOptions struct {
+    // CipherType denotes the cipher type according to the list of OCI suppported
+    // cipher types
+	CipherType string `json:"cipher"`
+
+    // Hmac contains the hmac string to help verify encryption
+	Hmac string `json:"hmac"`
+
+	// CipherOptions contains the cipher metadata used for encryption/decryption
+	// This field should be populated by Encrypt/Decrypt calls
+	CipherOptions map[string][]byte `json:"cipheroptions"`
+}
+
+// PrivateLayerBlockCipherOptions includes the information required to encrypt/decrypt
+// an image which are sensitive and should not be in plaintext
+type PrivateLayerBlockCipherOptions struct {
+	// SymmetricKey represents the symmetric key used for encryption/decryption
+	// This field should be populated by Encrypt/Decrypt calls
+	SymmetricKey []byte `json:"symkey"`
+
+	// Digest is the digest of the original data for verification.
+	// This is NOT populated by Encrypt/Decrypt calls
+	Digest digest.Digest `json:"digest"`
+
+	// CipherOptions contains the cipher metadata used for encryption/decryption
+	// This field should be populated by Encrypt/Decrypt calls
+	CipherOptions map[string][]byte `json:"cipheroptions"`
+}
+```
+
+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.
+- The `cipher` field specifies the encryption algorithm to use according to the [list of cipher types supported](#cipher-types).
 - 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.
 ```
+PublicLayerBlockCipherOption
+{
+    "cipher": "AES_256_CTR_HMAC_SHA256",
+    "hmac": "M0M5OTA5QUZFQzI1MzU0RDU1MURBRTIxNTkwQkIyNkUzOEQ1M0YyMTczQjhEM0RDM0VFRTRDMDQ3RTdBQjFDMQ=="
+    "cipheroptions": {}
+}
+
+PrivateLayerBlockCipherOption
 {
-    "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 PublicLayerBlockCipherOptions JSON object is stored base64 encoded in the layer annotation **org.opencontainers.image.enc.pubopts**. 
+
+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). 
 
 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.
+- `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)
+- `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)
+- `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)
+- `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.
+
+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.
+
+### Cipher Types
 
-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.
+The current list of cipher types supported are:
+- `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. 
 
 [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