From 4a3214594783c044d541dc5d767bd0650dd219ee Mon Sep 17 00:00:00 2001 From: Wes Biggs Date: Thu, 3 Oct 2024 18:04:35 -0500 Subject: [PATCH] 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 | | --- | --- | --- |
LibsodiumAlgorithm