From dbc83423837c96dd53253ba88587021a0b36bee5 Mon Sep 17 00:00:00 2001 From: Natalie Bravo Date: Tue, 4 Mar 2025 16:45:32 -0700 Subject: [PATCH 1/3] feat: add initial w3 encrypt --- w3-encrypt.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 w3-encrypt.md diff --git a/w3-encrypt.md b/w3-encrypt.md new file mode 100644 index 0000000..31bc3cb --- /dev/null +++ b/w3-encrypt.md @@ -0,0 +1,160 @@ +# W3 Encrypt + +![wip](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) + +# Introduction + +## Abstract + +W3 Encrypt protocol defines a format to encrypt content and how to allow authorized agents to decrypt it. This is done through an encryption service that manages keys in a decentralized context, enabling encryption and providing a way to validate invocations for content decryption. + +## Concepts + +### Space + +A namespace, often referred as a "space", is an owned resource that can be shared. It corresponds to a unique asymmetric cryptographic keypair and is identified by a [`did:key`] URI. + +### Content + +A file of any type that can be encrypted and stored. + +### Encryption Service + +The encryption service performs the role of managing keys in a decentralized context. It enables encryption and provides a way to validate invocations to decrypt content. The service should implemented a secure encryption system (e.g., Lit Protocol) that supports: + +1. Multi-party threshold secret sharing (TSS) to enable decentralized public key cryptography +2. Equipped with a Trusted Execution Environment (TEE) +3. Identity-based encryption with access control conditions +4. Secure key management +5. Decentralized authorization validation + +# Capabilities + +## Space Content Decrypt + +Authorized agent MAY invoke `space/content/decrypt` capability on the [space] subject to decrypt a specified content. + +### Space Content Decrypt Example + +Invocation example illustrates Bob requesting to decrypt a content under "bafy..." in the space "did:key:zAliceSpace". + +// NOTE: Don't know if this is correct. I notice we use different formats to show a invocation example, it's a bit confusing. +Is the 'sub' the same as the 'with'? +```js +{ + "cmd": "/space/content/decrypt", + "sub": "did:key:zAliceSpace", + "iss": "did:key:zBob", + "aud": "did:web:storacha.netowrk", + "args": { + "resource": { "/": "bafy..." } + }, + "prf": [], + "sig": "..." +} +``` + +### Space Content Decrypt Capability + +#### Space Content Decrypt Capability Schema + +```ts +type SpaceContentDecrypt = { + cmd: "/space/content/decrypt" + sub: SpaceDID + args: { + // Link is the Content Archive (CAR) containing the Encrypted Metadata + resource: Link> + } +} + +// Type describes a CAR format +type ContentArchive = ByteView<{ + roots: [Block] + blocks: Block[] +}> + +``` + +### Encrypted Metadata + + +#### Encrypted Metadata Schema + +Encrypted Metadata schema is variant type keyed by the format descriptor label designed to allow format evolution through versioning and additional schema variants. + +```ts +type Index = Variant<{ + "encrypted/metadata@0.1": EncryptedMetadata +}> + +type EncryptedMetadata = { + encryptedDataCID: Link + cypherText: Uint8Array, + dataToEncryptHash: Uint8Array + accessControlConditions: [Record] +} +``` + +The Encrypted Metadata MUST sumarize all necessary information someone with a delegation needs to solicitize to the encryption service to decrypt the content under `encryptedDataCID`. + +The Encrypted Metadata should be created after the encrypt is done, where the properties can be defined as: + +| Name | Description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| accessControlConditions (ACC) | Pre-determined identity parameter. | +| dataToEncryptHash | hash of the data to encrypt.| +| cypherText | The result of encrypting the data and the identity parameter, which is the hash of the data to encrypt and the hash of the ACC| +| encryptedDataCID | Represents the actual data CID of actual encrypted data.| + +#### Access Control Conditions Format +// TODO: + + +Example: + +```js +{ + "encrypted/metadata@0.1": { + cypherText: new Uint8Array([109, 70, ... 61]), + encryptedDataCID: { "/": "bafy..dag" }, + dataToEncryptHash: new Uint8Array([49, 53, ... 54]), + accessControlConditions: [ + { + chain: "ethereum", + method: "", + parameters: [ + ":currentActionIpfsId", + "did:key:z6MktfnQz8Kcz5nsC65oyXWFXhbbAZQavjg6LYuHgv4YbxzN", + ], + contractAddress: "", + returnValueTest: { + value: "QmPFrQGo5RAtdSTZ4bkaeDHVGrmy2TeEUwTu4LuVAPHiMd", + comparator: "=", + }, + standardContractType: "", + }, + ], + }, +} + +``` + + +# Implementation Requirements + +## Encryption Service + +The encryption service MUST: + +1. Support identity-based encryption with access control conditions +2. Provide secure key management +3. Validate UCAN invocations for decryption + +## Client Implementation + +Clients implementing this spec MUST: + +1. Handle both direct encryption and double encryption for large files +2. Properly format and store encryption metadata +3. Wrap the invocation in a delegation before attempting decryption From a7e2a1d6c5cee6106a0e6b055210a9681127b78f Mon Sep 17 00:00:00 2001 From: Natalie Bravo Date: Wed, 5 Mar 2025 11:55:29 -0700 Subject: [PATCH 2/3] chore: rename encrypt metadata parameters --- w3-encrypt.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/w3-encrypt.md b/w3-encrypt.md index 31bc3cb..97c4473 100644 --- a/w3-encrypt.md +++ b/w3-encrypt.md @@ -89,9 +89,9 @@ type Index = Variant<{ }> type EncryptedMetadata = { - encryptedDataCID: Link - cypherText: Uint8Array, - dataToEncryptHash: Uint8Array + encryptedDataCID: Link + identityBoundCiphertext: Uint8Array, + plaintextKeyHash: Uint8Array accessControlConditions: [Record] } ``` @@ -103,13 +103,10 @@ The Encrypted Metadata should be created after the encrypt is done, where the pr | Name | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | accessControlConditions (ACC) | Pre-determined identity parameter. | -| dataToEncryptHash | hash of the data to encrypt.| -| cypherText | The result of encrypting the data and the identity parameter, which is the hash of the data to encrypt and the hash of the ACC| +| plaintextKeyHash | hash of the original data.| +| identityBoundCiphertext | The result of encrypting the original data and the identity parameter, which is the hash of the original data and the hash of the ACC| | encryptedDataCID | Represents the actual data CID of actual encrypted data.| -#### Access Control Conditions Format -// TODO: - Example: From b82993ee3bcbb2bd2fb1d82ea2c3f5d83ebe9618 Mon Sep 17 00:00:00 2001 From: Natalie Bravo Date: Wed, 12 Mar 2025 12:32:09 -0300 Subject: [PATCH 3/3] fix: linting errors --- .github/workflows/words-to-ignore.txt | 3 +++ w3-encrypt.md | 30 +++++++++++++++------------ 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.github/workflows/words-to-ignore.txt b/.github/workflows/words-to-ignore.txt index b392a0c..a373563 100644 --- a/.github/workflows/words-to-ignore.txt +++ b/.github/workflows/words-to-ignore.txt @@ -175,3 +175,6 @@ InterPlanetary queryable bafy 0-rc +Decrypt +decrypt +decrypting diff --git a/w3-encrypt.md b/w3-encrypt.md index 97c4473..83750ba 100644 --- a/w3-encrypt.md +++ b/w3-encrypt.md @@ -26,7 +26,7 @@ The encryption service performs the role of managing keys in a decentralized con 2. Equipped with a Trusted Execution Environment (TEE) 3. Identity-based encryption with access control conditions 4. Secure key management -5. Decentralized authorization validation +5. UCAN validation # Capabilities @@ -38,8 +38,6 @@ Authorized agent MAY invoke `space/content/decrypt` capability on the [space] su Invocation example illustrates Bob requesting to decrypt a content under "bafy..." in the space "did:key:zAliceSpace". -// NOTE: Don't know if this is correct. I notice we use different formats to show a invocation example, it's a bit confusing. -Is the 'sub' the same as the 'with'? ```js { "cmd": "/space/content/decrypt", @@ -78,7 +76,6 @@ type ContentArchive = ByteView<{ ### Encrypted Metadata - #### Encrypted Metadata Schema Encrypted Metadata schema is variant type keyed by the format descriptor label designed to allow format evolution through versioning and additional schema variants. @@ -96,9 +93,9 @@ type EncryptedMetadata = { } ``` -The Encrypted Metadata MUST sumarize all necessary information someone with a delegation needs to solicitize to the encryption service to decrypt the content under `encryptedDataCID`. +The **Encrypted Metadata** **MUST** summarize all the necessary information required for someone with a delegation to request decryption from the encryption service for the content stored under `encryptedDataCID`. -The Encrypted Metadata should be created after the encrypt is done, where the properties can be defined as: +The **Encrypted Metadata** should be generated **after** the encryption process is complete, at which point its properties can be defined as follows: | Name | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | @@ -107,7 +104,6 @@ The Encrypted Metadata should be created after the encrypt is done, where the pr | identityBoundCiphertext | The result of encrypting the original data and the identity parameter, which is the hash of the original data and the hash of the ACC| | encryptedDataCID | Represents the actual data CID of actual encrypted data.| - Example: ```js @@ -137,7 +133,6 @@ Example: ``` - # Implementation Requirements ## Encryption Service @@ -145,13 +140,22 @@ Example: The encryption service MUST: 1. Support identity-based encryption with access control conditions -2. Provide secure key management +2. Provide secure decentralized key management 3. Validate UCAN invocations for decryption ## Client Implementation -Clients implementing this spec MUST: +### Encryption +Clients implementing this specification **MUST** use the encryption service to encrypt the key used to encrypt the content. This **double encryption strategy** is designed to better handle large files. + +Once the encryption key encrypted, the client **MUST** store the encrypted metadata in IPFS, encoded as **DAG-CBOR**. + +### Delegation +The client **MUST** allow users to create a delegation for decrypting the content. The delegated resource **SHOULD** be the **encrypted metadata CID**. -1. Handle both direct encryption and double encryption for large files -2. Properly format and store encryption metadata -3. Wrap the invocation in a delegation before attempting decryption +### Decryption +1. The client **MUST** fetch the **encrypted metadata CAR** from IPFS to retrieve all necessary properties, including the **encryptedData** under **encryptedDataCID**. +2. The client **MUST** authorize a session with the **Encryption Service** to call the **UCAN validation** and decryption function. +3. **Before passing the delegation to the UCAN validation and decryption function,** the client **MUST** create an **invocation**, wrap it in a delegation, and submit it. This ensures that the function validates only the **delegation chain** and does not execute the invocation directly. +4. The **UCAN validation and decryption function** code is stored in **IPFS** to guarantee **immutability**. This function validates the delegation chain and calls the **Encryption Service** to decrypt the key. +5. Once the encryption key is retrieved, the client **MUST** use it to decrypt the actual content and **discard the key immediately** for security reasons.