feat: update language around commitments

decentralized-identity · Jun 12, 2020 · 2071e92 · 2071e92
1 parent 08b3586
commit 2071e92
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 18 deletions.
diff --git a/docs/spec/common-functions.md b/docs/spec/common-functions.md
@@ -16,8 +16,27 @@ Pseudo-code example using current protocol defaults:
 let HashingOutput = Base64URL( Multihash(DATA, 'sha2-256') );
 ```
 
-### Commitment Value Generation
+### Commitment Schemes
 
-The values used as the revealed secrets for Sidetree's commit/reveal mechanism ****MUST**** be the [JCS canonicalized](https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-17) [IETF RFC 7517](https://tools.ietf.org/html/rfc7517) JWK representations of cryptographic public keys. Implementers and wallets ****SHOULD NOT**** reuse keypairs across recovery invocations, and ****MUST NOT**** reuse commitment values (hashes of the JWK reveal values) across the entire lifetime of a DID.
+[Commitment schemes](#commitment-scheme) are used by the Sidetree protocol in important ways to preserve the integrity of operations and assist in key recovery.
 
-The secret JWK values published during the reveal phase of Sidetree's commit/reveal mechanism ****SHOULD**** be deterministically regenerable, to minimize the number of sensitive values User Agent wallet applications need to track, secure, and store. The most common way to allow for a regenerable JWK value is to use a key derivation scheme, wherein the JWK value that was committed in the commitment phase is able to be regenerated at a later time (e.g. hardened BIP32 HD key generation).
+#### Operation Commitment Scheme { #operation-commitment-scheme }
+
+The following section defines the [commitment scheme](#commitment-scheme) for generating an [operation commitment](#operation-commitment) along with 
+how the [operation commit value](#operation-commit-value) is generated.
+
+The [operation commit value](#commit-value) used to generate a [operation commitment](#next-operation-commitment) ****MUST**** be sufficiently randomly generated such that there is negligible probability that the same value will be used in another operation.
+
+The length of the [coperation ommit value](#operation-commit-value) used to generate a [operation commitment](#operation-commitment) ****MUST**** be of the length equal to that as defined by [OPERATION_COMMIT_VALUE_SIZE](#operation-commit-value-size).
+
+The [operation commitment](#next-operation-commitment) is obtained by hashing the [operation commit value](#operation-commit-value) using the defined [HASH_ALGORITHM](#hash-algorithm).
+
+The [commit value](#commit-value) used to generate a [operation commitment](#next-operation-commitment) ****SHOULD**** be deterministically re-generable using information associated to the DID to which the operation pertains to, in order to reduce the possibility of irrecoverable loss.
+
+#### Recovery Commitment Scheme { #recovery-commitment-scheme }
+
+The following section defines the [commitment scheme](#commitment-scheme) for generating a [recovery commitment](#recovery-commitment) from a [recovery key pair](#recovery-key-pair).
+
+The public key of the [recovery key pair](#recovery-key-pair) used to generated a [recovery commitment](#recovery-commitment) ****MUST**** be in the form of a valid [JWK](https://tools.ietf.org/html/rfc7517), in this form the public key ****MUST**** then be [canonicalized](#canonicalized) using [JSON Canonicalization Scheme](https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-17), the output value of this [canoncalization](#canonicalization) ****MUST**** then be hashed using the defined [HASH_ALGORITHM](#hash-algorithm) to produce the [recovery commitment](#recovery-commitment).
+
+Implementers ****MUST NOT**** re-use [recovery key pairs](#recovery-key-pairs) across different recovery invocations.
diff --git a/docs/spec/operations.md b/docs/spec/operations.md
@@ -23,28 +23,28 @@ Sidetree Methods MAY rely on the DID Document data model when verifying protocol
 
 Use the following process to generate a Sidetree-based DID:
 
-1. Generate a recovery key pair via the [`KEY_ALGORITHM`](#key-algorithm), retaining the [_Initial Recovery Public Key_](#initial-recovery-key){id="initial-recovery-key"} for use in generating the _Recovery Commitment_, and the private key for use in the next [Recovery](#recover) operation.
-2. Create a _Recovery Commitment_ using the [Hashing Process](#hashing-process) to generate a hash value from the [JCS canonicalized](https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-17) [IETF RFC 7517](https://tools.ietf.org/html/rfc7517) JWK representation of the [_Initial Recovery Public Key_](#initial-recovery-key), and retain the hash value for inclusion in an [Anchor File](#anchor-file) (if publication of the DID is desired).
-3. Generate an update key pair via the [`KEY_ALGORITHM`](#key-algorithm), retaining the _Next Update Public Key_ for use in generating the _Update Commitment_, and the private key for use in the next [Update](#update) operation.
-4. Create an _Update Commitment_ using the [Hashing Process](#hashing-process) to generate a hash value from the [JCS canonicalized](https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-17) [IETF RFC 7517](https://tools.ietf.org/html/rfc7517) JWK representation of the _Next Update Public Key_, and retain the hash value for inclusion in the [_Create Operation Delta Object_](#create-delta-object)(as described below).
-5. Generate an encoded representation of the following object using the implementation's [`DATA_ENCODING_SCHEME`]#data-encoding-scheme), herein referred to as the [_Create Operation Delta Object_](#create-delta-object){ id="create-delta-object" }:
+1. Generate a [recovery key pair](#recovery-key-pair) using the defined [`KEY_ALGORITHM`](#key-algorithm), where the public key of this pair is used for generating the [recovery commitment](#recovery-commitment), and the private key for use in the next [recovery](#recovery) operation.
+2. Generate a [recovery commitment](#recovery-commitment) using the defined [recovery commitment scheme](#recovery-commitment-scheme) and public key of the generated [recovery key pair](#recovery-key-pair).
+3. Generate an [operation commit value](#operation-commit-value), let the result be known as the _Update Operation Commit Value_.
+4. Generate an [operation commitment](#operation-commitment) using the _Update Operation Commit Value_ as the [operation commit value](#operation-commit-value), let the result be known as the _Update Operation Commitment_.
+5. Generate an encoded representation of the following object using the implementation's [`DATA_ENCODING_SCHEME`](#data-encoding-scheme), herein referred to as the [_Create Operation Delta Object_](#create-delta-object){ id="create-delta-object" }:
     ```json
     {
       "patches": [ PATCH_1, PATCH_2, ... ],
-      "update_commitment": HASH_OF_UPDATE_COMMITMENT_VALUE
+      "update_commitment": Update Operation Commitment
     }
     ```
-    - The object ****MUST**** contain a `patches` property, and its value ****MUST**** be an array of [DID State Patches](#did-state-patches).
-    - The object ****MUST**** contain a `update_commitment` property, and its value ****MUST**** be the _Update Commitment_, as described above.
+    - The object ****MUST**** contain a `patches` property, and its value ****MUST**** be a JSON array of [DID State Patches](#did-state-patches).
+    - The object ****MUST**** contain a `update_commitment` property, and its value ****MUST**** be the _Update Operation Commitment_, as described above.
 6. Generate an encoded representation of the following object using the implementation's [`DATA_ENCODING_SCHEME`](#data-encoding-scheme), herein referred to as the [_Create Operation Suffix Data Object_](#create-suffix-data-object){ id="create-suffix-data-object" }:
     ```json
     {
       "delta_hash": DELTA_HASH,
-      "recovery_commitment": COMMITMENT_HASH
+      "recovery_commitment": Recovery Commitment
     }
     ```
     - The object ****MUST**** contain a `delta_hash` property, and its value ****MUST**** be a hash of the decoded [_Create Operation Delta Object_](#create-delta-object) (detailed above), generated via the [Hashing Process](#hashing-process).
-    - The object ****MUST**** contain an `recovery_commitment` property, and its value ****MUST**** be an [_Initial Recovery Commitment_](#initial-recovery-commitment) (detailed above).
+    - The object ****MUST**** contain a `recovery_commitment` property, and its value ****MUST**** be a [recovery commitment](#recovery-commitment) (detailed above).
 
 ::: note
 Implementations ****MAY**** choose to define additional properties for inclusion in the [_Create Operation Suffix Data Object_](#create-suffix-data-object), but the presence of any properties beyond the standard properties or implementation-defined properties ****ARE NOT**** permitted.
@@ -63,7 +63,7 @@ The following process must be used to update the state a Sidetree-based DID:
     ```json
     {
       "patches": [ PATCH_1, PATCH_2, ... ],
-      "update_commitment": HASH_OF_UPDATE_COMMITMENT_VALUE
+      "update_commitment": Update Operation Commitment
     }
     ```
     - The object ****MUST**** contain a `patches` property, and its value ****MUST**** be an array of [DID State Patches](#did-state-patches).
@@ -97,7 +97,7 @@ Use the following process to recover a Sidetree-based DID:
     ```json
     {
       "patches": [ PATCH_1, PATCH_2, ... ],
-      "update_commitment": HASH_OF_UPDATE_COMMITMENT_VALUE
+      "update_commitment": Update Operation Commitment
     }
     ```
     - The object ****MUST**** contain a `patches` property, and its value ****MUST**** be an array of [DID State Patches](#did-state-patches).
@@ -107,7 +107,7 @@ Use the following process to recover a Sidetree-based DID:
     {
       "protected": {...},
       "payload": {
-        "recovery_commitment": COMMITMENT_HASH,
+        "recovery_commitment": Recovery Commitment,
         "recovery_key": JWK_OBJECT,
         "delta_hash": DELTA_HASH
       },

diff --git a/docs/spec/parameters.md b/docs/spec/parameters.md
@@ -12,8 +12,8 @@ Each version of the protocol will define a set of protocol rules and parameters
 | `CAS_PROTOCOL` { #cas-protocol }       | The CAS network protocol used within an implementation.            |               IPFS |
 | `CAS_URI_ALGORITHM` { #cas-uri-algorithm }       | Algorithm for generating unique content-bound identifiers for the implementation-selected CAS protocol                      |           IPFS CID |
 | `COMPRESSION_ALGORITHM` { #compression-algorithm } | File compression algorithm                             |                ZIP |
-| `COMMITMENT_HASH` { #commitment-hash } | Cryptographically random hash of a value to be revealed in the next operation. |      32 bytes |
 | `REVEAL_VALUE` { #reveal-value } | Cryptographically random value to be revealed in the next operation. |  100 bytes |
+| `OPERATION_COMMIT_VALUE_LENGTH` { #operation-commit-value-length } | The length of the [operation commit value](#operation-commit-value). |      32 bytes |
 | `GENESIS_TIME` { #genesis-time }                 | The point in the target ledger's transaction history at which Sidetree implementation is first activated (e.g. block number in a blockchain).    |             630000 |
 | `MAX_ANCHOR_FILE_SIZE` { #max-anchor-file-size } | Maximum compressed [Anchor File](#anchor-file) size.                     |               1 MB |
 | `MAX_MAP_FILE_SIZE` { #max-map-file-size }       | Maximum compressed map file size.                        |               1 MB |

diff --git a/docs/spec/terminology.md b/docs/spec/terminology.md
@@ -8,13 +8,19 @@
 | Chunk File  | JSON Document containing all verbose operation data for the corresponding set of DIDs specified in the related Map File.                   |
 | CAS { #cas }    | Content-addressable storage protocol/network (e.g. IPFS)                       |
 | CAS URI { #cas-uri }               | The unique content-bound identifier used to locate a resource via the [CAS](#cas) protocol/network (e.g. IPFS)                       |
+| Commit Value { #commit-value }         | A chosen value that is used with a [commitment scheme](#commitment-scheme)                                 |
+| Commitment { #commitment }           | The output of a [commitment scheme](#commitment-scheme)                                              |
+| Commitment Scheme { #commitment-scheme }     | A cryptographic primative that allows one to commit to a chosen value, known as the [commit value](#commit-value) resulting in the generation of a [commitment](#commitment). A [commitment](#commitment) can then be shared without revealing the [commit value](#commit-value) forming a `proof of commitment` where the posessor of the [commit value](#commit-value) can then later reveal the [commit value](#commit-value) proving the original commitment.
 | DID Document          | JSON Document containing public key references, service endpoints, and other PKI metadata that corresponds to a given DID (as defined in the [W3C DID Specification](https://w3c.github.io/did-core/)). |
 | DID Suffix { #did-suffix }  | The unique identifier string within a DID URI. e.g. The unique suffix of `did:sidetree:123` would be `123`. |
 | DID Suffix Data       | Data required to deterministically generate a DID.                             |
 | Multihash  { #multihash }            | Protocol for differentiating outputs from common cryptographic hash functions, addressing size + encoding considerations: https://multiformats.io/multihash/ |
 | DID Operation         | Set of delta-based modifications that change the state of a DID Document when applied.                                               |
 | Operation Request     | JWS formatted request sent to a _Sidetree Node_ to include a _DID Operation_ in a batch of operations.     |
-| Recovery Key          | Public/private key pair used to perform a Recovery or Deactivate operation. Must be encoded as JWK.          |
+| Operation Commit Value { #operation-commit-value } | The [commit value](#commit-value) used with the [operation commitment scheme](#operation-commitment-scheme) to produce an [operation commitment](#operation-commitment) |
+| Operation Commitment { #operation-commitment } | The resulting [commitment](#commitment) obtained by applying the [operation commitment scheme](#operation-commitment-scheme) |
+| Recovery Key Pair { #recovery-key-pair }    | Public/private key pair used to perform a Recovery or Deactivate operation.          |
+| Recovery Commitment { #recovery-commitment }   | The resulting [commitment](#commitment) obtained by applying the [recovery commitment scheme](#recovery-commitment-scheme) to the public key of a [recovery key pair](#recovery-key-pair)          |
 | Sidetree Node         | Executable code that implements all the required components, functionality, and rules specified in the Sidetree protocol specification.                            |
 | Transaction           | Ledger transaction that anchors a set of Sidetree operations, via a CAS URI for an associated Anchor File.          |
 | Anchor String  | The string anchored to the ledger, composed of the CAS URI to the [Anchor File](#anchor-file), prefixed with the declared operation count .                                               |