From eb6db05c65c7f14f8474eb74246042b4dde3465f Mon Sep 17 00:00:00 2001 From: Sander Dijkhuis Date: Tue, 20 Aug 2024 14:23:44 +0200 Subject: [PATCH] Turn into Internet-Draft --- .github/workflows/editor.yml | 51 ++ Makefile | 16 +- README.md | 2 +- ...is-cfrg-hierarchical-deterministic-keys.md | 492 +++++++++--------- feedback.md | 2 +- 5 files changed, 307 insertions(+), 256 deletions(-) create mode 100644 .github/workflows/editor.yml rename keys.md => draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md (60%) diff --git a/.github/workflows/editor.yml b/.github/workflows/editor.yml new file mode 100644 index 0000000..a6e9631 --- /dev/null +++ b/.github/workflows/editor.yml @@ -0,0 +1,51 @@ +name: Editor + +on: + push: + paths-ignore: + - media/deployment.svg + - Makefile + - README.md + - feedback.md + - prototype.worksheet.sc + - .gitignore + pull_request: + paths-ignore: + - media/deployment.svg + - Makefile + - README.md + - feedback.md + - prototype.worksheet.sc + - .gitignore + +permissions: + contents: write + +jobs: + build: + name: Editor’s Copy + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - id: setup + run: date -u "+date=%FT%T" >> $GITHUB_OUTPUT + - uses: actions/cache@v3 + with: + path: | + .refcache + .venv + .gems + node_modules + .targets.mk + key: i-d-${{ steps.setup.outputs.date }} + restore-keys: i-d- + - name: Build + uses: martinthomson/i-d-template@v1 + with: + token: ${{ github.token }} + - name: Publish + uses: martinthomson/i-d-template@v1 + if: ${{ github.event_name == 'push' }} + with: + make: gh-pages + token: ${{ github.token }} diff --git a/Makefile b/Makefile index 163c25f..b4b038e 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,16 @@ -pdf: +LIBDIR := lib +include $(LIBDIR)/main.mk + +$(LIBDIR)/main.mk: +ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) + git submodule sync + git submodule update $(CLONE_ARGS) --init +else + git clone -q --depth 10 $(CLONE_ARGS) \ + -b main https://github.com/martinthomson/i-d-template $(LIBDIR) +endif + +hdk.pdf: mkdir -p build cp -r media build echo \ @@ -6,7 +18,7 @@ pdf: "Hierarchical Deterministic Keys for the European Digital Identity Wallet" \ "" \ > build/hdk.html - npx -p @mermaid-js/mermaid-cli mmdc -i keys.md -o build/keys.md -e svg -t neutral -w 400 + npx -p @mermaid-js/mermaid-cli mmdc -i draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md -o build/keys.md -e svg -t neutral -w 400 cat README.md | \ sed -e "s/# Hierarchical Deterministic Keys for the European Digital Identity Wallet/# Introduction to Hierarchical Deterministic Keys/g" | \ sed -e "s/keys.md/#hierarchical-deterministic-keys/g" | \ diff --git a/README.md b/README.md index 42b570a..6104b4d 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Expert participants from Potential: ## Contents -To address challenges 5 and 6, this repository contains a freely accessible, unencumbered specification of **[Hierarchical Deterministic Keys](keys.md)**. This enables an EU Digital Identity Wallet deployment that distributes key management efficiently: +To address challenges 5 and 6, this repository contains a freely accessible, unencumbered specification of **[Hierarchical Deterministic Keys](draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md)**. This enables an EU Digital Identity Wallet deployment that distributes key management efficiently: ![A wallet architecture using Hierarchical Deterministic Keys associated with keys protected using a wallet secure cryptographic device, optionally using Asynchronous Remote Key Generation (ARKG).](media/deployment.svg) diff --git a/keys.md b/draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md similarity index 60% rename from keys.md rename to draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md index 8093ce3..f31688a 100644 --- a/keys.md +++ b/draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md @@ -1,16 +1,123 @@ -# Hierarchical Deterministic Keys - -**Version:** 0.2.0-SNAPSHOT - -**Authors:** Sander Dijkhuis (Cleverbase, editor) - -**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) - -## Introduction +--- +title: Hierarchical Deterministic Keys +abbrev: HDK +category: info +docname: draft-dijkhuis-cfrg-hierarchical-deterministic-keys-latest +submissiontype: independent +v: 3 +area: IRTF +workgroup: Crypto Forum +keyword: + - KDF +venue: + github: sander/hierarchical-deterministic-keys +author: + - fullname: Sander Dijkhuis + role: editor + initials: S. Q. + surname: Dijkhuis + organization: Cleverbase + email: mail@sanderdijkhuis.nl +ipr: trust200902 +normative: + I-D.draft-bradleylundberg-cfrg-arkg-02: + FIPS180-4: + title: Secure Hash Standard (SHS) + target: https://csrc.nist.gov/pubs/fips/180-4/upd1/final + seriesinfo: + FIPS: 180-4 + DOI: 10.6028/NIST.FIPS.180-4 + author: + - organization: National Institute of Standards and Technology (NIST) + date: 2012-06 + ISO18013-5: + title: "Personal identification — ISO-compliant driving licence – Part 5: Mobile driving licence (mDL) application" + target: https://www.iso.org/standard/69084.html + seriesinfo: + ISO/IEC: 18013-5:2021 + author: + - organization: ISO/IEC + date: 2019-09 + RFC2119: + RFC7800: + RFC8017: + RFC8174: + RFC9380: + SEC2: + title: "SEC 2: Recommended Elliptic Curve Domain Parameters, Version 2.0" + target: https://www.secg.org/sec2-v2.pdf + seriesinfo: + SEC: 2 Version 2.0 + author: + - organization: Certicom Research + date: 2010-01 + TR03111: + title: Elliptic Curve Cryptography + target: https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/Technische-Richtlinien/TR-nach-Thema-sortiert/tr03111/tr-03111.html + seriesinfo: + BSI: TR-03111 Version 2.10 + author: + - organization: Federal Office for Information Security (BSI) + date: 2018-06 +informative: + BIP32: + title: Hierarchical Deterministic Wallets + target: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki + seriesinfo: + BIP: 32 + author: + - name: Pieter Wuille + date: 2021-02 + draft-OpenID4VCI: + title: OpenID for Verifiable Credential Issuance, draft 13 + target: https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html + author: + - name: T. Lodderstedt + - name: K. Yasuda + - name: T. Looker + date: 2024-02-08 + EU2015-1502: + title: Commission Implementing Regulation (EU) 2015/1502 of 8 September 2015 on setting out minimum technical specifications and procedures for assurance levels for electronic identification means + target: https://eur-lex.europa.eu/legal-content/TXT/?uri=CELEX%3A32015R1502 + author: + - organization: European Commission + seriesinfo: + (EU): 2015/1502 + date: 2025-09 + EU2024-1183: + title: Amending Regulation (EU) No 910/2014 as regards establishing the European Digital Identity Framework + target: https://data.europa.eu/eli/reg/2024/1183/oj + author: + - organization: The European Parliament and the Council of the European Union + seriesinfo: + (EU): 2024/1183 + date: 2024-04 + SCAL3: + title: "SCAL3: Verify that systems operate under your sole control, version de8c5ae" + target: https://github.com/cleverbase/scal3 + author: + - organization: Cleverbase ID B.V. + date: 2024-03 + TR03181: + title: Cryptographic Service Provider 2 (CSP2) + target: https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/Technische-Richtlinien/TR-nach-Thema-sortiert/tr03181/TR-03181_node.html + author: + - organization: Federal Office for Information Security (BSI) + seriesinfo: + BSI: TR-03181 Version 0.94 + date: 2023-04 + +--- abstract + +Hierarchical Deterministic Keys enables managing large sets of keys bound to a secure cryptographic device that protects a single key. This enables the development of secure digital identity wallets providing many one-time-use public keys. + +--- middle + +# Introduction This document specifies the algorithms to apply Hierarchical Deterministic Keys (HDKs). The purpose of an HDK architecture is to manage large sets of keys bound to a secure cryptographic device that protects a single key. This enables the development of secure digital identity wallets providing many one-time-use public keys. -The core idea has been introduced in [[BIP32]] to create multiple cryptocurrency addresses in a manageable way. The present document extends the idea towards devices commonly used for digital wallets, and towards common interaction patterns for document issuance and authentication. +The core idea has been introduced in [BIP32] to create multiple cryptocurrency addresses in a manageable way. The present document extends the idea towards devices commonly used for digital wallets, and towards common interaction patterns for document issuance and authentication. To store many HDKs, only a seed string needs to be securely stored, associated with the device private key. Each HDK is then deterministically defined by a path of self-generated indices or provided key handles. Such a path can efficiently be stored and requires less confidentiality than the seed. @@ -22,98 +129,110 @@ An HDK instantiation is expected to be applied in a solution deployed as (wallet This document represents the consensus of the authors, based on working group input and feedback. It is not a standard. It does not include security or privacy proofs. -### Conventions and definitions +## Conventions and definitions -The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [[RFC2119]] [[RFC8174]] when, and only when, they appear in all capitals, as shown here. +{::boilerplate bcp14-tagged} The following notation is used throughout the document. - byte: A sequence of eight bits. -- `I2OSP(n, w)`: Convert non-negative integer `n` to a `w`-length, big-endian byte string, as described in [[RFC8017]]. +- `I2OSP(n, w)`: Convert non-negative integer `n` to a `w`-length, big-endian byte string, as described in [RFC8017]. -## The Hierarchical Deterministic Keys algorithm +# The Hierarchical Deterministic Keys algorithm -An HDK instantiation applies local key derivation to create many key pairs from a single seed value. It applies asynchronous remote key generation to enable providers to derive more key pairs. Additionally, an HDK instantiation applies these key pairs to blind a single key pair and proofs of its possession, such as required in [[RFC7800]]. +An HDK instantiation applies local key derivation to create many key pairs from a single seed value. It applies asynchronous remote key generation to enable providers to derive more key pairs. Additionally, an HDK instantiation applies these key pairs to blind a single key pair and proofs of its possession, such as required in [RFC7800]. Solutions MAY omit application of the asynchronous remote key generation functionality. In this case, a solution instance can only derive keys locally. -### Introductory examples +## Introductory examples -#### Local key derivation example +### Local key derivation example The following example illustrates the use of key derivation. An HDK tree is defined by an initial public key and a seed value, which is a byte array containing sufficient entropy. Now tree nodes are constructed as follows. -```mermaid -%%{init: {"flowchart": { "htmlLabels": false}} }%% -flowchart -subgraph Confidential static data -pk_device(["pk_device"]) -seed(["seed"]) -end -pk_device --> root -seed --> root -subgraph Level 0 - root["(pk0, sk0, salt0) = hdk0 = HDK-Root(pk_device, seed)"] -end -subgraph Level 1 - root --> l1_0["(pk1, sk1, salt1) = HDK-Derive-Local(hdk0, 0)"] - root --> l1_1["HDK-Derive-Local(hdk0, 1)"] - root --> l1_2["HDK-Derive-Local(hdk0, 2)"] -end -subgraph Level 2 - l1_0 --> l2_0["HDK-Derive-Local((pk1, sk1, salt1), 0)"] - l1_0 --> l2_1["HDK-Derive-Local((pk1, sk1, salt1), 1)"] -end -``` +~~~ + ┌────────────────────────┐ + │Confidential static data│ + │┌─────────┐ ┌────┐ │ + ││pk_device│ │seed│ │ + │└────┬────┘ └──┬─┘ │ + └─────┼─────────┼────────┘ + ┌─────────────────┼─────────┼───────────────────────────┐ + │Level 0 ▼ ▼ │ + │┌─────────────────────────────────────────────────────┐│ + ││(pk0, sdk0, salt0) = hdk0 = HDK-Root(pk_device, seed)││ + │└────┬────────────────────────────────────────────────┘│ + └─────┼─────────────────────────────────────────────────┘ +Level 1 ▼ +┌─────────────────────────┐┌────────────────────────┐┌─────────────────────────┐ +│(pk1, sk1, salt1) = ││HDK-Derive-Local(hd0, 1)││HDK-Derive-Local(hdk0, 2)│ +│HDK-Derive-Local(hdk0, 0)││ ││ │ +└───────────┬────────┬────┘└────────────────────────┘└─────────────────────────┘ + │ └────────────────────────┐ + │ │ +┌───────────┼─────────────────────────────────┼──────────────────────────────┐ +│Level 2 ▼ ▼ │ +│┌────────────────────────────────────┐┌────────────────────────────────────┐│ +││HDK-Derive-Local((pk1,sk1,salt1), 0)││HDK-Derive-Local((pk1,sk1,salt1), 1)││ +│└────────────────────────────────────┘└────────────────────────────────────┘│ +└────────────────────────────────────────────────────────────────────────────┘ +~~~ The solution instance computes the Level 0 HDK at the root node using a deterministic function called HDK-Root. The HDK consists of a key pair `(pk0, sk0)`, and a byte string `salt0` to derive next-level keys. The solution instance computes the Level `n > 0` value is using a deterministic function called HDK-Derive-Local. The function takes the previous-level salt as input, and a sequence number `i` starting at 0. The function returns a new HDK as output. -#### Remote key derivation example +### Remote key derivation example -Instead of a locally generated index, an HDK can also be derived using a key handle as per Asynchronous Remote Key Generation (ARKG) [[draft-bradleylundberg-cfrg-arkg]]. To enable ARKG, the solution instance uses HDK-Seed-Remote and provides the output public key to an issuer. The issuer returns a key handle, using which the solution instance can derive a next-level key pair and seed using HDK-Derive-Remote. +Instead of a locally generated index, an HDK can also be derived using a key handle as per Asynchronous Remote Key Generation (ARKG) [I-D.draft-bradleylundberg-cfrg-arkg-02]. To enable ARKG, the solution instance uses HDK-Seed-Remote and provides the output public key to an issuer. The issuer returns a key handle, using which the solution instance can derive a next-level key pair and seed using HDK-Derive-Remote. Locally derived parents can have remotely derived children. Remotely derived parents can have locally derived children. -#### Blinding example +### Blinding example The next concept to illustrate is blinding. Blinding enables a solution instance to prove possession of a private key without disclosing the directly associated public key. This way, solutions can avoid linkability across readers of a document that is released with proof of possession. In this example, a document is issued in such a way that it can be presented with proof of possession using `pk` as derived using HDK. The solution instance applies the HDK-Authenticate function to the associated `sk` along with the device private key `sk_device` and reader-provided `reader_data`. The output is `device_data`, which the solution instance can subsequently use to prove possession to the reader. The reader does not need to be aware that HDK was used. -```mermaid -%%{init: {"flowchart": { "htmlLabels": false}} }%% -flowchart LR -subgraph In secure cryptographic device - sk_device -end -subgraph HDK in solution instance - pk - sk -end -sk_device --> authenticate -sk --> authenticate -reader_data --> authenticate -authenticate("HDK-Authenticate") --> device_data -``` +~~~ +In secure +cryptographic +device +┌───────────┐ +│sk_device ┼─────────────┐ +└───────────┘ │ +───────────── │ +HDK in │ +solution │ +instance ▼ ┌───────────┐ +┌───────────┐ HDK-Authenticate─►│device_data│ +│pk │ ▲ ▲ └───────────┘ +└───────────┘ │ │ +┌───────────┐ │ │ +│sk ┼───────┘ │ +└───────────┘ │ +───────────── │ +┌───────────┐ │ +│reader_data┼─────────────┘ +└───────────┘ +~~~ Blinding methods can be constructed such that the secure cryptographic device does not need to be designed for it. In such cases, `sk_device` does not contain the value of the private device key but a reference to it. -### Instantiation parameters +## Instantiation parameters The parameters of an HDK instantiation are: - `ID`: A domain separation tag, represented as a string of ASCII bytes. -- `Nk`: The amount of bytes needed to create a uniformly random key. Note that `Nk` usually needs to be higher than the size of the key space, for example to maintain uniform distribution when deriving RNG({1,2,...,n-1}) from RNG({0,1,2,...,2^k-1}) for `k=8*Nk` and `2^k >= n` as per [[TR03111]] Section 4.1.1 Algorithm 2. +- `Nk`: The amount of bytes needed to create a uniformly random key. Note that `Nk` usually needs to be higher than the size of the key space, for example to maintain uniform distribution when deriving RNG({1,2,...,n-1}) from RNG({0,1,2,...,2^k-1}) for `k=8*Nk` and `2^k >= n` as per [TR03111] Section 4.1.1 Algorithm 2. - `Ns`: The amount of bytes of a salt value with sufficient entropy. - `key(bytes)`: Deterministically outputs a key pair `(pk, sk)` from a uniformly random string of `Nk` bytes. - `serialize(pk)`: Serializes a public key `pk` to a fixed-size string. - `expand(msg, DST, L)`: Outputs a uniformly random string of `L` bytes using a cryptographic hash or extendable-output function and input byte strings `msg` and `DST`. -- `BL`: An asymmetric key blinding scheme [[draft-bradleylundberg-cfrg-arkg]], consisting of the functions: +- `BL`: An asymmetric key blinding scheme [I-D.draft-bradleylundberg-cfrg-arkg-02], consisting of the functions: - BL-Blind-Public-Key(pk, tau, info): Outputs `pk` blinded with blinding factor `tau` and domain separation parameter `info`, both byte strings. - BL-Blind-Private-Key(sk, tau, info): Outputs `sk` blinded with blinding factor `tau` and domain separation parameter `info`, both byte strings. -- `ARKG`: An asynchronous remote key generation instantiation [[draft-bradleylundberg-cfrg-arkg]], encapsulating an asymmetric key blinding scheme instantiation `BL` and a key encapsulation mechanism `KEM`, and consisting of the functions: +- `ARKG`: An asynchronous remote key generation instantiation [I-D.draft-bradleylundberg-cfrg-arkg-02], encapsulating an asymmetric key blinding scheme instantiation `BL` and a key encapsulation mechanism `KEM`, and consisting of the functions: - ARKG-Derive-Public-Key(pk, info): Outputs `(pk', kh)` where `pk'` is a derived public key and `kh` is a key handle to derive the associated private key, based on an ARKG public seed `pk = (pk_kem, pk_bl)` and application-specific information `info`. - ARKG-Derive-Private-Key(sk, kh, info): Outputs `sk'`, a blinded private key Scalar based on ARKG private seed `sk = (sk_kem, sk_bl)`, a key handle `kh`, and application-specific information `info`. - `HDK-Root(pk_device, seed)`: See [The HDK-Root function](#the-hdk-root-function). @@ -122,11 +241,11 @@ The parameters of an HDK instantiation are: A concrete HDK instantiation MUST specify the instantiation of each of the above functions and values. -### The HDK-Root function +## The HDK-Root function A solution instance creates a root HDK using a seed and a device public key. The generation of the seed is out of scope for this specification. -``` +~~~ Inputs: - pk_device, a device public key. - seed, a string of Ns bytes. @@ -137,13 +256,13 @@ Outputs: - salt, the root salt. def HDK-Root(pk_device, seed) -``` +~~~ -### The HDK-Derive-Local function +## The HDK-Derive-Local function A solution instance derives a key pair and a salt from an HDK and an index. -``` +~~~ Inputs: - pk, a public key. - sk, a private key. @@ -164,13 +283,13 @@ def HDK-Derive-Local((pk, sk, salt), index): pk' = BL-Blind-Public-Key(pk, tau, info) salt' = okm[Nk:] return (pk', sk', salt') -``` +~~~ -### The HDK-Seed-Remote function +## The HDK-Seed-Remote function A solution instance derives an ARKG seed from an HDK. -``` +~~~ Inputs: - pk, a public key. - sk, a private key. @@ -186,19 +305,19 @@ def HDK-Seed-Remote((pk, sk, salt)): pk_bl = pk sk_bl = sk return ((pk_kem, pk_bl), (sk_kem, sk_bl)) -``` +~~~ Given an ARKG public seed `pk`, an issuer can derive an ARKG key handle `kh` and blinded public key `pk'` using: -``` +~~~ (pk', kh) = ARKG-Derive-Public-Key(pk, "") -``` +~~~ -### The HDK-Derive-Remote function +## The HDK-Derive-Remote function A solution instance derives a key pair and a salt from an HDK and an ARKG key handle. -``` +~~~ Inputs: - pk_device, the device public key. - pk, a public key. @@ -212,13 +331,13 @@ Outputs: - salt', the next-level salt for the provided key handle. def HDK-Derive-Remote(pk_device, (pk, sk, salt), kh) -``` +~~~ -### The HDK-Authenticate function +## The HDK-Authenticate function A solution instance authenticates the device by creating a blinded proof applying the device private key and an HDK private key. This yields device data which it can use to prove possession of the device-bound document. The application-specific data for proof of possession is out of scope for HDK. -``` +~~~ Inputs: - sk_device, a (reference to a) device private key. - sk_hdk, an HDK private key. @@ -228,15 +347,15 @@ Outputs: - device_data, a byte string of device data for proving possession. def HDK-Authenticate(sk_device, sk_hdk, reader_data) -``` +~~~ Implementations of this function typically perform pre-processing on the `reader_data`, invoke the device key operation on the result, and perform post-processing on the output. A HDK instantiation MUST define HDK-Authenticate such that the `device_data` can be verified using the public key in the same HDK as `sk_hdk`. The reader does not need to know that HDK was applied: the public key will look like any other public key used for proofs of possession. -## Generic HDK instantiations +# Generic HDK instantiations -### Using elliptic curves +## Using elliptic curves Instantiations of HDK using elliptic curves requires the following cryptographic construct: @@ -249,7 +368,7 @@ Instantiations of HDK using elliptic curves requires the following cryptographic These instantiations instantiate the following: -``` +~~~ def serialize(pk): return EC-Serialize-Element(pk) @@ -258,20 +377,20 @@ def key(bytes): sk = sk' + 1 pk = EC-Scalar-Base-Mult(sk) return (pk, sk) -``` +~~~ -### Using ECDH message authentication codes for proof of possession +## Using ECDH message authentication codes for proof of possession Such instantiations of HDK use elliptic curves (see [Using elliptic curves](#using-elliptic-curves)) and require the following cryptographic construct: -- `ECDH`: An Elliptic Curve Key Agreement Algorithm - Diffie-Hellman (ECKA-DH) [[TR03111]] with elliptic curve `EC`, consisting of the functions: +- `ECDH`: An Elliptic Curve Key Agreement Algorithm - Diffie-Hellman (ECKA-DH) [TR03111] with elliptic curve `EC`, consisting of the functions: - ECDH-Create-Shared-Secret(sk_self, pk_other): Outputs a shared secret byte string representing an Element. -In such instantiations, the reader provides an ephemeral public key `reader_data`. The HDK-Authenticate function returns `device_data` consisting of a binary encoded x-coordinate `Z_AB` of an ECDH operation with `sk_device` and `sk_hdk`. Subsequently, the solution instance creates a message authentication code (MAC), such as in ECDH-MAC authentication defined in [[ISO18013-5]]. The reader verifies this MAC by performing an ECDH operation with its ephemeral private key and the HDK public key. +In such instantiations, the reader provides an ephemeral public key `reader_data`. The HDK-Authenticate function returns `device_data` consisting of a binary encoded x-coordinate `Z_AB` of an ECDH operation with `sk_device` and `sk_hdk`. Subsequently, the solution instance creates a message authentication code (MAC), such as in ECDH-MAC authentication defined in [ISO18013-5]. The reader verifies this MAC by performing an ECDH operation with its ephemeral private key and the HDK public key. These instantiations instantiate the following: -``` +~~~ def HDK-Root(pk_device, seed): msg = serialize(pk_device) okm = expand(msg, ID || seed, Nk + Ns) @@ -295,13 +414,13 @@ def HDK-Authenticate(sk_device, sk_hdk, reader_data): Z_AB = ECDH-Create-Shared-Secret(sk_device, P') return Z_AB -``` +~~~ -### Using EC-SDSA signatures for proof of possession +## Using EC-SDSA signatures for proof of possession Such instantiations of HDK use elliptic curves (see [Using elliptic curves](#using-elliptic-curves)) require the following cryptographic construct: -- `DSA`: an EC-SDSA (Schnorr) digital signature algorithm [[TR03111]], consisting of the functions: +- `DSA`: an EC-SDSA (Schnorr) digital signature algorithm [TR03111], consisting of the functions: - DSA-Sign(sk, message): Outputs the signature `(c, r)` created using private signing key `sk` over byte string `message`. - DSA-Verify(signature, pk, message): Outputs whether `signature` is a signature over `message` using public verification key `pk`. - DSA-Serialize(c, r): Outputs the byte array serialization of the signature `(c, r)`. @@ -311,7 +430,7 @@ The reader MUST create an input byte string `reader_data` with sufficient entrop The reader MUST verify the proof `device_data` using DSA-Verify with the HDK public key. -``` +~~~ def HDK-Root(pk_device, seed): msg = serialize(pk_device) okm = expand(msg, ID || seed, Nk + Ns) @@ -336,57 +455,57 @@ def HDK-Authenticate(sk_device, sk_hdk, reader_data): s' = s + c * sk_hdk mod EC-Order() proof = DSA-Serialize(c, s') return proof -``` +~~~ -### Using ECDSA signatures for proof of possession +## Using ECDSA signatures for proof of possession Due to potential patent claims and potential related-key attacks, this document does not specify an implementation for threshold ECDSA. -## Concrete HDK instantiations +# Concrete HDK instantiations The RECOMMENDED instantiation is the HDK-ECDH-P256. This avoids the risk of having the holder unknowingly producing a potentially non-repudiable signature over reader-provided data. Secure cryptographic devices that enable a high level of assurance typically support managing ECDH keys with the P-256 elliptic curve. -### HDK-ECDH-P256 +## HDK-ECDH-P256 This instantiation uses ECDH (see [Using ECDH message authentication codes for proof of possession](#using-ecdh-message-authentication-codes-for-proof-of-possession)). - `ID`: `"HDK-ECDH-P256-v1"` - `Nr`: 48 - `Ns`: 32 -- `expand`: `expand_message_xmd` from [[RFC9380]] with: - - `H`: SHA-256 [[FIPS180-4]] +- `expand`: `expand_message_xmd` from [RFC9380] with: + - `H`: SHA-256 [FIPS180-4] - `b_in_bytes`: 32 - `s_in_bytes`: 64 -- `ARKG`: ARKG instantiation as described in [[draft-bradleylundberg-cfrg-arkg]] with the identifier `ARKG-P256MUL-ECDH`, `KEM` as defined above, and `BL` with elliptic curve arithmetic as described in [[draft-bradleylundberg-cfrg-arkg]] Section 3.1, but with multiplicative instead of additive blinding. -- `EC`: The NIST curve `secp256r1` (P-256) [[SEC2]]. +- `ARKG`: ARKG instantiation as described in [I-D.draft-bradleylundberg-cfrg-arkg-02] with the identifier `ARKG-P256MUL-ECDH`, `KEM` as defined above, and `BL` with elliptic curve arithmetic as described in [I-D.draft-bradleylundberg-cfrg-arkg-02] Section 3.1, but with multiplicative instead of additive blinding. +- `EC`: The NIST curve `secp256r1` (P-256) [SEC2]. - `ECDH`: ECKA-DH with curve `EC` The holder MUST generate `sk_device` as an `ECDH` private key in the secure cryptographic device. -### HDK-ECSDSA-P256 +## HDK-ECSDSA-P256 This instantiation uses EC-SDSA (see [Using EC-SDSA signatures for proof of possession](#using-ec-sdsa-signatures-for-proof-of-possession)). - `ID`: `"HDK-ECSDSA-P256-v1"` - `Nr`: 48 - `Ns`: 32 -- `expand`: `expand_message_xmd` from [[RFC9380]] with: - - `H`: SHA-256 [[FIPS180-4]] +- `expand`: `expand_message_xmd` from [RFC9380] with: + - `H`: SHA-256 [FIPS180-4] - `b_in_bytes`: 32 - `s_in_bytes`: 64 -- `ARKG`: ARKG instantiation as described in [[draft-bradleylundberg-cfrg-arkg]] with the identifier `ARKG-P256ADD-ECDH`, `KEM` as defined above, and `BL` with elliptic curve arithmetic as described in [[draft-bradleylundberg-cfrg-arkg]] Section 3.1. -- `EC`: The NIST curve `secp256r1` (P-256) [[SEC2]]. +- `ARKG`: ARKG instantiation as described in [I-D.draft-bradleylundberg-cfrg-arkg-02] with the identifier `ARKG-P256ADD-ECDH`, `KEM` as defined above, and `BL` with elliptic curve arithmetic as described in [I-D.draft-bradleylundberg-cfrg-arkg-02] Section 3.1. +- `EC`: The NIST curve `secp256r1` (P-256) [SEC2]. - `DSA`: EC-SDSA-opt (the optimised EC-SDSA) with curve `EC`. The holder MUST generate `sk_device` as a `DSA` private key in the secure cryptographic device. -## Application considerations +# Application considerations -### Secure cryptographic device +## Secure cryptographic device The HDK algorithm assumes that the holder controls a secure cryptographic device that protects the device key pair `(pk_device, sk_device)`. The device key is under sole control of the holder. -In the context of [[EU2024-1183]], this device is typically called a Wallet Secure Cryptographic Device (WSCD), running a personalised Wallet Secure Cryptographic Application (WSCA) that exposes a Secure Cryptographic Interface (SCI) to a Wallet Instance (WI) running on a User Device (UD). The WSCD is certified to protect access to the device private key with high attack potential resistance to achieve high level of assurance authentication as per [[EU2015-1502]]. This typically means that the key is associated with a strong possession factor and with a rate-limited Personal Identification Number (PIN) check as a knowledge factor, and the verification of both factors actively involve the WSCD. +In the context of [EU2024-1183], this device is typically called a Wallet Secure Cryptographic Device (WSCD), running a personalised Wallet Secure Cryptographic Application (WSCA) that exposes a Secure Cryptographic Interface (SCI) to a Wallet Instance (WI) running on a User Device (UD). The WSCD is certified to protect access to the device private key with high attack potential resistance to achieve high level of assurance authentication as per [EU2015-1502]. This typically means that the key is associated with a strong possession factor and with a rate-limited Personal Identification Number (PIN) check as a knowledge factor, and the verification of both factors actively involve the WSCD. The HDK algorithm can support any of the following WSCD architectures: @@ -405,9 +524,9 @@ The HDK algorithm can support any of the following WSCD architectures: 4. Remote HSM, for example: - Cryptographic module certified against EN 419221-5:2018 with a local client application acting as WSCA, remotely controlled for example using: - PIV card as possession factor and PIN verification using a HSM-backed Device-Enhanced Augmented PAKE (an approach proposed by Sweden) - - Android/iOS security platform or standalone device, applying asymmetric cryptography to enable detection of remote HSM corruption as described in [[SCAL3]] + - Android/iOS security platform or standalone device, applying asymmetric cryptography to enable detection of remote HSM corruption as described in [SCAL3] -In all cases, the WSCD may implement a Cryptographic Service Provider [[TR03181]] to reduce the scope for Common Criteria certification of the WSCA. +In all cases, the WSCD may implement a Cryptographic Service Provider [TR03181] to reduce the scope for Common Criteria certification of the WSCA. The solution proposal discussed herein works in all four WSCD architectures that support the required cryptographic primitives within the WSCD: @@ -424,23 +543,23 @@ If the user enters the PIN in the WI instead of on the WSCD directly, the WI MUS The rate-limiting of the PIN check MUST be managed within the WSCD or on securely managed SCI infrastructure. In particular, the rate-limiting MUST NOT be managed solely in local WI software since it is aassumed that attackers could modify this without detection. -### Trust evidence +## Trust evidence -Some issuers could require evidence from a solution provider of the security of the holder’s cryptographic device. This evidence is in the context of [[EU2024-1183]] divided into initial “Wallet Trust Evidence” and related “Issuer Trust Evidence”. Each is a protected document that contains a trust evidence public key associated with a private key that is protected in the secure cryptographic device. In HDK, these public keys are specified as follows. +Some issuers could require evidence from a solution provider of the security of the holder’s cryptographic device. This evidence is in the context of [EU2024-1183] divided into initial “Wallet Trust Evidence” and related “Issuer Trust Evidence”. Each is a protected document that contains a trust evidence public key associated with a private key that is protected in the secure cryptographic device. In HDK, these public keys are specified as follows. -#### Wallet Trust Evidence +### Wallet Trust Evidence The Wallet Trust Evidence public key is the root HDK public key. To achieve reader unlinkability, the wallet SHOULD limit access to a trusted person identification document provider only. To prevent association across identities, the solution provider MUST before issuing Wallet Trust Evidence ensure that the root HDK public key is associated with a newly generated device key pair. For example, the solution provider could rely on freshness of a key attestation and ensure that each device public key is attested only once. -#### Issuer Trust Evidence +### Issuer Trust Evidence The Issuer Trust Evidence public key can be any non-root HDK public key. The solution provider MUST verify that the wallet knows the associated private key before issuing Issuer Trust Evidence. The solution provider MUST ensure that `sk_device` is under sole control of the solution instance holder. To achieve reader unlinkability, the solution instance MUST limit access of Issuer Trust Evidence to a single issuer. Subsequent issuers within the same HDK tree do not need to receive any Issuer Trust Evidence, since they can derive equally secure keys by applying ARKG to presented keys attested by trusted (other) issuers. -### Applying HDK in OpenID for Verifiable Credential Issuance +## Applying HDK in OpenID for Verifiable Credential Issuance -In [[draft-OpenID4VCI]], the following terminology applies: +In [draft-OpenID4VCI], the following terminology applies: | OpenID4VCI | HDK | | ----------------- | ----------------- | @@ -453,153 +572,22 @@ HDK enables solution instances and issuers cooperatively to establish the crypto For asynchronous batch issuance, HDK proposes an update to the OpenID4VCI endpoints. This proposal is under discussion in [openid/OpenID4VCI#359](https://github.com/openid/OpenID4VCI/issues/359). In the update, the solution instance shares an ARKG public seed with the issuer, and the issuer shares a key handle for each attestation, generated using: -``` +~~~ ARKG-Derive-Public-Key(key_generation_public_key, "") -``` +~~~ -## Security considerations +# Security considerations -### Confidentiality of key handles +## Confidentiality of key handles The key handles MUST be considered confidential, since they provide knowledge about the blinding factors. Compromise of this knowledge could introduce undesired linkability. In HDK, both the holder and the issuer know the key handle during issuance. In an alternative to HDK, the holder independently generates blinded key pairs and proofs of association, providing the issuer with zero knowledge about the blinding factors. However, this moves the problem: the proofs of association would now need to be considered confidential. -## References - -### Normative references - -
- -
[draft-bradleylundberg-cfrg-arkg]
- -[draft-bradleylundberg-cfrg-arkg]: #draft-bradleylundberg-cfrg-arkg - -Lundberg, E., and J. Bradley, “The Asynchronous Remote Key Generation (ARKG) algorithm”, [draft-bradleylundberg-cfrg-arkg-latest](https://yubico.github.io/arkg-rfc/draft-bradleylundberg-cfrg-arkg.html), 24 May 2024. - -
[FIPS180-4]
- -[FIPS180-4]: #FIPS180-4 - -National Institute of Standards and Technology (NIST), “Secure Hash Standard (SHS)”, [FIPS 180-4](https://csrc.nist.gov/pubs/fips/180-4/upd1/final), DOI 10.6028/NIST.FIPS.180-4, June 2012. - -
[ISO18013-5]
- -[ISO18013-5]: #ISO18013-5 - -ISO/IEC, “Personal identification — ISO-compliant driving licence – Part 5: Mobile driving licence (mDL) application”, [ISO/IEC 18013-5:2021](https://www.iso.org/standard/69084.html), September 2019. - -
[RFC2119]
- -[RFC2119]: #RFC2119 - -Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, [RFC 2119](https://www.rfc-editor.org/info/rfc2119), DOI 10.17487/RFC2119, March 1997. - -
[RFC7800]
- -[RFC7800]: #RFC7800 - -Jones, M., Bradley, J., and H. Tschofenig, “Proof-of-Possession Key Semantics for JSON Web Tokens (JWTs)”, [RFC 7800](https://www.rfc-editor.org/info/rfc7800), DOI 10.17487/RFC7800, April 2016. - -
[RFC8017]
- -[RFC8017]: #RFC8017 - -Moriarty, K., Ed., Kaliski, B., Jonsson, J., and A. Rusch, “PKCS #1: RSA Cryptography Specifications Version 2.2”, BCP 14, [RFC 8017](https://www.rfc-editor.org/info/rfc8017), DOI 10.17487/RFC8017, November 2016. - -
[RFC8174]
- -[RFC8174]: #RFC8174 - -Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, [RFC 8174](https://www.rfc-editor.org/info/rfc8174), DOI 10.17487/RFC8174, May 2017. - -
[RFC9380]
- -[RFC9380]: #RFC9380 - -Faz-Hernandez, A., Scott, S., Sullivan, N., Wahby, R. S., and C. A. Wood, “Hashing to Elliptic Curves”, [RFC 9380](https://www.rfc-editor.org/info/rfc9380), DOI 10.17487/RFC9380, August 2023. - -
[SEC2]
- -[SEC2]: #SEC2 - -Certicom Research, “SEC 2: Recommended Elliptic Curve Domain Parameters”, [Version 2.0](https://www.secg.org/sec2-v2.pdf), January 2010. - -
[TR03111]
- -[TR03111]: #TR03111 - -Federal Office for Information Security (BSI), “Elliptic Curve Cryptography”, [BSI TR-03111 Version 2.10](https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/Technische-Richtlinien/TR-nach-Thema-sortiert/tr03111/tr-03111.html), June 2018. - -
- -### Informative references - -
- -
[BIP32]
- -[BIP32]: #BIP32 - -Wuille, P., “Hierarchical Deterministic Wallets”, [BIP32 version 2020-11-04](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), February 2012. - -
[draft-ietf-oauth-selective-disclosure-jwt]
- -[draft-ietf-oauth-selective-disclosure-jwt]: #draft-ietf-oauth-selective-disclosure-jwt - -Fett, D., Yasuda, K., and B. Campbell, “Selective Disclosure for JWTs (SD-JWT)”, [draft-ietf-oauth-selective-disclosure-jwt-08](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-08.html), 4 March 2024. - -
[draft-irtf-cfrg-signature-key-blinding]
- -[draft-irtf-cfrg-signature-key-blinding]: #draft-irtf-cfrg-signature-key-blinding - -Denis, F., Eaton, E., Lepoint, T., and C.A. Wood, “Key Blinding for Signature Schemes”, [draft-irtf-cfrg-signature-key-blinding-06](https://www.ietf.org/archive/id/draft-irtf-cfrg-signature-key-blinding-06.html#name-key-blinding), 1 April 2024. - -
[draft-OpenID4VCI]
- -[draft-OpenID4VCI]: #draft-OpenID4VCI - -Lodderstedt, T., Yasuda, K., and T. Looker, “OpenID for Verifiable Credential Issuance”, [draft 13](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html), 8 February 2024. - -
[draft-OpenID4VP]
- -[draft-OpenID4VP]: #draft-OpenID4VP - -Terbu, O., Lodderstedt, T., Yasuda, K., and T. Looker, “OpenID for Verifiable Presentations”, [draft 20](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html), 29 November 2023. - -
[EU2015-1502]
- -[EU2015-1502]: #EU2015-1502 - -European Commission, “Commission Implementing Regulation (EU) 2015/1502 of 8 September 2015 on setting out minimum technical specifications and procedures for assurance levels for electronic identification means”, [(EU) 2015/1502](https://eur-lex.europa.eu/legal-content/TXT/?uri=CELEX%3A32015R1502), September 2015. - -
[EU2024-1183]
- -[EU2024-1183]: #EU2024-1183 - -The European Parliament and the Council of the European Union, “Amending Regulation (EU) No 910/2014 as regards establishing the European Digital Identity Framework”, [(EU) 2024/1183](https://data.europa.eu/eli/reg/2024/1183/oj), April 2024. - -
[ePrint2021-963]
- -[ePrint2021-963]: #ePrint2021-963 - -Eaton, E., Stebila, D., and R. Stracovsky, “Post-Quantum Key-Blinding for Authentication in Anonymity Networks”, [Cryptology ePrint Archive, Paper 2021/963](https://eprint.iacr.org/2021/963), July 2021. - -
[SCAL3]
- -[SCAL3]: #SCAL3 - -Cleverbase ID B.V., [“SCAL3: Verify that systems operate under your sole control”](https://github.com/cleverbase/scal3) version de8c5ae, March 2024. - -
[TR03181]
- -[TR03181]: #TR03181 - -Federal Office for Information Security (BSI), “Cryptographic Service Provider 2 (CSP2)”, [BSI TR-03181 Version 0.94](https://www.bsi.bund.de/EN/Themen/Unternehmen-und-Organisationen/Standards-und-Zertifizierung/Technische-Richtlinien/TR-nach-Thema-sortiert/tr03181/TR-03181_node.html), April 2023. - -
+--- back -## Acknowledgements +# Acknowledgements +{:numbered="false"} This design is based on ideas introduced to the EU Digital Identity domain by Peter Lee Altmann. diff --git a/feedback.md b/feedback.md index dfc88a0..0f81341 100644 --- a/feedback.md +++ b/feedback.md @@ -8,7 +8,7 @@ ## Context -For a general introduction, see [Hierarchical Deterministic Keys for the European Digital Identity Wallet](README.md). In the current document, the authors develop and share structured feedback on one part of the Wallet Toolbox: the [Architecture and Reference Framework](https://eu-digital-identity-wallet.github.io/eudi-doc-architecture-and-reference-framework/latest/arf/) (ARF). The purpose of this feedback is to enable implementation of [Hierarchical Deterministc Keys](keys.md) (HDKs). +For a general introduction, see [Hierarchical Deterministic Keys for the European Digital Identity Wallet](README.md). In the current document, the authors develop and share structured feedback on one part of the Wallet Toolbox: the [Architecture and Reference Framework](https://eu-digital-identity-wallet.github.io/eudi-doc-architecture-and-reference-framework/latest/arf/) (ARF). The purpose of this feedback is to enable implementation of [Hierarchical Deterministc Keys](draft-dijkhuis-cfrg-hierarchical-deterministic-keys.md) (HDKs). By enabling Hierarchical Deterministic Keys, we aim for interoperability with a concrete and desirable cryptographic architecture in the context of person identification data and some (qualified) electronic attestations of attributes. We do not suggest to mandate the application of this cryptographic architecture for all digital identity documents. Instead, we aim to address two risks to the ARF and subsequently the implementing acts: the risk of accidentally disabling desirable technical solutions, and the risk of accidentally requiring undesirable technical solutions.