Skip to content

Commit

Permalink
Updated to split public/private cipher options
Browse files Browse the repository at this point in the history 
Signed-off-by: Brandon Lum <lumjjb@gmail.com>
  • Loading branch information
@lumjjb
lumjjb committed Aug 16, 2019
1 parent f21e591 commit 6c6d3dc
Show file tree
Hide file tree
Showing 2 changed files with 72 additions and 13 deletions.
7 changes: 4 additions & 3 deletions annotations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
78 changes: 68 additions & 10 deletions layer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -339,32 +339,90 @@ 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:

```
// LayerCipherType is the ciphertype as specified in the layer metadata
type LayerCipherType string
// 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 LayerCipherType `json:"cipher"`
// Hmac contains the hmac string to help verify encryption
Hmac []byte `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
Expand Down

0 comments on commit 6c6d3dc

Please # to comment.