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
Problem
=======
See #263
Solution
========
- Moved old Public Key Announcement to "Migrated Announcements".
- Added Avro type PublicKey.
- Updated User Data section to define key agreement and assertion method
key types.
---------
Co-authored-by: Wes Biggs <[email protected]>
Copy file name to clipboardExpand all lines: pages/DSNP/Operations.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ Compliant implementations may respond to error conditions either synchronously,
34
34
| <aid="remove-control-key">Remove Control Key</a> | YES | User | Key |[Control Key Removal Record](Records.md#control-key-removal)|
35
35
| <aid="publish-announcement">Publish Announcement</a> | no*| User OR Delegate |[Announcement](Announcements.md)|[Announcement Published Record](Records.md#announcement-published)|
36
36
| <aid="publish-batch">Publish Batch</a> | no*| User OR Delegate |[Announcement Type](Announcements.md#announcement-types), [Batch Publication](BatchPublications.md) URL, Batch Publication Content Hash |[Batch Published Record](Records.md#batch-published)|
37
-
| <aid="get-user-data">Get User Data</a> | no | Any | User's Identifier, Set of Requested [User Data Types](UserData.md#user-data-types)| Map of [User Data Types](UserData.md#user-data-types) to [Data Chunks](UserData.md#data-chunks) with optional [Key Identifiers](Types/PublicKey.md#keyid)|
37
+
| <aid="get-user-data">Get User Data</a> | no | Any | User's Identifier, Set of Requested [User Data Types](UserData.md#user-data-types)| Map of [User Data Types](UserData.md#user-data-types) to [Data Chunks](UserData.md#data-chunks) with optional key identifiers of encryption keys for each chunk|
38
38
| <aid="replace-user-data">Replace User Data</a> | no | User OR Delegate | User's Identifier, [Key Identifier](Types/PublicKey.md#keyid), Map of [User Data Types](UserData.md#user-data-types) to [Data Chunks](UserData.md#data-chunks)|[User Data Replaced Record](Records.md#user-data-replaced)|
39
39
40
40
\* For each Announcement Type, an implementation may support one or both of these operations.
Represents an encoding of a public key, one half of a cryptographic key pair.
4
+
5
+
## Serialization
6
+
7
+
PublicKey object serialization MUST conform to the following [Avro](https://avro.apache.org) schema:
8
+
9
+
```
10
+
{
11
+
"namespace": "org.dsnp",
12
+
"name": "PublicKey",
13
+
"type": "record",
14
+
"fields": [
15
+
{
16
+
"name": "publicKey",
17
+
"type": "bytes",
18
+
"doc": "Multicodec public key"
19
+
}
20
+
]
21
+
}
22
+
```
23
+
24
+
## Generation
25
+
26
+
### publicKey
27
+
28
+
- MUST be a public key of an allowed key type for the associated User Data type, encoded in `multicodec` format
29
+
30
+
The byte encoding consists of a [multicodec](https://github.com/multiformats/multicodec/blob/master/table.csv) key identifier (as a varint) followed by the public key's binary data in the codec's described format.
31
+
32
+
#### Allowed Key Types
33
+
34
+
| User Data Type | Allowed Algorithms ([multicodec](https://github.com/multiformats/multicodec/blob/master/table.csv)) | Purpose |
35
+
| --- | --- | --- |
36
+
|`keyAgreementPublicKeys`|`x25519-pub`| A Curve25519 public key that can be used in key exchange protocols to generate a shared secret |
37
+
|`assertionMethodPublicKeys`|`ed25519-pub`| A public key for the EdDSA signature scheme using SHA-512 and Curve25519 that can be used to verify cryptographic signatures |
Data for each data type is initially formatted as a stream of Avro objects that should conform to the schema specified.
26
+
A DSNP system MAY limit the number of objects allowed for a given user data type; if so, this MUST be documented.
24
27
Avro file- and block-level information (including in-stream schema) is omitted.
25
28
The Avro stream is then compressed and/or encrypted as specified.
26
29
@@ -29,7 +32,7 @@ In the specification of cryptographic operations below, relevant methods from th
29
32
30
33
## Data Chunks
31
34
32
-
Because blockchain systems often have specific limits to the amount of data that can be included in a given transaction, operations on user data deal with the data in discrete chunks.
35
+
Because consensus systems often have specific limits to the amount of data that can be included in a given transaction, operations on user data deal with the data in discrete chunks.
33
36
As implementation strategies may vary, implementations MUST define their own maximum chunk size in bytes to be used in the operations described below.
34
37
35
38
## Entity Tags
@@ -46,8 +49,8 @@ The Replace User Data Operation takes the following parameters:
46
49
47
50
* A DSNP User Id
48
51
* Implementations MUST ensure that the principal invoking this Operation is this user, or a transparent chain of delegation from the user to the principal exists.
49
-
*A [Key Identifier](Types/PublicKey.md#keyid) for the `keyAgreement` key pair used to encrypt any private data in the operation.
50
-
(If only unencrypted user data types are included, the key identifier is optional.)
52
+
*The index of the `keyAgreementPublicKeys` key pair used to encrypt any private data in the operation.
53
+
(If only unencrypted user data types are included, the key index may be omitted.)
51
54
* A map containing the set of data types to update as the keys, and tuples consisting of (1) the schema version used to encode the data type, and (2) a list where each element includes a data chunk and its associated entity tag, as the values.
52
55
53
56
If the Operation is successful, any previous data associated with the user for each data type included in the input MUST be removed and replaced by the new data.
@@ -61,9 +64,9 @@ Data chunks should be generated for each included data type using the following
61
64
3. For each chunk generated, the application should then:
62
65
1. If the data type requires compression, apply the compression codec noted.
63
66
1. If the data type requires encryption,
64
-
1. Retrieve the user's active (most recently announced) `keyAgreement` public key, U<sub>public</sub>.
65
-
The `keyId` in the announcement should match the key identifier provided for this Operation.
66
-
If no key exists, one should be created and published as an Announcement before invoking the Operation.
67
+
1. Retrieve the user's active `keyAgreementPublicKey`key, U<sub>public</sub>, and note its index.
68
+
If no key exists, one should be created and published as User Data before invoking the Operation.
69
+
By convention, the key with the highest index (the last object in the Avro stream) is the active key.
67
70
1. Create a sealed box (a payload encrypted with a symmetric key derived from an ephemeral key pair, and accompanied by the ephemeral public key), as in the [libsodium](https://doc.libsodium.org/public-key_cryptography/sealed_boxes) function `crypto_box_seal`, using U<sub>public</sub>.
68
71
1. Include the previous `etag` value for the chunk. If the chunk is new, `etag` should be set to `null`.
69
72
If any chunks are to be deleted, they should be included in the input identified with the existing `etag` and a `null` value for the data.
@@ -151,13 +154,13 @@ The Get User Data Operation takes the following parameters:
151
154
* Note: While _writing_ user data is reserved for the user and any delegates, anyone on the network can read any user's data (though it may be encrypted).
152
155
* The User Data Types (by system name) that should be retrieved.
153
156
154
-
The operation returns a mapping of User Data Type to data chunks, with each data chunk annotated with an entity tag and (optionally) a key identifier. (Note that this is the same general structure as the input data for [Replace User Data](#replace-user-data-operation), for each requested data type.
157
+
The operation returns a mapping of User Data Type to data chunks, with each data chunk annotated with an entity tag and (optionally) a key index. (Note that this is the same general structure as the input data for [Replace User Data](#replace-user-data-operation), for each requested data type.
155
158
If no chunks for a requested data type exist, an implementation MAY omit that data type from the response.
156
159
157
160
To transform the data from the output to Avro binary records, a consumer should apply the following algorithm to each data type included:
158
161
1. Determine the relevant encryption algorithm, compression codec, and object schema from the User Data Type and version noted.
159
162
1. For each chunk,
160
-
1. If encryption is indicated, decrypt the chunk data using the user's secret key (identified using the key identifier) as in the [libsodium](https://doc.libsodium.org/public-key_cryptography/sealed_boxes) function `crypto_box_seal_open`.
163
+
1. If encryption is indicated, decrypt the chunk data using the user's secret key (identified using the key index) as in the [libsodium](https://doc.libsodium.org/public-key_cryptography/sealed_boxes) function `crypto_box_seal_open`.
161
164
1. If compression is required, uncompress the chunk data using the specified codec.
162
165
1. Deserialize the uncompressed data to logical records according to the Avro object schema.
163
166
1. Retain the chunk's `etag` value if needed for any updates.
Copy file name to clipboardExpand all lines: pages/Frequency/UserData.md
+4-8Lines changed: 4 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -1,27 +1,23 @@
1
1
# Frequency User Data
2
2
3
-
On Frequency, User Data and select Announcements are mapped to Schemas which use [Stateful Storage](https://frequency-chain.github.io/frequency/pallet_stateful_storage/index.html) for storage and retrieval of the data.
3
+
On Frequency, User Data is mapped to Schemas which use [Stateful Storage](https://frequency-chain.github.io/frequency/pallet_stateful_storage/index.html) for storage and retrieval of the data.
4
4
5
5
## User Data Sets
6
6
7
7
<!-- Update ./Overview.md if a Schema Id is updated -->
8
8
9
9
| User Data Set | Deployed Schema Ids | Frequency Model Type | Frequency Payload Location | Settings |
[Pseudonymous Relationship Identifiers](./../DSNP/Graph.md#pseudonymous-relationship-identifiers) (PRIds) are stored along side Private Connections in the same Stateful Storage page.
17
+
[Pseudonymous Relationship Identifiers](./../DSNP/Graph.md#pseudonymous-relationship-identifiers) (PRIds) are stored alongside Private Connections in the same Stateful Storage page.
16
18
17
19
Source code for each schema is located in the [LibertyDSNP/schemas](https://github.com/LibertyDSNP/schemas) repository.
18
20
19
-
## Announcements
20
-
21
-
| Announcement | Deployed Schema Ids | Frequency Model Type | Frequency Payload Location | Settings |
0 commit comments