From 25a72fe0c7c585f2e1fbde023d737808288bc320 Mon Sep 17 00:00:00 2001 From: Wes Biggs <40926006+wesbiggs@users.noreply.github.com> Date: Mon, 28 Oct 2024 10:36:52 -0500 Subject: [PATCH] Minor hygiene items (#291) - 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 - name items in the PRId description a little more consistently --------- Co-authored-by: Wes Biggs --- .../common/set-up-mdbook/action.yaml | 10 ++----- .spellcheckerdict.txt | 2 +- README.md | 3 +-- book.toml | 5 +++- pages/DSNP/Identifiers.md | 2 +- pages/DSNP/Types/PRId.md | 26 +++++++++---------- pages/VerifiableCredentials/Overview.md | 2 +- 7 files changed, 23 insertions(+), 27 deletions(-) diff --git a/.github/workflows/common/set-up-mdbook/action.yaml b/.github/workflows/common/set-up-mdbook/action.yaml index 24aaa3f6..e40fc825 100644 --- a/.github/workflows/common/set-up-mdbook/action.yaml +++ b/.github/workflows/common/set-up-mdbook/action.yaml @@ -8,14 +8,8 @@ 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" - + shell: bash + run: cargo install mdbook mdbook-linkcheck mdbook-external-links - name: Show mdbook version shell: bash run: mdbook --version 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/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 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 | | --- | --- | --- |
LibsodiumAlgorithm