From 4a3214594783c044d541dc5d767bd0650dd219ee Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Thu, 3 Oct 2024 18:04:35 -0500 Subject: [PATCH 1/5] Minor hygiene items - open external links in a new tab (some via mdbook extension, others by hardcoding HTML) - fix reference to deprecated public key announcement in PRId algorithm - give a more useful internal link for assertionMethodPublicKeys in the Verifiable Credentials overview --- .spellcheckerdict.txt | 2 +- README.md | 3 +-- book.toml | 5 ++++- pages/DSNP/Types/PRId.md | 26 ++++++++++++------------- pages/VerifiableCredentials/Overview.md | 2 +- 5 files changed, 20 insertions(+), 18 deletions(-) diff --git a/.spellcheckerdict.txt b/.spellcheckerdict.txt index 20d3b397..5ecc5cc9 100644 --- a/.spellcheckerdict.txt +++ b/.spellcheckerdict.txt @@ -22,7 +22,6 @@ cryptographically [Cc]ryptosuites CtxSharedSecretA CtxSharedSecretB -CtxSharedSecretBob Curve25519 decrypt(ed)? Delegator @@ -100,6 +99,7 @@ repo resolvers RFC[1-9][0-9]* Ristretto +RootSharedSecretAB RPC S3 schemaless diff --git a/README.md b/README.md index a260dd71..ea6ea499 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,7 @@ Note: Remember that you can link to the tag on GitHub before creating the tag. To build the spec generator locally, install [mdBook](https://github.com/rust-lang/mdBook.git) and [link checker](https://github.com/Michael-F-Bryan/mdbook-linkcheck). The link checker will run during build process and throw warnings for any broken internal or external links. ``` bash -cargo install mdbook -cargo install mdbook-linkcheck +cargo install mdbook mdbook-linkcheck mdbook-external-links ``` To run the spec generator locally and preview the formatted spec website, use the following commands: diff --git a/book.toml b/book.toml index f9684958..aae194e0 100644 --- a/book.toml +++ b/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["Unfinished"] +authors = ["Project Liberty Institute"] language = "en" multilingual = false src = "pages" @@ -21,3 +21,6 @@ exclude = ['en\.bitcoin\.it', 'github\.com/LibertyDSNP/spec', 'w3\.org'] [output.html.fold] enable = true + +# https://github.com/jonahgoldwastaken/mdbook-external-links +[preprocessor.external-links] diff --git a/pages/DSNP/Types/PRId.md b/pages/DSNP/Types/PRId.md index 47342678..e14372e1 100644 --- a/pages/DSNP/Types/PRId.md +++ b/pages/DSNP/Types/PRId.md @@ -41,17 +41,17 @@ Definitions: Algorithm: 1. Both Alice and Bob generate an asymmetric key pair for use with X25519 ECIES. - Each publishes a Public Key Announcement with their generated public key with a `keyType` value of `keyAgreement`. + Each uses the [Replace User Data](../UserData.md#replace-user-data-operation) Operation to publish their generated public key in `keyAgreementPublicKeys`.
LibsodiumAlgorithm
-crypto_box_keypair(
+crypto_box_keypair(
   &a_public,
   &a_secret);
-crypto_box_keypair(
+crypto_box_keypair(
   &b_public, 
   &b_secret);
@@ -71,7 +71,7 @@ Algorithm:
LibsodiumAlgorithm
-crypto_box_beforenm(
+crypto_box_beforenm(
   &root_shared_secret,
   b_public,
   a_secret);
@@ -83,13 +83,13 @@ RootSharedSecretAB ←
-3. Alice derives a context-specific subkey CtxSharedSecretBob from the shared secret `RootSharedSecret` as the master key, Bob's DSNP User Id as the 64-bit key identifier, and the ASCII encoding of the [PRId Context](#contexts) string (`"PRIdCtx0"` for connections). +3. Alice derives a context-specific subkey CtxSharedSecretA→B from the shared secret RootSharedSecretAB as the master key, Bob's DSNP User Id as the 64-bit key identifier, and the ASCII encoding of the [PRId Context](#contexts) string (`"PRIdCtx0"` for connections).
LibsodiumAlgorithm
-crypto_kdf_derive_from_key(
+crypto_kdf_derive_from_key(
   ctx_shared_secret,
   32,
   b_user_id,
@@ -98,7 +98,7 @@ RootSharedSecretAB ←
 
-CtxSharedSecretA→B ←
+CtxSharedSecretA→B,C ←
   Blake2b256(
     key = RootSharedSecretAB,
     message = {},
@@ -108,7 +108,7 @@ CtxSharedSecretA→B ←
4. Alice uses Bob's DSNP User Id to form an 8-byte little-endian message. -Alice encrypts this message using [XSalsa20](http://cr.yp.to/snuffle/xsalsa-20110204.pdf) with the PRId key CtxSharedSecretA→B and a nonce of her own User Id (little-endian) followed by 16 zero bytes. +Alice encrypts this message using [XSalsa20](http://cr.yp.to/snuffle/xsalsa-20110204.pdf) with the PRId key CtxSharedSecretA→B,C and a nonce of her own User Id (little-endian) followed by 16 zero bytes. @@ -120,7 +120,7 @@ for (i = 0; i < 8; i++) { nonce[i] = (user_id_a >> (i*8)) & 0xff; }
-crypto_secretbox_detached( +crypto_secretbox_detached( &prid, &mac_unused, user_id_b, @@ -136,7 +136,7 @@ for (i = 0; i < 8; i++) { PRIdA→B,C ← XSalsa20( message = IdB, - key = CtxSharedSecretA→B, + key = CtxSharedSecretA→B,C, nonce = Padded24BytesLE(IdA) ) @@ -147,7 +147,7 @@ PRIdA→B,C ← Similarly, Bob can calculate the same root shared secret `RootSharedSecret` using Alicepublic and Bobsecret and derive the same PRIdA→B,C in order to check if it is in Alice's published PRIds. Bob can also derive the PRId subkey for Alice's DSNP User Id and encrypt Alice's User Id, using his own as the nonce, to generate the Bob-to-Alice PRId (PRIdB→A,C), and then publish it to his own list, if desired. -If Alice or Bob wants to prove to a third party that their PRIds are in each other's PRId list, they can provide the third party with their own subkey CtxSharedSecretA→B or CtxSharedSecretB→A. +If Alice or Bob wants to prove to a third party that their PRIds are in each other's PRId list, they can provide the third party with their own subkey CtxSharedSecretA→B,C or CtxSharedSecretB→A,C. The third party can repeat the encryption step using Alice and Bob's User Ids, and check that the output is present in the published set of PRIds. The root shared secret `RootSharedSecret` (used as a master key in this algorithm) should _not_ be divulged. ### Test Vector @@ -169,6 +169,6 @@ An implementation of the PRId generation algorithm should produce the following | Output | Value | | --- | --- | | PRIdA→B | `0xace4d2995b1a829c` | -| CtxSharedSecretA→B | `0x37cb1a870f0c1dce06f5116faf145ac2cf7a2f7d30136be4eea70c324932e6d2` | +| CtxSharedSecretA→B,C | `0x37cb1a870f0c1dce06f5116faf145ac2cf7a2f7d30136be4eea70c324932e6d2` | | PRIdB→A | `0x1a53b02a26503600` | -| CtxSharedSecretB→A | `0x32c45c49fcfe12f9db60e74fa66416c5a05832c298814d82032a6783a4b1fca0` | +| CtxSharedSecretB→A,C | `0x32c45c49fcfe12f9db60e74fa66416c5a05832c298814d82032a6783a4b1fca0` | diff --git a/pages/VerifiableCredentials/Overview.md b/pages/VerifiableCredentials/Overview.md index 13946305..1579244a 100644 --- a/pages/VerifiableCredentials/Overview.md +++ b/pages/VerifiableCredentials/Overview.md @@ -22,7 +22,7 @@ Current usage with DSNP relies on the following specifications: ### Cryptography The Data Integrity specification provides a generic format for expressing cryptographic proofs, where the detailed representation of each data item is defined in individual cryptosuites. -DSNP compliant applications MUST support the following cryptosuites, which correspond to the allowed algorithms for `assertionMethod` [Public Keys](../DSNP/Types/PublicKey.md): +DSNP compliant applications MUST support the following cryptosuites, which correspond to the allowed algorithms for the DSNP User Data item [`assertionMethodPublicKeys`](../DSNP/Types/PublicKeyUserData.md#allowed-key-types): | Specification | Version/Status | Multikey codec | | --- | --- | --- | From d0bd4de9505832033b367bfcac03da1e20235dfc Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Sun, 13 Oct 2024 11:48:09 -0500 Subject: [PATCH 2/5] Fix broken internal link --- pages/DSNP/Identifiers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/DSNP/Identifiers.md b/pages/DSNP/Identifiers.md index 02ea457a..521f4f1b 100644 --- a/pages/DSNP/Identifiers.md +++ b/pages/DSNP/Identifiers.md @@ -13,7 +13,7 @@ Graph connections are formed through the DSNP User Id. - MUST be a multibase string using the `base32` encoding - MUST represent a valid [multihash](https://github.com/multiformats/multihash) encoding of the hashing algorithm output for the bytes of the content -- MUST use a [Supported Hashing Algorithm](Announcements.md#supported-hashing-algorithms) +- MUST use a [Supported Hashing Algorithm](#supported-hashing-algorithms) ### Serialization Steps From 21a54d77bdeb611e4794d529eceb8586e56a369a Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Sun, 13 Oct 2024 22:52:03 -0700 Subject: [PATCH 3/5] See if cargo install is available --- .github/workflows/verify-pr.yaml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/verify-pr.yaml b/.github/workflows/verify-pr.yaml index 9bb5ea38..0f557ef2 100644 --- a/.github/workflows/verify-pr.yaml +++ b/.github/workflows/verify-pr.yaml @@ -24,9 +24,7 @@ jobs: run: npm run lint - name: Set up mdBook 📚 - uses: ./.github/workflows/common/set-up-mdbook - with: - token: ${{secrets.GITHUB_TOKEN}} + run: cargo install mdbook mdbook-linkcheck mdbook-external-links - name: Build mdBook 📚 run: mdbook build From 02d0b0473634e4a8361807a8afcfa3e36f8c74a4 Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Mon, 14 Oct 2024 11:38:08 -0700 Subject: [PATCH 4/5] Change shared action --- .github/workflows/common/set-up-mdbook/action.yaml | 9 +-------- .github/workflows/verify-pr.yaml | 4 +++- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/.github/workflows/common/set-up-mdbook/action.yaml b/.github/workflows/common/set-up-mdbook/action.yaml index 24aaa3f6..20e89c91 100644 --- a/.github/workflows/common/set-up-mdbook/action.yaml +++ b/.github/workflows/common/set-up-mdbook/action.yaml @@ -8,14 +8,7 @@ runs: using: "composite" steps: - name: Setup mdBook 📚 - uses: jontze/action-mdbook@0765bef0c7c5792f93bf3ed3d487a0ca32c9da33 - with: - token: ${{ inputs.token }} - mdbook-version: "~0.4.37" # Use a semver compatible string - # Optional Plugins have to be enabled - use-linkcheck: true - linkcheck-version: "~0.7.7" - + run: cargo install mdbook mdbook-linkcheck mdbook-external-links - name: Show mdbook version shell: bash run: mdbook --version diff --git a/.github/workflows/verify-pr.yaml b/.github/workflows/verify-pr.yaml index 0f557ef2..9bb5ea38 100644 --- a/.github/workflows/verify-pr.yaml +++ b/.github/workflows/verify-pr.yaml @@ -24,7 +24,9 @@ jobs: run: npm run lint - name: Set up mdBook 📚 - run: cargo install mdbook mdbook-linkcheck mdbook-external-links + uses: ./.github/workflows/common/set-up-mdbook + with: + token: ${{secrets.GITHUB_TOKEN}} - name: Build mdBook 📚 run: mdbook build From bb3b49f3d0bbe1c8c819b86b7c12a8a596357b46 Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Mon, 14 Oct 2024 12:33:25 -0700 Subject: [PATCH 5/5] Add shell property --- .github/workflows/common/set-up-mdbook/action.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/common/set-up-mdbook/action.yaml b/.github/workflows/common/set-up-mdbook/action.yaml index 20e89c91..e40fc825 100644 --- a/.github/workflows/common/set-up-mdbook/action.yaml +++ b/.github/workflows/common/set-up-mdbook/action.yaml @@ -8,6 +8,7 @@ runs: using: "composite" steps: - name: Setup mdBook 📚 + shell: bash run: cargo install mdbook mdbook-linkcheck mdbook-external-links - name: Show mdbook version shell: bash
LibsodiumAlgorithm