From 2f07383709ac82b997c8a7e7f33ebab0f9da508e Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 13 Jan 2021 17:31:00 +0000 Subject: [PATCH 1/6] init: initial spec for AES codec --- block-layer/codecs/aes.md | 52 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 block-layer/codecs/aes.md diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/aes.md new file mode 100644 index 00000000..50894881 --- /dev/null +++ b/block-layer/codecs/aes.md @@ -0,0 +1,52 @@ +# Specification: AES CODECS + +**Status: Prescriptive - Draft** + +This document describes codecs for IPLD blocks (CID + Data) that are encrypted with +an AES cipher. + +The following AES variants are defined in this spec: + +| name | multicodec | iv size (in bytes) | +| --- | --- | --- | +| aes-gcm | 0x1400 | 12 | +| aes-cbc | 0x1401 | 16 | +| aes-ctr | 0x1402 | 12 | + +## Encrypted Block Format + +An encrypted block can be decoded into its initializing vector and the encrypted byte +payload. Since the initializing vector is a known size for each AES variant the block +format is simply the iv followed by the byte payload. + +``` +| iv | bytes | +``` + +This is decoded into IPLD data model of the following schema. + +```ipldsch +type AES struct { + iv Bytes + bytes Bytes +} representation map +``` + +### Decrypted Block Format + +The decrypted payload has a defined format so that it can be parsed into a pair of `CID` and +`bytes`. + +``` +| uint32(CID byteLength) | CID | Bytes +``` + +The decrypted state is decoded into IPLD data model of the following schema. + +```ipldsch +type DecryptedBlock { + cid Link + bytes Bytes +} +``` + From 4a60e401e2149460adb8982d3de33cfd02a5a9ec Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 13 Jan 2021 09:32:43 -0800 Subject: [PATCH 2/6] fix: add representation to struct --- block-layer/codecs/aes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/aes.md index 50894881..99bf24e5 100644 --- a/block-layer/codecs/aes.md +++ b/block-layer/codecs/aes.md @@ -44,9 +44,9 @@ The decrypted payload has a defined format so that it can be parsed into a pair The decrypted state is decoded into IPLD data model of the following schema. ```ipldsch -type DecryptedBlock { +type DecryptedBlock struct { cid Link bytes Bytes -} +} representation map ``` From 03d54df09621649c7b380dd6926a07b39f9b022f Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 13 Jan 2021 09:33:05 -0800 Subject: [PATCH 3/6] fix: align headers --- block-layer/codecs/aes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/aes.md index 99bf24e5..f586ae87 100644 --- a/block-layer/codecs/aes.md +++ b/block-layer/codecs/aes.md @@ -32,7 +32,7 @@ type AES struct { } representation map ``` -### Decrypted Block Format +## Decrypted Block Format The decrypted payload has a defined format so that it can be parsed into a pair of `CID` and `bytes`. From 417e69cad460adb0c3f533345ea0a96c27e21d0c Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 13 Jan 2021 11:13:20 -0800 Subject: [PATCH 4/6] feat: stronger language about what this is and isnt --- block-layer/codecs/aes.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/aes.md index f586ae87..74a814f4 100644 --- a/block-layer/codecs/aes.md +++ b/block-layer/codecs/aes.md @@ -13,6 +13,33 @@ The following AES variants are defined in this spec: | aes-cbc | 0x1401 | 16 | | aes-ctr | 0x1402 | 12 | +## What this spec is not + +This is not a complete system for application privacy. The following issues are +out of scope for this specification, although they can obvious leverage these codecs: + +* Key signaling +* Access controls +* Dual-layer encryption w/ replication keys + +How you determine what key to apply to an encrypted block will need to be done in the +application layer. How you decide to encrypt a graph and potentially link the encrypted +blocks together for replication is done at the application layer. How you manage and access +keys is done in the application layer. + +## Encode/Decode vs Encrypt/Decrypt + +The goal of specifying codecs that are used for encryption is to allow the codecs to +include encryption and decryption programs alongside the codec. However, encrypting and +decrypting are done by the user and are not done automatically as part of any encode/decode +operation in the codec. + +The encryption program returns a data model value suitable for the block encode program. The +decode program provides a data model value suitable for the decryption program. And the decryption +program provides a data model value suitable for parsing into a new block (CID and Bytes). These +programs are designed to interoperate but it's up to the user to combine them and provide the +necessary key during encryption and decryption. + ## Encrypted Block Format An encrypted block can be decoded into its initializing vector and the encrypted byte From bbb6014f89cfe0b361f3be564d8bef519f1af179 Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 13 Jan 2021 11:13:51 -0800 Subject: [PATCH 5/6] doc: typo --- block-layer/codecs/aes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/aes.md index 74a814f4..1ef846ce 100644 --- a/block-layer/codecs/aes.md +++ b/block-layer/codecs/aes.md @@ -16,7 +16,7 @@ The following AES variants are defined in this spec: ## What this spec is not This is not a complete system for application privacy. The following issues are -out of scope for this specification, although they can obvious leverage these codecs: +out of scope for this specification, although they can obviously leverage these codecs: * Key signaling * Access controls From bf8e5e02a2ebd2d1681a26454ef91afdfa28335f Mon Sep 17 00:00:00 2001 From: Mikeal Rogers Date: Wed, 20 Jan 2021 12:07:26 -0800 Subject: [PATCH 6/6] fix: collapse into a single block format --- block-layer/codecs/{aes.md => encrypted.md} | 28 ++++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) rename block-layer/codecs/{aes.md => encrypted.md} (78%) diff --git a/block-layer/codecs/aes.md b/block-layer/codecs/encrypted.md similarity index 78% rename from block-layer/codecs/aes.md rename to block-layer/codecs/encrypted.md index 1ef846ce..42248fd2 100644 --- a/block-layer/codecs/aes.md +++ b/block-layer/codecs/encrypted.md @@ -1,17 +1,18 @@ -# Specification: AES CODECS +# Specification: Encrypted Block Codec **Status: Prescriptive - Draft** -This document describes codecs for IPLD blocks (CID + Data) that are encrypted with -an AES cipher. +This document describes codecs for IPLD blocks (CID + Data) that are encrypted. The +multicodec idenfier for the cipher and the initital vector are included in the block +format and parsed into a standardized data model representation. -The following AES variants are defined in this spec: +The following known ciphers may be referenced in encrypted blocks: -| name | multicodec | iv size (in bytes) | -| --- | --- | --- | -| aes-gcm | 0x1400 | 12 | -| aes-cbc | 0x1401 | 16 | -| aes-ctr | 0x1402 | 12 | +| name | multicodec | +| --- | --- | +| aes-gcm | 0x1401 | +| aes-cbc | 0x1402 | +| aes-ctr | 0x1403 | ## What this spec is not @@ -47,25 +48,29 @@ payload. Since the initializing vector is a known size for each AES variant the format is simply the iv followed by the byte payload. ``` -| iv | bytes | +| varint(cipher-multicodec) | varint(ivLength) | iv | bytes | ``` This is decoded into IPLD data model of the following schema. ```ipldsch type AES struct { + code Int iv Bytes bytes Bytes } representation map ``` +The `code` property can be used to looking the decryption program in order to arrive +at the decrypted block format below. + ## Decrypted Block Format The decrypted payload has a defined format so that it can be parsed into a pair of `CID` and `bytes`. ``` -| uint32(CID byteLength) | CID | Bytes +| CID | Bytes ``` The decrypted state is decoded into IPLD data model of the following schema. @@ -76,4 +81,3 @@ type DecryptedBlock struct { bytes Bytes } representation map ``` -