From f9db0c9304a122cccfc2dd7b200b9a3ead4ed497 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Mon, 1 Jul 2024 16:43:06 -0700 Subject: [PATCH] Add rationale files --- README.md | 17 ++++++----------- design/README.md | 3 +++ design/cid_configuration.md | 11 +++++++++++ design/cryptosuite.md | 11 +++++++++++ 4 files changed, 31 insertions(+), 11 deletions(-) create mode 100644 design/README.md create mode 100644 design/cid_configuration.md create mode 100644 design/cryptosuite.md diff --git a/README.md b/README.md index 563edccc..d1121ab5 100644 --- a/README.md +++ b/README.md @@ -395,12 +395,12 @@ All UCANs MUST be canonically encoded with [DAG-CBOR] for signing. A UCAN MAY be A UCAN token MUST be configured as follows: -| Parameter | REQUIRED Configuration | -|--------------|-------------------------| -| Version | [CIDv1] | -| [Multibase] | [`base58btc`] [^b58btc] | -| [Multihash] | [SHA-256] | -| [Multicodec] | [DAG-CBOR] | +| Parameter | REQUIRED Configuration | +|--------------|------------------------| +| Version | [CIDv1] | +| [Multibase] | [`base58btc`] | +| [Multihash] | [SHA-256] | +| [Multicodec] | [DAG-CBOR] | > [!NOTE] > All CIDs encoded as above start with the characters `zdpu`. @@ -563,10 +563,6 @@ If a PITM attack was successfully performed on a UCAN delegation, the proof chai It is possible to use other algorithms, but doing so limits interoperability with the broader UCAN ecosystem. This is thus considered "off spec" (i.e. non-interoperable). If you choose to extend UCAN with additional algorithms, you MUST include this metadata in the (self-describing) [Varsig] header. -## Why must those specific signature algorithms be supported? - -In an ideal world, a single algorithm (Ed25519) would be available everywhere. For many historical reasons, P-256 and `secp256k1` are the only practical options for many applications, such as the [WebCrypto API] and many cryptocurrency wallets. A design goal of UCAN is to leverage existing public key infrastructure (PKI), and supporting these three algorithms achieves that goal. Requiring multiple signature types for broad interoperability is not an unusual design choice; for example, [JWT] supports multiple signature algorithms for a similar reason. - # Related Work and Prior Art [SPKI/SDSI] is closely related to UCAN. A different encoding format is used, and some details vary (such as a delegation-locking bit), but the core idea and general usage pattern are very close. UCAN can be seen as making these ideas more palatable to a modern audience and adding a few features such as content IDs that were less widespread at the time SPKI/SDSI were written. @@ -615,7 +611,6 @@ We want to especially recognize [Mark Miller] for his numerous contributions to -[^b58btc]: The choice of `base58btc` retains compatibility with common CID tools, and forces a canonical CID encoding unlike `base32`'s case-insensitivity. [^pcec]: To be precise, this is a [PC/EC][PACELC] system, which is a critical trade-off for many systems. UCAN can be used to model both PC/EC and PA/EL, but is most typically PC/EL. diff --git a/design/README.md b/design/README.md new file mode 100644 index 00000000..5ab30763 --- /dev/null +++ b/design/README.md @@ -0,0 +1,3 @@ +# Design + +This directory includes the rationale for various parts of the design contained in this repository. This is intended to provide a record for future decision making, and may be of interest to others working on their own protocols. diff --git a/design/cid_configuration.md b/design/cid_configuration.md new file mode 100644 index 00000000..b23c14c4 --- /dev/null +++ b/design/cid_configuration.md @@ -0,0 +1,11 @@ +# CID Configuration + +A single CID configuration makes canonicalization for signatures (and lookup) significantly simpler. The base encoding is set for when rendered for signatures, still is flexible for network lookup (e.g. with an IPFS gateway subdomain). + +## SHA-256 + +While BLAKE3 is faster in software, the SHA2 family is already a requirement of the signature algorithms in UCAN's cryptosuite. SHA2 is also available effectively everywhere. + +## `base58tc` + +The choice of [`base58btc`] retains compatibility with common CID tools, and forces a canonical CID encoding. The other common base at time of writing is `base32`, which is popular due to its compatability with various web technologies such as subdomain handling in browsers. Unfortunately, `base32` is case-insensitive, which poses a problem for CID canonicalization since multiple CIDs map to the same underlying hash. diff --git a/design/cryptosuite.md b/design/cryptosuite.md new file mode 100644 index 00000000..22544304 --- /dev/null +++ b/design/cryptosuite.md @@ -0,0 +1,11 @@ +# Cryptosuite + +## Signature Algorithms + +In an ideal world, a single algorithm (Ed25519) would be available everywhere. For many historical reasons, P-256 and `secp256k1` are the only practical options for many applications, such as the [WebCrypto API] and many cryptocurrency wallets. A design goal of UCAN is to leverage existing public key infrastructure (PKI), and supporting these three algorithms achieves that goal. Requiring multiple signature types for broad interoperability is not an unusual design choice; for example, [JWT] supports multiple signature algorithms for a similar reason. + +The NIST report on post-quantum computing will also be released in the next few months, so we anticipate a shift to new algorithms in the medium-term. + +## SHA-256 + +While BLAKE3 is faster in software, the SHA2 family is already a requirement of the signature algorithms in UCAN's cryptosuite. SHA-256 is also available effectively everywhere, and doesn't need to shipped as a separate package, which lowers implementation/maintenance complexity, and bundle size.