You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: spec/spec.md
+62-68
Original file line number
Diff line number
Diff line change
@@ -315,69 +315,6 @@ The message generating party ****MUST**** construct the signed message object as
315
315
- The object ****MUST**** include a `kid` property, and its value ****MUST**** be a [DID URL](https://w3c.github.io/did-core/#example-a-unique-verification-method-in-a-did-document) string identifying the key to be used in verifying the signature.
316
316
- The object ****MUST**** include a `signature` property, and its value ****must**** be a signature string produced by signing the `protected` and `payload` values, in accordance with the [[spec:rfc7515]] JSON Web Signature specification.
317
317
318
-
### Encrypted Data
319
-
320
-
If the object is to be encrypted (e.g the Node owner encrypting their data to keep it private), the `descriptor` object ****MUST**** be constructed as follows:
The message generating party ****MUST**** construct an encrypted message as follows:
342
-
343
-
1. The `encryption` property of the `descriptor` object ****MUST**** be set to the string label value of a [Supported Encryption Format](#supported-encryption-format).
344
-
2. Generate an encrypted payload from the data conformant with the format specified in the `encryption` property..
345
-
3. Generate a [Version 1 CID](https://docs.ipfs.io/concepts/content-addressing/#identifier-formats) from the payload produced in Step 2 and let the `dataCid` property of the `descriptor` object be the stringified representation of the CID.
346
-
347
-
### Signed & Encrypted Data
348
-
349
-
If the object is to be both attributed to a signer and encrypted encrypted, it ****MUST**** be structured as follows:
The message generating party ****MUST**** construct the signed and encrypted message as follows:
377
-
378
-
1. Follow the instructions described in the [Encrypted Data](#encrypted-data) section to add the required properties to the `descriptor` and produce a [[spec:rfc7516]] JSON Web Encryption (JWE) object from the associated data.
379
-
2. Follow the instructions described in the [Signed Data](#signed-data) section to add an `attestation` property with a General object representation of a [[spec:rfc7515]] JSON Web Signature as its value.
380
-
381
318
### Response Objects
382
319
383
320
Responses from Interface method invocations are JSON objects that ****MUST**** be constructed as follows:
@@ -924,9 +861,23 @@ directory of the specification.
924
861
- The object ****MAY**** contain a `schema` property, and if present its value ****Must**** be a URI string that indicates the schema of the associated data and ****MUST**** be treated as an immutable value for the lifetime of the logical record.
925
862
- The object ****MAY**** contain a `commitStrategy` property, and if present its value ****Must**** be a string from the table of registered [Commit Strategies](#commit-strategies).
926
863
- The object ****MAY**** contain a `published` property, and if present its value ****Must**** be a boolean indicating the record's publication state. A value of `true` indicates the record has been published for public queries and consumption without requiring authorization. A value of `false` or the absence of the property indicates the record ****MUST NOT**** be served in response to public queries that lack proper authorization.
927
-
- The object ****MAY**** contain an `encryption` property, and if present its value ****Must**** be a string that matches one of the [Supported Encryption Formats](#supported-encryption-format), indicating the encryption format with which the data is encrypted. The absence of this property indicates the data is not encrypted.
864
+
865
+
- The object ****MAY**** contain an `encryption` property; the object ****MUST**** contain the `encryption` property if the data is encrypted. The absence of this property indicates the data is not encrypted. If present, its value ****MUST**** be a JSON object composed as follows:
866
+
- The object ****MUST**** contain an `algorithm` string property denoting the symmetric encryption algorithm used to encrypt this message. Use the algorithm list names published in the [IANA
867
+
JOSE Algorithms registry](https://www.iana.org/assignments/jose/jose.xhtml).
868
+
- The object ****MUST**** contain an `initializationVector` property and its value ****MUST**** be a `base64Url` encoded string of the initialization vector used for the symmetric encryption.
869
+
- The object ****MUST**** contain a `keyEncryption` property and its value ****MUST**** be an array of encrypted key objects described as follows:
870
+
- The object ****MUST**** contain a `derivationScheme` property and it ****MUST**** have one of the following values:
871
+
-`protocolPath`
872
+
-`protocolContext`
873
+
- The object ****MUST**** contain a `rootKeyId` property and it ****MUST**** have a string value representing the fully qualified key ID of the root key used in deriving the public key that encrypts the symmetric encryption key.
874
+
- The object ****MUST**** contain an `algorithm` string property denoting the asymmetric encryption algorithm used to encrypt the symmetric encryption key.
875
+
- The object ****MAY**** contain other custom properties needed by the encryption chosen algorithm, such as `ephemeralPublicKey`, `initializationVector`, `messageAuthenticationCode`, etc.
876
+
- The object ****MUST**** contain an `encryptedKey` property and its value ****MUST**** be a `base64Url` encoded string of the encrypted symmetric key used to encrypt the data.
877
+
- The object ****MAY**** contain a `derivedPublicKey` property; if present its value ****MUST**** be an object representing the derived public key used to encrypt the symmetric key in JWK format as per [[spec:RFC7517]].
878
+
928
879
- The object ****MUST**** contain a `dateCreated` property, and its value ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` was created by the DID owner or another permitted party.
929
-
- The object ****MAY**** contain a `datePublished` property, and its value ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` was published by the DID owner or another permitted party.
880
+
- The object ****MAY**** contain a `datePublished` property; if present, its value ****MUST**** be an [[spec:rfc3339]] ISO 8601 timestamp that ****MUST**** be set and interpreted as the time the `RecordsWrite` was published by the DID owner or another permitted party.
930
881
931
882
```json
932
883
{ // Message
@@ -1172,7 +1123,12 @@ Protocol Definition objects are declarative rules within `ProtocolConfigure` mes
1172
1123
-`recipient`
1173
1124
- The object ****MUST**** contain a `can` property and it ****MUST**** have a value of either `read` or `write`
1174
1125
- The object ****MAY**** contain a `of` property and it ****MUST**** have a string value that references one of the `types`
1175
-
1126
+
1127
+
- The object ****MAY**** contain an `$encryption` property to enable record encryption using the [Protocol Path derivation scheme](#protocol-path-scheme). If present, its value ****MUST**** be an object composed as follows:
1128
+
- The object ****MUST**** contain a `publicKeyJwk` property representing a public key as per [[spec:RFC7517]].
1129
+
This is the public key that a sender uses to encrypt the symmetric private key used to encrypt the Decentralized Web Node message.
1130
+
- The object ****MUST**** contain a `rootKeyId` property and it ****MUST**** be the fully qualified key ID of the root key used to derive the `publicKeyJwk` using the protocol-path key derivation scheme.
1131
+
1176
1132
##### Processing Instructions
1177
1133
1178
1134
When processing a `ProtocolsConfigure` message, a conforming implementation ****MUST**** perform the following steps:
@@ -1630,16 +1586,54 @@ The `PermissionQuery` method exists to facilitate lookup of any retained Permiss
1630
1586
1631
1587
The Sync interface and its methods allow different Decentralized Web Nodes to communicate and sync on the state of the data they contain, including replication of messages and files.
1632
1588
1633
-
## Supported Encryption Schemes
1589
+
## Encryption
1590
+
1591
+
Each Decentralized Web Node (DWN) supports encryption at the individual message level. Encryption of data is performed using a symmetric key unique to each message. The symmetric key is then encrypted with one or more public keys derived using the HMAC-based Key Derivation Function as specified in [[spec:RFC5869]] together with one of the [key derivation path schemes](#key-derivation-path-schemes) defined in this specification. Each key derivation path scheme is optimized for a particular usage pattern of the Decentralized Web Node. Application and protocol developers can select schemes that best fit their requirements.
1592
+
1593
+
Encrypted messages must include an `encryption` property. This property contains the encrypted symmetric key(s) and metadata related to asymmetric key derivation. The `encryption` property allows the recipient, who possesses the corresponding private key, to decrypt the symmetric key and, consequently, the message data itself. For complete details on the `encryption` property, refer to [RecordsWrite](#recordswrite).
1594
+
1595
+
To enable encryption within a protocol, developers must declare the `$encryption` property in the protocol's definition as detailed in [Protocol Definitions](#protocol-definitions).
1596
+
1597
+
1598
+
### Key Derivation Path Schemes
1599
+
1600
+
#### Protocol Path Scheme
1601
+
1602
+
This scheme enables the owner of a Decentralized Web Node to derive and specify public keys at each level of the protocol path hierarchy, facilitating incoming encrypted communication from others without the need for additional bootstrapping.
1603
+
1604
+
Due to the hierarchical nature of the keys, the private key corresponding to any given protocol path can decrypt all records in the descending protocol paths. This feature allows protocol designers to strategically distribute the private key at specific protocol path levels based on their specific requirements.
1605
+
1606
+
The hierarchical derivation path segments of this scheme must follow the structure:
This scheme allows the initiator of a new record context to derive and specify a public key that encrypts all symmetric keys within the context. The holder of the corresponding context derived private key can decrypt all messages within the context.
1616
+
1617
+
Under this scheme, a recommended pattern for distributing the private key to a participant is to include the encrypted private key in the participant's _role record_ itself. This encryption uses the public key declared in the recipient's own instance of the configuration of the same protocol. This approach ensures that all essential cryptographic materials remain within the record context hierarchy.
1618
+
1619
+
The derivation path segments of this scheme must use the structure below:
1620
+
1621
+
```json
1622
+
["protocolContext", <root-context-id>]
1623
+
```
1624
+
1625
+
1626
+
### Supported Encryption Schemes
1634
1627
1635
1628
A conforming implementation ****MUST**** be capable of encrypting and decrypting data stored in Decentralized Web Nodes using the following combinations of cryptographic schemes. Each scheme is a pair, wherein the symmetric keys are used to encrypt the data being protected, then subsequently shared with permitted recipients via encryption of the symmetric keys using the asymmetric key of each recipient.
1636
1629
1637
1630
| Asymmetric Key | Symmetric Key |
1638
1631
| -------------- | ------------------- |
1632
+
|`ECIES-ES256K`|`AES-CTR`|
1639
1633
|`X25519`|`AES-GCM`|
1640
1634
|`X25519`|`XSalsa20-Poly1305`|
1641
1635
1642
-
## Supported Encryption Formats
1636
+
###Supported Encryption Formats
1643
1637
1644
1638
A conforming implementation ****MUST**** be capable of encrypting and decrypting data stored in Decentralized Web Nodes using the following combinations of cryptographic schemes. Each scheme is a pair, wherein the symmetric keys are used to encrypt the data being protected, then subsequently shared with permitted recipients via encryption of the symmetric keys using the asymmetric key of each recipient.
0 commit comments