From 1181a209dd9c77de0b282214b93603e9b2067197 Mon Sep 17 00:00:00 2001 From: Rein Krul Date: Tue, 17 Dec 2024 12:06:39 +0100 Subject: [PATCH 01/36] RFC023: X509Credential --- rfc/rfc023-x509credential.md | 174 +++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 rfc/rfc023-x509credential.md diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md new file mode 100644 index 0000000..61347f7 --- /dev/null +++ b/rfc/rfc023-x509credential.md @@ -0,0 +1,174 @@ +# RFC023: X509Credential + +| | | +|:--------------------------|:--------------| +| Nuts foundation | R.G. Krul | +| Request for Comments: 023 | Zorg bij jou | +| | R. Groen | +| | Zorg bij jou | +| | December 2024 | + +## Abstract + +This RFC specifies the requirements and validation process for the `X509Credential`, a W3C Verifiable Credential (VC) +type issued by a `did:x509` DID. The `X509Credential` ensures strong alignment with the properties of the associated +X.509 certificate and defines mechanisms to validate the credential and verify its association with a `did:x509` DID. + +## Status of this document + +This document is a proposal for discussion and implementation. Feedback is welcome to improve the interoperability +and robustness of the specification. + +## Introduction + +The `X509Credential` is a W3C Verifiable Credential type designed for use cases where trust anchors are based on X.509 +certificates. It leverages the `did:x509` method, as specified in +the [Trust Over IP DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/). +By aligning credential subject validation with the fields of the associated `did:x509` DID and enforcing +certificate revocation checks, the `X509Credential` ensures integrity and adherence to the PKI trust model. + +Its intended use is to bridge the gap in ecosystems where issuers don't support issuance of Verifiable Credentials yet, +but do issue X.509 certificates containing relevant information about the credential subject. + +## Definitions + +- **X509Credential**: A Verifiable Credential whose issuer is a `did:x509` DID and whose structure adheres to the + requirements in this document. +- **did:x509**: A Decentralized Identifier (DID) method specified by the Trust Over IP Foundation, where the DID is + derived from an X.509 certificate. +- **Issuer Certificate**: The X.509 certificate associated with the `did:x509` DID that issued the credential. +- **Credential Subject**: The entity described by the credential. +- **Revocation Check**: The process of verifying the revocation status of the issuer certificate using mechanisms like + OCSP or CRL. + +## Credential Structure + +An `X509Credential` must conform to the general structure of a W3C Verifiable Credential and conform to the following +rules: + +- The credential MUST be in JWT format. +- `type`: MUST include `VerifiableCredential` and `X509Credential`. +- `issuer`: MUST be a valid `did:x509` identifier. +- `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies. + +The credential subject can be identified by any DID method (e.g. `did:web`) accepted by the credential verifier. + +### Example `X509Credential` + +Below is an example of an `X509Credential` issued by a `did:x509` DID. The credential subject is identified by a +`did:web`. +The first snippet is the JWT header, and the second snippet is the credential payload. + +(TODO: check this example) + +```json +{ + "alg": "PS256", + "typ": "JWT", + "x5c": [ + "", + "", + "" + ], + "x5t": "", + "kid": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123#1" +} +``` + +(TODO: Add right JSON-LD context) +Payload: + +```json +{ + "vc": { + "@context": [ + "https://www.w3.org/2018/credentials/v1" + ], + "type": [ + "VerifiableCredential", + "X509Credential" + ], + "issuer": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123", + "issuanceDate": "2024-12-01T00:00:00Z", + "credentialSubject": { + "id": "did:web:example.com", + "subject:O": "Library The Bookworm", + "subject:L": "Bookland", + "san:otherName": "123" + } + } +} +``` + +## Validation + +To validate an `X509Credential`, the following steps MUST be performed: + +- Verify that the credential is in JWT format. +- Verify that the issuer's DID is a `did:x509` DID. +- Resolve the `did:x509` DID document according to the did:x509 specification and check the certificate chain for + revocation. +- Validate that the `credentialSubject` fields match the policies in the `did:x509` DID. + +### 1. Verify Credential Structure + +Ensure that the credential: + +- Includes the `X509Credential` type. +- Contains a valid `did:x509` issuer. +- Includes a `credentialSubject` whose fields match the `did:x509` DID Document. + +### 2. Validate the Issuer Certificate + +The certificate associated with the `did:x509` issuer MUST be validated as follows: + +- **Certificate Chain Validation**: The certificate must have a valid trust chain to a known root CA. +- **Revocation Check**: Verify the revocation status of the certificate using OCSP or CRL. + +Failure to validate the issuer certificate invalidates the credential. + +### 3. Validate the Credential Subject + +The `credentialSubject` MUST be verified against the `did:x509` DID Document. Specifically: + +- Every field in the `credentialSubject` MUST be present in the `did:x509` DID Document. +- Fields not present in the `did:x509` DID Document invalidate the credential. + +### 4. Verify the Proof + +The cryptographic proof of the credential MUST be verified using the public key associated with the `did:x509` DID. +This involves: + +- Resolving the public key from the DID Document. +- Verifying the signature on the credential's `proof`. + +### 5. Check Credential Expiry + +If the `issuanceDate` or any other relevant date constraints (e.g., `expirationDate`) are present, they MUST be +validated to ensure the credential is within its valid timeframe. + +## Security Considerations + +TODO: Trust, which ca-fingerprint to use, ... + +### Certificate Revocation + +The revocation status of the issuer's certificate is a critical component of `X509Credential` validation. Implementers +MUST use reliable revocation checking mechanisms (e.g., OCSP or CRL) and handle failures (e.g., network issues) +appropriately to avoid false-positive validations. + +### Field Alignment + +Restricting the `credentialSubject` fields to those present in the `did:x509` DID Document ensures alignment with the +X.509 certificate, reducing the risk of unauthorized data inclusion. + +### Proof Verification + +The cryptographic proof verification ensures that the credential has not been tampered with and was issued by the +entity controlling the `did:x509` DID. + +## References + +- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) +- [DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) +- [X.509 Certificate Revocation (OCSP/CRL)](https://datatracker.ietf.org/doc/html/rfc5280) From 2574caf61152d1f4b8e3e781ccc8290117a35aca Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 17 Dec 2024 19:04:19 +0100 Subject: [PATCH 02/36] Add detailed explanation of x509 certificates in RFC Expand the RFC with an in-depth introduction to x509 certificates, their structure, and their application in the Nuts network. Include details on the `did:x509` DID method and its attributes, usage of x509 for signing JWEs, and expanded specification of the Subject Other Name attribute. --- rfc/rfc023-x509credential.md | 144 +++++++++++++++++++++++++++++++++-- 1 file changed, 139 insertions(+), 5 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 61347f7..bf886f9 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -10,20 +10,45 @@ ## Abstract +Trust is a key element in the Nuts network. This RFC describes how x509 certificates can be used to source trust from +outside the Nuts network. The x509 certification process has been around for a long time and is widely used in the +internet. This RFC describes how x509 certificates can be used in the Nuts network to establish trust between parties by +being able to link the x509 certificate to a Nuts identity by as a Verifiable Credential that is issued by the holder of +the x509 identity. + This RFC specifies the requirements and validation process for the `X509Credential`, a W3C Verifiable Credential (VC) -type issued by a `did:x509` DID. The `X509Credential` ensures strong alignment with the properties of the associated -X.509 certificate and defines mechanisms to validate the credential and verify its association with a `did:x509` DID. +type issued by the holder of a x509 certificate, represented by a `did:x509` DID. The `X509Credential` ensures strong +alignment with the properties of the associated X.509 certificate and defines mechanisms to validate the credential and +verify its association with a `did:x509` DID. ## Status of this document -This document is a proposal for discussion and implementation. Feedback is welcome to improve the interoperability -and robustness of the specification. +This document is currently in draft. Feedback is welcome to improve the interoperability and robustness of the +specification. + +### Copyright Notice + +![](../.gitbook/assets/license.png) ## Introduction +The Nuts network is a network of trust. The trust is established by the use of Verifiable Credentials. These credentials +are issued by a trusted party and can be used to establish trust between parties. The Nuts network is a decentralised +network and the trust is established between parties that are not necessarily known to each other. The trust is +established by the use of Verifiable Credentials that are issued by trusted sources. Members of the Nuts network can +then trust their peers by verifying the Verifiable Credentials that are presented to them. + +At this time of writing, there are not many sources of trust available that act as trusted source of identity AND that +are capable of providing such trust in the form of Verifiable Credentials. Even tough work is being done in this area. +Most trusted sources in The Netherlands make use of systems like the x509 certificates to establish trust. This RFC +describes how x509 certificates can be used to establish trust in the Nuts network by bridging the gap between the x509 +certificates and the Nuts network. This is done by issuing a Verifiable Credential that is based on the x509 certificate +that makes use of the did:x509 method. + The `X509Credential` is a W3C Verifiable Credential type designed for use cases where trust anchors are based on X.509 certificates. It leverages the `did:x509` method, as specified in the [Trust Over IP DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/). + By aligning credential subject validation with the fields of the associated `did:x509` DID and enforcing certificate revocation checks, the `X509Credential` ensures integrity and adherence to the PKI trust model. @@ -41,7 +66,112 @@ but do issue X.509 certificates containing relevant information about the creden - **Revocation Check**: The process of verifying the revocation status of the issuer certificate using mechanisms like OCSP or CRL. -## Credential Structure +## Used standards and technologies + +This RFC builds on the following standards and technologies: + +* [X.509 Certificate Standard](https://datatracker.ietf.org/doc/html/rfc5280) +* [JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.6) +* [did:x509 method specification](https://trustoverip.github.io/tswg-did-x509-method-specification/), with modifications +* W3C Verifiable Credentials Data Model + +### x509 certificates, a brief introduction + +The structure of an x509 certificate is defined by the X.509 standard. An x509 certificate contains information about +the holder and is signed by a Certificate Authority (CA). The CA is a trusted party that is capable of verifying the +identity of the holder of the certificate. The CA signs the certificate with its own private key. The holder of the +certificate can then use the public key of the CA to verify the signature of the certificate. This way the holder of the +certificate can prove that the certificate is valid and that the information in the certificate is correct. + +The verifier of a x509 certificate can then trust the information in the certificate by verifying the signature of the +certificate chain of the certificate. The verifier can then trust the information in the certificate by trusting the CA +that signed the certificate. + +The chain of certificates can be viewed as a hierarchy, where the root certificate is the certificate is trusted, and +signing is delegated to intermediate certificates. The root certificate is the certificate that is trusted by the +holder. The holder maintains a list of trusted CAs that the holder trusts. The holder can then +verify the signature of the certificate chain by verifying the signature of the CA that signed the intermediate +certificate and the intermediate certificates that lead to the signing certificate. + +
+┌────────────────────┐
+│        CA          │
+└─────────┬──────────┘
+          │           
+┌─────────▼──────────┐
+│    Intermediate    │
+└─────────┬──────────┘
+          │           
+┌─────────▼──────────┐
+│    Intermediate    │
+└─────────┬──────────┘
+          │           
+┌─────────▼──────────┐
+│Signing Certificate │
+└────────────────────┘
+
+ +### Using x509 for signing JWEs + +The JWE is a standard that is used to sign and encrypt JSON objects. Thus standard allows for the signing and encryption +of JSON objects with certificates part of the a certificate chain. This allows for the signing of JSON objects with the +private key of the certificate and the verification of the signature with the public key of the certificate, and the +verification of the certificate chain with the public key of the CA. This is done by using the following headers fields: + +* x5c, the certificate chain as a list of base64 encoded certificates in the DER format, with the signing certificate + first and the root certificate last. +* x5t, the thumbprint of the signing certificate. +* x5t#S256, the thumbprint of the signing certificate as a SHA256 hash. + +### The `did:x509` DID Method + +The `did:x509` DID method is a method that can be used to create a Decentralized Identifier (DID) based on an x509 +certificate chain. This is done by creating a DID that is based on the root CA of the certificate chain. The did:x509 +method is used to specify specific attributes of the signing certificate to specify the holder of the signing +certificate. By doing this, a did:x509 DID can be used to identify the holder of the signing certificate by specifica +attributes that are assigned to the signing certificate. So, for example following did:x509: + +``` +did:x509:0:sha256:WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk::subject:C:US:ST:California:O:My%20Organisation +``` + +ties down the holder of the signing certificate by, first having a digitally signed certificate by the root CA with the +thumbprint `WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk` and then having the following attributes in the certificate: + +* Subjects: + * C: US + * ST: California + * O: My Organisation + +The did:x509 defines various attribute types that can be used as attributes, such as: + +* Subject + * C: Country + * CN: Common Name + * L: Locality + * ST: State + * O: Organisation + * OU: Organisation Unit + * STREET: Street Address +* Subject Other Name (san) + * email + * dns + * uri +* Extended Key Usage (eku) + * Any OID +* A Free-to-Use CA For Code Signing (fulcio-issuer) + * Any issuer hostname + +### Expanding the x509 specification + +This RFC extends the Subject Other Name (san) attribute with the following attribute: + +* otherName: A free-form attribute that can be used to specify any attribute that is not covered by the other + attributes. + +The otherName attribute can be used to specify extra attributes in a x509 certificate. This attribute is added to the specification of this RFC to cater for the use case where the san:otherName attribute is used in the x509 certificate and plays a role in the identification of the holder of the certificate. + +## The X509Credential Structure An `X509Credential` must conform to the general structure of a W3C Verifiable Credential and conform to the following rules: @@ -172,3 +302,7 @@ entity controlling the `did:x509` DID. - [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) - [DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) - [X.509 Certificate Revocation (OCSP/CRL)](https://datatracker.ietf.org/doc/html/rfc5280) + +## PKI overheid & UZI certificates + +## The use of x509 Verifiable Credential in the Nuts network From 12859aa336bcfb794ead7162147fabc60dc642b2 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Thu, 19 Dec 2024 15:43:03 +0100 Subject: [PATCH 03/36] Update RFC023 to extend x509 specification and clarify usage Extend the x509 specification with additional SAN attributes and updated formatting details. Provide structured guidance on UZI certificates and their integration into the Dutch healthcare ecosystem. Elaborate on the use of x509 Verifiable Credentials within the Nuts network to establish trust. --- rfc/rfc023-x509credential.md | 112 +++++++++++++++++++++++++++++++---- 1 file changed, 102 insertions(+), 10 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index bf886f9..7b82c05 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -93,7 +93,7 @@ holder. The holder maintains a list of trusted CAs that the holder trusts. The h verify the signature of the certificate chain by verifying the signature of the CA that signed the intermediate certificate and the intermediate certificates that lead to the signing certificate. -
+```asciidoc
 ┌────────────────────┐
 │        CA          │
 └─────────┬──────────┘
@@ -109,7 +109,7 @@ certificate and the intermediate certificates that lead to the signing certifica
 ┌─────────▼──────────┐
 │Signing Certificate │
 └────────────────────┘
-
+``` ### Using x509 for signing JWEs @@ -162,12 +162,13 @@ The did:x509 defines various attribute types that can be used as attributes, suc * A Free-to-Use CA For Code Signing (fulcio-issuer) * Any issuer hostname -### Expanding the x509 specification +### Extending the x509 specification This RFC extends the Subject Other Name (san) attribute with the following attribute: -* otherName: A free-form attribute that can be used to specify any attribute that is not covered by the other - attributes. +* Subject Other Name (san) + * otherName: A free-form attribute that can be used to specify any attribute that is not covered by the other + attributes. The otherName attribute can be used to specify extra attributes in a x509 certificate. This attribute is added to the specification of this RFC to cater for the use case where the san:otherName attribute is used in the x509 certificate and plays a role in the identification of the holder of the certificate. @@ -179,7 +180,8 @@ rules: - The credential MUST be in JWT format. - `type`: MUST include `VerifiableCredential` and `X509Credential`. - `issuer`: MUST be a valid `did:x509` identifier. -- `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies. +- `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies with the format < + policy_type>:, for example `subject:O` or `san:otherName`. The credential subject can be identified by any DID method (e.g. `did:web`) accepted by the credential verifier. @@ -196,9 +198,9 @@ The first snippet is the JWT header, and the second snippet is the credential pa "alg": "PS256", "typ": "JWT", "x5c": [ - "", - "", - "" + "", + "", + "" ], "x5t": "", "kid": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123#1" @@ -236,7 +238,9 @@ To validate an `X509Credential`, the following steps MUST be performed: - Verify that the credential is in JWT format. - Verify that the issuer's DID is a `did:x509` DID. -- Resolve the `did:x509` DID document according to the did:x509 specification and check the certificate chain for +- Resolve the `did:x509` DID document according to + the [did:x509 specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) and check the + certificate chain for revocation. - Validate that the `credentialSubject` fields match the policies in the `did:x509` DID. @@ -305,4 +309,92 @@ entity controlling the `did:x509` DID. ## PKI overheid & UZI certificates +The Dutch government has a Public Key Infrastructure (PKI) that is used to establish trust between parties. The PKI +framework is currently in place and makes use of PKI Overheid Certificates issued by the root CAs of the Dutch +government. In healthcare a specific instance of PKI overheid certificates are issued: the UZI certificates. These +certificates are used to establish trust between parties in the healthcare sector. The UZI certificates are issued by +the UZI register, which is a trusted party that is capable of verifying the identity of the holder of the certificate. +The UZI register signs the certificate with its own private key. The holder of the certificate can then use the public +key of the UZI register to verify the signature of the certificate. This way the holder of the certificate can prove +that the certificate is valid and that the information in the certificate is correct. The UZI certificates are issued +to: + +* Individuals that work in healthcare, such as doctors, nurses, etc. They hold this certificate on a UZI card. +* Organisations that work in healthcare, such as hospitals, pharmacies, etc. They hold this certificate as server + certificates. + +#### UZI certificate structure for organisations + +The UZI certificate is used to identify the holder of the certificate. The UZI certificate contains information about +the holder of the certificate. This information is used to identify the holder of the certificate. The UZI certificate +contains the following information (of intrest): + +* The `subject.CN` The full FQN. +* The `subject:O` the name of the holder of the certificate. +* The `subject.serialNumber ` The URI number +* The `subject.C` The subject country +* The `subject.ST` The subject state +* The `subject.L` The subject locality (city) +* The `subject.commonName` the full FQN. +* The `san:dNSName` the DNS name of the holder of the certificate. +* The `san:otherName` a string containing `------`, + where: + * `` is the OID of the CA that issued the certificate, `2.16.528.1.1007.99.2110` for CIBG. + * `` is the version number of the certificate. + * `` is the UZI number of the holder of the certificate, same as `subject.serialNumber`. + * `` is the type of the holder of the certificate, always `S`. + * `` is the subscriber URA of the holder of the certificate. + * `` is the role of the holder of the certificate, always "0.00" + * `` is the AGB code of the holder of the certificate. + ## The use of x509 Verifiable Credential in the Nuts network + +The focus on trust in the NUTS network for organizations lies primarily on the URA number identified as the +`` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch +healthcare ecosystem . The holder of the certificate can use the UZI certificate in combination with the private +key to proof the ownership of the URA number. The diagram below shows how the UZI certificate can be used to transfer +the trust from the CIBG register into the NUTS ecosystem using the `did:x509` method and the `X509Credential` Verifiable +Credential. + +```asciidoc + ┌─────────┐ ┌──────────┐ + │ Keypair ┼───────┤ did:x509 │ + └────┬────┘ └────┬─────┘ + │ │ + │ │ +┌───────────┐ ┌───────┴───────┐ │ +│ ROOT CA │ │ UZI │ ┌───────┴────────┐ ┌────┐ +└─────┬─────┘ │ Certificate │ │ X509Credential ┼───────────────► VP │ + │ └───────────────┘ └───────┬──┬─────┘ └─┬──┘ + │ │ │ │ ┌────────────┐ │ ┌────────────┐ +┌─────┴─────┐ Request ┌───────┴───────┐ │ │ │ │ │ │ │ +│ Source of ◄────────────┼ Holder of ┼─────────┴──┼────► Wallet ┼─────┴─────► Verifier │ +│ Trust ┌────────────► Trust │ Issue│ │ │ Present │ │ +└───────────┘ Issue └───────────────┘ │ └──────┬─────┘ └────────────┘ + │ │ + │ │ + ┌───────┴─┐ ┌────┴────┐ + │ did:web ├────┤ Keypair │ + └─────────┘ └─────────┘ +``` + +The main steps in the diagram are: + +* The holder generates a keypair and requests a UZI certificate from the UZI register with a Certificate Signing + Request (CSR). +* The UZI register issues the certificate to the holder of the UZI certificate and signs the request with the + intermediate CA, linked to the root CA. +* The holder of the UZI creates a `X509Credential` Verifiable Credential: + * The holder set the `did:x509` of the UZI certificate as issuer to the `X509Credential` Verifiable Credential. + * The holder includes the complete chain in the `X509Credential` Verifiable Credential. + * The holder issues the `X509Credential` Verifiable Credential to its own NUTS identity as `did:web` . + * The holder signs the `X509Credential` Verifiable Credential with the keypair associated with the UZI certificate. +* The holder places the `X509Credential` Verifiable Credential in the wallet. +* The holder presents the `X509Credential` Verifiable Credential to the verifier, and signs the presentation with the + keypair associated with the `did:web` of the holder. +* The verifier now can verify that: + * The `X509Credential` Verifiable Credential is issued by a `did:x509` issued by the the UZI register. + * The `X509Credential` Verifiable Credential is signed by the holder of the UZI certificate. + * The attributes of the `X509Credential` Verifiable Credential match the attributes of the UZI certificate. + * The URA number of the holder of the UZI certificate is present in the `X509Credential` Verifiable Credential. + From 6af5704c055035e61cd4ec8eddd4f887038d28b1 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Thu, 19 Dec 2024 15:45:09 +0100 Subject: [PATCH 04/36] Update section title to specify UZI server certificate usage Clarified the section title to specifically refer to the UZI server certificate instead of the more generic x509 Verifiable Credential. This improves specificity and aligns the document with its intended focus. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 7b82c05..d8ffc3b 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -347,7 +347,7 @@ contains the following information (of intrest): * `` is the role of the holder of the certificate, always "0.00" * `` is the AGB code of the holder of the certificate. -## The use of x509 Verifiable Credential in the Nuts network +## The use of UZI server certificate in the Nuts network The focus on trust in the NUTS network for organizations lies primarily on the URA number identified as the `` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch From ccdbf88a97ae69fd9b350747bae9275a141bb096 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Mon, 6 Jan 2025 19:42:18 +0100 Subject: [PATCH 05/36] Refine X509Credential validation and add UZI mapping guide. Clarified certificate chain validation rules and revocation checks. Added a section to map UZI certificates to X509Credentials, including field mappings and hierarchical structure of the UZI certificate register. This improves compatibility and compliance with the `did:x509` specification. --- rfc/rfc023-x509credential.md | 41 +++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index d8ffc3b..133e9e1 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -240,8 +240,7 @@ To validate an `X509Credential`, the following steps MUST be performed: - Verify that the issuer's DID is a `did:x509` DID. - Resolve the `did:x509` DID document according to the [did:x509 specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) and check the - certificate chain for - revocation. + certificate chain for revocation. - Validate that the `credentialSubject` fields match the policies in the `did:x509` DID. ### 1. Verify Credential Structure @@ -256,7 +255,8 @@ Ensure that the credential: The certificate associated with the `did:x509` issuer MUST be validated as follows: -- **Certificate Chain Validation**: The certificate must have a valid trust chain to a known root CA. +- **Certificate Chain Validation**: The certificate must have a valid trust chain. The use case determines if the CA is + trusted. - **Revocation Check**: Verify the revocation status of the certificate using OCSP or CRL. Failure to validate the issuer certificate invalidates the credential. @@ -347,6 +347,41 @@ contains the following information (of intrest): * `` is the role of the holder of the certificate, always "0.00" * `` is the AGB code of the holder of the certificate. +## Mapping UZI certificate to X509Credential + +### The ROOT Ca + +The `did:x509` specification dictates that the fingerprint of the Root CA is part of the did:x509. For mapping an UZI +certificate to an X509Credential the ROOT CA MUST match one of the certificates in the UZI register hierarchy. + +```asciidoc + ┌────────────────────────────────────┐ + │ Staat der Nederlanden Root CA - G3 │ + └────────────────┬───────────────────┘ + │ +┌────────────────────────▼───────────────────────────┐ +│ Staat der Nederlanden Organisatie Services CA - G3 │ +└────────────────────────┬───────────────────────────┘ + │ + ┌────────────────────▼───────────────────────┐ + │ UZI-register Medewerker niet op naam CA G3 │ + └────────────────────────────────────────────┘ +``` + +### Field mapping +The following fields are commonly used for mapping UZI cetificates to X509Credentials +* The `subject:O` the name of the holder of the certificate. +* The `subject.L` The subject locality (city) +* The `san:otherName` a string containing `------`, + where: + * `` is the OID of the CA that issued the certificate, `2.16.528.1.1007.99.2110` for CIBG. + * `` is the version number of the certificate. + * `` is the UZI number of the holder of the certificate, same as `subject.serialNumber`. + * `` is the type of the holder of the certificate, always `S`. + * `` is the subscriber URA of the holder of the certificate. + * `` is the role of the holder of the certificate, always "0.00" + * `` is the AGB code of the holder of the certificate. + ## The use of UZI server certificate in the Nuts network The focus on trust in the NUTS network for organizations lies primarily on the URA number identified as the From 95a2f5167446d27b84f580f1e2811ed93250801c Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 7 Jan 2025 11:35:58 +0100 Subject: [PATCH 06/36] Add detailed security considerations for x509credential Expanded the Security Considerations section to include checks against the root CA structure for specific use cases. Highlighted the importance of matching the ROOT CA chain, such as for UZI certificates. This ensures clearer guidance on trust and certificate validation. --- rfc/rfc023-x509credential.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 133e9e1..1c0656c 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -283,7 +283,10 @@ validated to ensure the credential is within its valid timeframe. ## Security Considerations -TODO: Trust, which ca-fingerprint to use, ... +The following security considerations are to be considered: + +- The Root CA of the did:x509 needs to be checked against the root CA structure of the use case. For instance, in case + of UZI certificates the ROOT CA must match the associated root CA chain. ### Certificate Revocation From 9bdff453e87763faa52edcc0ab2661fca331596c Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 7 Jan 2025 11:36:23 +0100 Subject: [PATCH 07/36] Add example UZI certificate mapping in RFC023 documentation Updated the RFC023 to enhance clarity around mapping UZI certificates to X509Credentials. Added details on the ROOT G3 CA hierarchy, refined field mapping descriptions, and adjusted sections to improve readability and consistency. --- rfc/rfc023-x509credential.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 1c0656c..38b3482 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -310,7 +310,9 @@ entity controlling the `did:x509` DID. - [DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) - [X.509 Certificate Revocation (OCSP/CRL)](https://datatracker.ietf.org/doc/html/rfc5280) -## PKI overheid & UZI certificates +# An application of the RFC023: UZI server certificates + +## PKI overheid & UZI server certificates The Dutch government has a Public Key Infrastructure (PKI) that is used to establish trust between parties. The PKI framework is currently in place and makes use of PKI Overheid Certificates issued by the root CAs of the Dutch @@ -352,10 +354,13 @@ contains the following information (of intrest): ## Mapping UZI certificate to X509Credential -### The ROOT Ca +The mapping of certificates to x509 is depending + +### The ROOT G3 The `did:x509` specification dictates that the fingerprint of the Root CA is part of the did:x509. For mapping an UZI -certificate to an X509Credential the ROOT CA MUST match one of the certificates in the UZI register hierarchy. +certificate to an X509Credential the ROOT CA MUST match one of the certificates in the UZI ROOT CA register hierarchy. +For G3 this is: ```asciidoc ┌────────────────────────────────────┐ @@ -371,9 +376,10 @@ certificate to an X509Credential the ROOT CA MUST match one of the certificates └────────────────────────────────────────────┘ ``` -### Field mapping -The following fields are commonly used for mapping UZI cetificates to X509Credentials -* The `subject:O` the name of the holder of the certificate. +### Field mapping of the UZI credential + +The following fields are commonly used for mapping UZI certificates to X509Credentials +* The `subject:O` the name of the holder of the certificate. Maps to `subject.O` in the X509Credential. * The `subject.L` The subject locality (city) * The `san:otherName` a string containing `------`, where: @@ -385,7 +391,7 @@ The following fields are commonly used for mapping UZI cetificates to X509Creden * `` is the role of the holder of the certificate, always "0.00" * `` is the AGB code of the holder of the certificate. -## The use of UZI server certificate in the Nuts network +## The use of UZI server certificate in the Nuts network or identifying organizations The focus on trust in the NUTS network for organizations lies primarily on the URA number identified as the `` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch From 6c17ad65019fab6c27e35d7f21ae08b7432f2ef3 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 7 Jan 2025 11:41:22 +0100 Subject: [PATCH 08/36] Refactor credentialSubject structure in RFC023. Updated the `credentialSubject` definition to use a structured mapping for each type as separate maps, enhancing clarity and consistency in representation. Provided an example to illustrate the new format. --- rfc/rfc023-x509credential.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 38b3482..9988523 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -180,8 +180,17 @@ rules: - The credential MUST be in JWT format. - `type`: MUST include `VerifiableCredential` and `X509Credential`. - `issuer`: MUST be a valid `did:x509` identifier. -- `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies with the format < - policy_type>:, for example `subject:O` or `san:otherName`. +- `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies with the fields mapped by each type as a separate map. An example: +``` +{ + "subject": { + "O" : "My Organisation" + }, + "san" : { + "email" : "info@example.com," + } +} +``` The credential subject can be identified by any DID method (e.g. `did:web`) accepted by the credential verifier. From 6f72f41c8f62fd4ddf59ead7544c9370021cf7e7 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 7 Jan 2025 11:46:10 +0100 Subject: [PATCH 09/36] Normalize attribute notation in RFC023 document. Updated attribute references to use consistent dot notation (e.g., `san.otherName` and `subject.O`) instead of colon-based notation. This improves standardization and readability across the document. --- rfc/rfc023-x509credential.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 9988523..6f5a491 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -170,7 +170,7 @@ This RFC extends the Subject Other Name (san) attribute with the following attri * otherName: A free-form attribute that can be used to specify any attribute that is not covered by the other attributes. -The otherName attribute can be used to specify extra attributes in a x509 certificate. This attribute is added to the specification of this RFC to cater for the use case where the san:otherName attribute is used in the x509 certificate and plays a role in the identification of the holder of the certificate. +The otherName attribute can be used to specify extra attributes in a x509 certificate. This attribute is added to the specification of this RFC to cater for the use case where the san.otherName attribute is used in the x509 certificate and plays a role in the identification of the holder of the certificate. ## The X509Credential Structure @@ -344,14 +344,14 @@ the holder of the certificate. This information is used to identify the holder o contains the following information (of intrest): * The `subject.CN` The full FQN. -* The `subject:O` the name of the holder of the certificate. +* The `subject.O` the name of the holder of the certificate. * The `subject.serialNumber ` The URI number * The `subject.C` The subject country * The `subject.ST` The subject state * The `subject.L` The subject locality (city) * The `subject.commonName` the full FQN. -* The `san:dNSName` the DNS name of the holder of the certificate. -* The `san:otherName` a string containing `------`, +* The `san.dNSName` the DNS name of the holder of the certificate. +* The `san.otherName` a string containing `------`, where: * `` is the OID of the CA that issued the certificate, `2.16.528.1.1007.99.2110` for CIBG. * `` is the version number of the certificate. @@ -388,9 +388,9 @@ For G3 this is: ### Field mapping of the UZI credential The following fields are commonly used for mapping UZI certificates to X509Credentials -* The `subject:O` the name of the holder of the certificate. Maps to `subject.O` in the X509Credential. +* The `subject.O` the name of the holder of the certificate. Maps to `subject.O` in the X509Credential. * The `subject.L` The subject locality (city) -* The `san:otherName` a string containing `------`, +* The `san.otherName` a string containing `------`, where: * `` is the OID of the CA that issued the certificate, `2.16.528.1.1007.99.2110` for CIBG. * `` is the version number of the certificate. From b59d760dc88382ef9ea9bfee3dc64a32f8efa1dd Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Tue, 7 Jan 2025 13:20:16 +0100 Subject: [PATCH 10/36] Update rfc/rfc023-x509credential.md Co-authored-by: reinkrul --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 6f5a491..37549fc 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -187,7 +187,7 @@ rules: "O" : "My Organisation" }, "san" : { - "email" : "info@example.com," + "email" : "info@example.com" } } ``` From 755055d339b0237572dd2d08d8f6df431fc82bdc Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:19:02 +0100 Subject: [PATCH 11/36] Update rfc/rfc023-x509credential.md Co-authored-by: reinkrul --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 37549fc..569ddac 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -162,7 +162,7 @@ The did:x509 defines various attribute types that can be used as attributes, suc * A Free-to-Use CA For Code Signing (fulcio-issuer) * Any issuer hostname -### Extending the x509 specification +### Extending the `did:x509` specification This RFC extends the Subject Other Name (san) attribute with the following attribute: From 925757484f307d16f460481183d9bb26221843d8 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:19:14 +0100 Subject: [PATCH 12/36] Rename `X509Credential` to `NutsX509Credential` in RFC023. Updated all mentions and descriptions of `X509Credential` to `NutsX509Credential` for consistency and alignment with the naming convention. This clarifies the credential's association with the Nuts ecosystem and its specific context. --- rfc/rfc023-x509credential.md | 64 ++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 569ddac..d995fe8 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -1,4 +1,4 @@ -# RFC023: X509Credential +# RFC023: NutsX509Credential | | | |:--------------------------|:--------------| @@ -16,8 +16,8 @@ internet. This RFC describes how x509 certificates can be used in the Nuts netwo being able to link the x509 certificate to a Nuts identity by as a Verifiable Credential that is issued by the holder of the x509 identity. -This RFC specifies the requirements and validation process for the `X509Credential`, a W3C Verifiable Credential (VC) -type issued by the holder of a x509 certificate, represented by a `did:x509` DID. The `X509Credential` ensures strong +This RFC specifies the requirements and validation process for the `NutsX509Credential`, a W3C Verifiable Credential (VC) +type issued by the holder of a x509 certificate, represented by a `did:x509` DID. The `NutsX509Credential` ensures strong alignment with the properties of the associated X.509 certificate and defines mechanisms to validate the credential and verify its association with a `did:x509` DID. @@ -45,19 +45,19 @@ describes how x509 certificates can be used to establish trust in the Nuts netwo certificates and the Nuts network. This is done by issuing a Verifiable Credential that is based on the x509 certificate that makes use of the did:x509 method. -The `X509Credential` is a W3C Verifiable Credential type designed for use cases where trust anchors are based on X.509 +The `NutsX509Credential` is a W3C Verifiable Credential type designed for use cases where trust anchors are based on X.509 certificates. It leverages the `did:x509` method, as specified in the [Trust Over IP DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/). By aligning credential subject validation with the fields of the associated `did:x509` DID and enforcing -certificate revocation checks, the `X509Credential` ensures integrity and adherence to the PKI trust model. +certificate revocation checks, the `NutsX509Credential` ensures integrity and adherence to the PKI trust model. Its intended use is to bridge the gap in ecosystems where issuers don't support issuance of Verifiable Credentials yet, but do issue X.509 certificates containing relevant information about the credential subject. ## Definitions -- **X509Credential**: A Verifiable Credential whose issuer is a `did:x509` DID and whose structure adheres to the +- **NutsX509Credential**: A Verifiable Credential whose issuer is a `did:x509` DID and whose structure adheres to the requirements in this document. - **did:x509**: A Decentralized Identifier (DID) method specified by the Trust Over IP Foundation, where the DID is derived from an X.509 certificate. @@ -172,13 +172,13 @@ This RFC extends the Subject Other Name (san) attribute with the following attri The otherName attribute can be used to specify extra attributes in a x509 certificate. This attribute is added to the specification of this RFC to cater for the use case where the san.otherName attribute is used in the x509 certificate and plays a role in the identification of the holder of the certificate. -## The X509Credential Structure +## The NutsX509Credential Structure -An `X509Credential` must conform to the general structure of a W3C Verifiable Credential and conform to the following +An `NutsX509Credential` must conform to the general structure of a W3C Verifiable Credential and conform to the following rules: - The credential MUST be in JWT format. -- `type`: MUST include `VerifiableCredential` and `X509Credential`. +- `type`: MUST include `VerifiableCredential` and `NutsX509Credential`. - `issuer`: MUST be a valid `did:x509` identifier. - `credentialSubject`: MUST only contain fields explicitly present in the `did:x509` DID policies with the fields mapped by each type as a separate map. An example: ``` @@ -194,9 +194,9 @@ rules: The credential subject can be identified by any DID method (e.g. `did:web`) accepted by the credential verifier. -### Example `X509Credential` +### Example `NutsX509Credential` -Below is an example of an `X509Credential` issued by a `did:x509` DID. The credential subject is identified by a +Below is an example of an `NutsX509Credential` issued by a `did:x509` DID. The credential subject is identified by a `did:web`. The first snippet is the JWT header, and the second snippet is the credential payload. @@ -227,7 +227,7 @@ Payload: ], "type": [ "VerifiableCredential", - "X509Credential" + "NutsX509Credential" ], "issuer": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123", "issuanceDate": "2024-12-01T00:00:00Z", @@ -243,7 +243,7 @@ Payload: ## Validation -To validate an `X509Credential`, the following steps MUST be performed: +To validate an `NutsX509Credential`, the following steps MUST be performed: - Verify that the credential is in JWT format. - Verify that the issuer's DID is a `did:x509` DID. @@ -256,7 +256,7 @@ To validate an `X509Credential`, the following steps MUST be performed: Ensure that the credential: -- Includes the `X509Credential` type. +- Includes the `NutsX509Credential` type. - Contains a valid `did:x509` issuer. - Includes a `credentialSubject` whose fields match the `did:x509` DID Document. @@ -299,7 +299,7 @@ The following security considerations are to be considered: ### Certificate Revocation -The revocation status of the issuer's certificate is a critical component of `X509Credential` validation. Implementers +The revocation status of the issuer's certificate is a critical component of `NutsX509Credential` validation. Implementers MUST use reliable revocation checking mechanisms (e.g., OCSP or CRL) and handle failures (e.g., network issues) appropriately to avoid false-positive validations. @@ -361,14 +361,14 @@ contains the following information (of intrest): * `` is the role of the holder of the certificate, always "0.00" * `` is the AGB code of the holder of the certificate. -## Mapping UZI certificate to X509Credential +## Mapping UZI certificate to NutsX509Credential The mapping of certificates to x509 is depending ### The ROOT G3 The `did:x509` specification dictates that the fingerprint of the Root CA is part of the did:x509. For mapping an UZI -certificate to an X509Credential the ROOT CA MUST match one of the certificates in the UZI ROOT CA register hierarchy. +certificate to an NutsX509Credential the ROOT CA MUST match one of the certificates in the UZI ROOT CA register hierarchy. For G3 this is: ```asciidoc @@ -387,8 +387,8 @@ For G3 this is: ### Field mapping of the UZI credential -The following fields are commonly used for mapping UZI certificates to X509Credentials -* The `subject.O` the name of the holder of the certificate. Maps to `subject.O` in the X509Credential. +The following fields are commonly used for mapping UZI certificates to NutsX509Credentials +* The `subject.O` the name of the holder of the certificate. Maps to `subject.O` in the NutsX509Credential. * The `subject.L` The subject locality (city) * The `san.otherName` a string containing `------`, where: @@ -406,7 +406,7 @@ The focus on trust in the NUTS network for organizations lies primarily on the U `` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch healthcare ecosystem . The holder of the certificate can use the UZI certificate in combination with the private key to proof the ownership of the URA number. The diagram below shows how the UZI certificate can be used to transfer -the trust from the CIBG register into the NUTS ecosystem using the `did:x509` method and the `X509Credential` Verifiable +the trust from the CIBG register into the NUTS ecosystem using the `did:x509` method and the `NutsX509Credential` Verifiable Credential. ```asciidoc @@ -417,7 +417,7 @@ Credential. │ │ ┌───────────┐ ┌───────┴───────┐ │ │ ROOT CA │ │ UZI │ ┌───────┴────────┐ ┌────┐ -└─────┬─────┘ │ Certificate │ │ X509Credential ┼───────────────► VP │ +└─────┬─────┘ │ Certificate │ │ NutsX509Credential ┼───────────────► VP │ │ └───────────────┘ └───────┬──┬─────┘ └─┬──┘ │ │ │ │ ┌────────────┐ │ ┌────────────┐ ┌─────┴─────┐ Request ┌───────┴───────┐ │ │ │ │ │ │ │ @@ -437,17 +437,17 @@ The main steps in the diagram are: Request (CSR). * The UZI register issues the certificate to the holder of the UZI certificate and signs the request with the intermediate CA, linked to the root CA. -* The holder of the UZI creates a `X509Credential` Verifiable Credential: - * The holder set the `did:x509` of the UZI certificate as issuer to the `X509Credential` Verifiable Credential. - * The holder includes the complete chain in the `X509Credential` Verifiable Credential. - * The holder issues the `X509Credential` Verifiable Credential to its own NUTS identity as `did:web` . - * The holder signs the `X509Credential` Verifiable Credential with the keypair associated with the UZI certificate. -* The holder places the `X509Credential` Verifiable Credential in the wallet. -* The holder presents the `X509Credential` Verifiable Credential to the verifier, and signs the presentation with the +* The holder of the UZI creates a `NutsX509Credential` Verifiable Credential: + * The holder set the `did:x509` of the UZI certificate as issuer to the `NutsX509Credential` Verifiable Credential. + * The holder includes the complete chain in the `NutsX509Credential` Verifiable Credential. + * The holder issues the `NutsX509Credential` Verifiable Credential to its own NUTS identity as `did:web` . + * The holder signs the `NutsX509Credential` Verifiable Credential with the keypair associated with the UZI certificate. +* The holder places the `NutsX509Credential` Verifiable Credential in the wallet. +* The holder presents the `NutsX509Credential` Verifiable Credential to the verifier, and signs the presentation with the keypair associated with the `did:web` of the holder. * The verifier now can verify that: - * The `X509Credential` Verifiable Credential is issued by a `did:x509` issued by the the UZI register. - * The `X509Credential` Verifiable Credential is signed by the holder of the UZI certificate. - * The attributes of the `X509Credential` Verifiable Credential match the attributes of the UZI certificate. - * The URA number of the holder of the UZI certificate is present in the `X509Credential` Verifiable Credential. + * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509` issued by the the UZI register. + * The `NutsX509Credential` Verifiable Credential is signed by the holder of the UZI certificate. + * The attributes of the `NutsX509Credential` Verifiable Credential match the attributes of the UZI certificate. + * The URA number of the holder of the UZI certificate is present in the `NutsX509Credential` Verifiable Credential. From e8949c7d304bd6ff7d91ca05dd5b95a31783928e Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:21:59 +0100 Subject: [PATCH 13/36] Update terminology from JWE to JWT in RFC document Corrected the section to accurately reference JWT instead of JWE when discussing signing and encrypting JSON objects with x509 certificates. This ensures consistency and correctness in the described standard usage. --- rfc/rfc023-x509credential.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index d995fe8..b7380fa 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -111,10 +111,10 @@ certificate and the intermediate certificates that lead to the signing certifica └────────────────────┘ ``` -### Using x509 for signing JWEs +### Using x509 for signing JWTs -The JWE is a standard that is used to sign and encrypt JSON objects. Thus standard allows for the signing and encryption -of JSON objects with certificates part of the a certificate chain. This allows for the signing of JSON objects with the +The JWT is a standard that is used to sign and encrypt JSON objects. Thus standard allows for the signing and encryption +of JSON objects with certificates part of a certificate chain. This allows for the signing of JSON objects with the private key of the certificate and the verification of the signature with the public key of the certificate, and the verification of the certificate chain with the public key of the CA. This is done by using the following headers fields: From 256b8cab1bbb2f24997caf661e5ee4157ae269d4 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 10:54:53 +0100 Subject: [PATCH 14/36] Update rfc/rfc023-x509credential.md Co-authored-by: reinkrul --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index b7380fa..4aa68cd 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -295,7 +295,7 @@ validated to ensure the credential is within its valid timeframe. The following security considerations are to be considered: - The Root CA of the did:x509 needs to be checked against the root CA structure of the use case. For instance, in case - of UZI certificates the ROOT CA must match the associated root CA chain. + of UZI certificates the `ca-fingerprint` must match the hash of (name of G3 intermediate CA(s) here). ### Certificate Revocation From ff9d72cccdce090736a9b99378bb8c2ebc0c4786 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:22:45 +0100 Subject: [PATCH 15/36] Suggested rewording. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 4aa68cd..977610f 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -118,7 +118,7 @@ of JSON objects with certificates part of a certificate chain. This allows for t private key of the certificate and the verification of the signature with the public key of the certificate, and the verification of the certificate chain with the public key of the CA. This is done by using the following headers fields: -* x5c, the certificate chain as a list of base64 encoded certificates in the DER format, with the signing certificate +* x5c, the ordered certificate chain as a list of base64 encoded certificates in the DER format, with the signing certificate first and the root certificate last. * x5t, the thumbprint of the signing certificate. * x5t#S256, the thumbprint of the signing certificate as a SHA256 hash. From 5ee7c0057cacefa2b024c50e41f0241eca1c7832 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:23:49 +0100 Subject: [PATCH 16/36] Suggested rewording. --- rfc/rfc023-x509credential.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 977610f..b4ad858 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -126,9 +126,9 @@ verification of the certificate chain with the public key of the CA. This is don ### The `did:x509` DID Method The `did:x509` DID method is a method that can be used to create a Decentralized Identifier (DID) based on an x509 -certificate chain. This is done by creating a DID that is based on the root CA of the certificate chain. The did:x509 -method is used to specify specific attributes of the signing certificate to specify the holder of the signing -certificate. By doing this, a did:x509 DID can be used to identify the holder of the signing certificate by specifica +certificate chain. Trust in the DID is anchored by specifying the (hash of) one of the chain's intermediate, or the root CA's certificate. The did:x509 method +is used to specify specific attributes of the signing certificate to specify the holder of the signing +certificate. By doing this, a did:x509 DID can be used to identify the holder of the signing certificate by specificying attributes that are assigned to the signing certificate. So, for example following did:x509: ``` From f535c53f97e2c1041c1269284b8350f3f5faf67a Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:24:10 +0100 Subject: [PATCH 17/36] Suggested rewording --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index b4ad858..e4d22ca 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -135,7 +135,7 @@ attributes that are assigned to the signing certificate. So, for example followi did:x509:0:sha256:WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk::subject:C:US:ST:California:O:My%20Organisation ``` -ties down the holder of the signing certificate by, first having a digitally signed certificate by the root CA with the +ties down the holder of the signing certificate by, first having a digitally signed certificate by the CA with the thumbprint `WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk` and then having the following attributes in the certificate: * Subjects: From 32abc4f626952d80e916be5c9fb5bc2fd57e2f68 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:24:24 +0100 Subject: [PATCH 18/36] Suggested rewording. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index e4d22ca..e35e475 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -138,7 +138,7 @@ did:x509:0:sha256:WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk::subject:C:US:ST:C ties down the holder of the signing certificate by, first having a digitally signed certificate by the CA with the thumbprint `WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk` and then having the following attributes in the certificate: -* Subjects: +* Subject: * C: US * ST: California * O: My Organisation From 75c5b7399b7024321da5e5276b3b6ec6bdb7418a Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Fri, 10 Jan 2025 11:25:06 +0100 Subject: [PATCH 19/36] Suggested rewording. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index e35e475..5666128 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -164,7 +164,7 @@ The did:x509 defines various attribute types that can be used as attributes, suc ### Extending the `did:x509` specification -This RFC extends the Subject Other Name (san) attribute with the following attribute: +This RFC extends the Subject Other Name (san) policy with the following attribute: * Subject Other Name (san) * otherName: A free-form attribute that can be used to specify any attribute that is not covered by the other From 0138bc047d6d46ab23a648e43a945c39783653af Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:50:04 +0100 Subject: [PATCH 20/36] Add verification of trust anchor in x509 credential checks Ensure that the DID specifies an accepted trust anchor (CA certificate) for the `ca-fingerprint` during credential validation. This strengthens the validation process by confirming the trustworthiness of the issuing CA. --- rfc/rfc023-x509credential.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 5666128..f7799f4 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -247,6 +247,7 @@ To validate an `NutsX509Credential`, the following steps MUST be performed: - Verify that the credential is in JWT format. - Verify that the issuer's DID is a `did:x509` DID. +- Verify that the DID specifies an accepted trust anchor (CA certificate) for ca-fingerprint. - Resolve the `did:x509` DID document according to the [did:x509 specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) and check the certificate chain for revocation. From 873f0f8330061518b4b3f046dfab9152a053e438 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:50:32 +0100 Subject: [PATCH 21/36] Update x509credential example to reflect new issuer details Revised the credential example with updated issuer information, including organization, location, and SAN fields. This ensures the example aligns with current specification changes and provides clearer, more accurate data. --- rfc/rfc023-x509credential.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index f7799f4..22e9eaa 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -212,7 +212,7 @@ The first snippet is the JWT header, and the second snippet is the credential pa "" ], "x5t": "", - "kid": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123#1" + "kid": "did:x509:0:sha256:WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk::subject:O:OLVG%20Oost::subject:L:Amsterdam::san:otherName:23419943234#1" } ``` @@ -229,13 +229,13 @@ Payload: "VerifiableCredential", "NutsX509Credential" ], - "issuer": "did:x509:0:sha256:::subject:O:Library%20The%20Bookworm::subject:L:Bookland::san:otherName:123", + "issuer": "did:x509:0:sha256:WE4P5dd8DnLHSkyHaIjhp4udlkF9LqoKwCvu9gl38jk::subject:O:OLVG%20Oost::subject:L:Amsterdam::san:otherName:23419943234", "issuanceDate": "2024-12-01T00:00:00Z", "credentialSubject": { "id": "did:web:example.com", - "subject:O": "Library The Bookworm", - "subject:L": "Bookland", - "san:otherName": "123" + "subject:O": "OLVG Oost", + "subject:L": "Amsterdam", + "san:otherName": "23419943234" } } } From 945271ce5b4650d3691434eebe9a5ca992d68cda Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:52:34 +0100 Subject: [PATCH 22/36] Simplify revocation check to use only CRL. Updated the certificate revocation check to rely solely on CRL instead of both OCSP and CRL. This change aims to streamline the revocation verification process and ensure consistency in validation methods. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 22e9eaa..3d3a096 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -267,7 +267,7 @@ The certificate associated with the `did:x509` issuer MUST be validated as follo - **Certificate Chain Validation**: The certificate must have a valid trust chain. The use case determines if the CA is trusted. -- **Revocation Check**: Verify the revocation status of the certificate using OCSP or CRL. +- **Revocation Check**: Verify the revocation status of the certificate using CRL. Failure to validate the issuer certificate invalidates the credential. From 5075e6e5777a3e6f53883d640289e84f594c5a13 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:55:24 +0100 Subject: [PATCH 23/36] Update subject.commonName to subject.CN in RFC023 Replaced `subject.commonName` with `subject.CN` for clarity and consistency with standard naming conventions. Removed the `san.dNSName` entry as it was redundant or no longer required. --- rfc/rfc023-x509credential.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 3d3a096..789fd9a 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -350,8 +350,7 @@ contains the following information (of intrest): * The `subject.C` The subject country * The `subject.ST` The subject state * The `subject.L` The subject locality (city) -* The `subject.commonName` the full FQN. -* The `san.dNSName` the DNS name of the holder of the certificate. +* The `subject.CN` the full FQN. * The `san.otherName` a string containing `------`, where: * `` is the OID of the CA that issued the certificate, `2.16.528.1.1007.99.2110` for CIBG. From 4609a6dc1b6e108848bfa66320ed351c3b2e995f Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:58:11 +0100 Subject: [PATCH 24/36] Fix alignment issues in x509credential RFC diagram Corrected the alignment of diagram elements in the x509credential RFC for better visual clarity. These adjustments ensure the diagram is more readable and properly formatted. --- rfc/rfc023-x509credential.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 789fd9a..7ee49a9 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -416,9 +416,9 @@ Credential. │ │ │ │ ┌───────────┐ ┌───────┴───────┐ │ -│ ROOT CA │ │ UZI │ ┌───────┴────────┐ ┌────┐ -└─────┬─────┘ │ Certificate │ │ NutsX509Credential ┼───────────────► VP │ - │ └───────────────┘ └───────┬──┬─────┘ └─┬──┘ +│ ROOT CA │ │ UZI │ ┌───────┴────────────┐ ┌────┐ +└─────┬─────┘ │ Certificate │ │ NutsX509Credential ┼───────────► VP │ + │ └───────────────┘ └───────┬──┬─────────┘ └─┬──┘ │ │ │ │ ┌────────────┐ │ ┌────────────┐ ┌─────┴─────┐ Request ┌───────┴───────┐ │ │ │ │ │ │ │ │ Source of ◄────────────┼ Holder of ┼─────────┴──┼────► Wallet ┼─────┴─────► Verifier │ From 6fa366a3360982da1a713e176d01c29e1ee6f67b Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:58:28 +0100 Subject: [PATCH 25/36] Refine wording on x509 credential issuer description. Updated the RFC to clarify that the `NutsX509Credential` is issued by the subject of an x509 certificate, rather than its holder. This improves the precision of the specification and ensures alignment with the intended semantics. --- rfc/rfc023-x509credential.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 7ee49a9..33fd4d7 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -16,10 +16,10 @@ internet. This RFC describes how x509 certificates can be used in the Nuts netwo being able to link the x509 certificate to a Nuts identity by as a Verifiable Credential that is issued by the holder of the x509 identity. -This RFC specifies the requirements and validation process for the `NutsX509Credential`, a W3C Verifiable Credential (VC) -type issued by the holder of a x509 certificate, represented by a `did:x509` DID. The `NutsX509Credential` ensures strong -alignment with the properties of the associated X.509 certificate and defines mechanisms to validate the credential and -verify its association with a `did:x509` DID. +This RFC specifies the requirements and validation process for the `NutsX509Credential`, a W3C Verifiable Credential ( +VC) type issued by the subject of a x509 certificate, represented by a `did:x509` DID. The `NutsX509Credential` ensures +strong alignment with the properties of the associated X.509 certificate and defines mechanisms to validate the +credential and verify its association with a `did:x509` DID. ## Status of this document From 0608c3d1a4610fe4d91eb9758d697321c7a480bd Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 11:59:21 +0100 Subject: [PATCH 26/36] Update wording from CIBG to UZI in RFC023 description Corrected the reference from "CIBG register" to "UZI register" to ensure accuracy in the explanation of trust transfer within the NUTS ecosystem. This aligns the documentation with the proper terminology. --- rfc/rfc023-x509credential.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 33fd4d7..7ef9fff 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -406,7 +406,7 @@ The focus on trust in the NUTS network for organizations lies primarily on the U `` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch healthcare ecosystem . The holder of the certificate can use the UZI certificate in combination with the private key to proof the ownership of the URA number. The diagram below shows how the UZI certificate can be used to transfer -the trust from the CIBG register into the NUTS ecosystem using the `did:x509` method and the `NutsX509Credential` Verifiable +the trust from the UZI register into the NUTS ecosystem using the `did:x509` method and the `NutsX509Credential` Verifiable Credential. ```asciidoc From 9b339b3ea4f6faa4cbeb07ea4afc2720aff70f09 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 12:06:50 +0100 Subject: [PATCH 27/36] Revise X.509 certificate introduction and add trust hierarchy. Updated the X.509 certificate section to provide a clearer introduction, highlight key features, and explain the trust hierarchy more effectively. Added relevance to the Nuts framework by showcasing its integration with X.509 for decentralized identity. --- rfc/rfc023-x509credential.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 7ef9fff..04164da 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -77,39 +77,35 @@ This RFC builds on the following standards and technologies: ### x509 certificates, a brief introduction -The structure of an x509 certificate is defined by the X.509 standard. An x509 certificate contains information about -the holder and is signed by a Certificate Authority (CA). The CA is a trusted party that is capable of verifying the -identity of the holder of the certificate. The CA signs the certificate with its own private key. The holder of the -certificate can then use the public key of the CA to verify the signature of the certificate. This way the holder of the -certificate can prove that the certificate is valid and that the information in the certificate is correct. - -The verifier of a x509 certificate can then trust the information in the certificate by verifying the signature of the -certificate chain of the certificate. The verifier can then trust the information in the certificate by trusting the CA -that signed the certificate. - -The chain of certificates can be viewed as a hierarchy, where the root certificate is the certificate is trusted, and -signing is delegated to intermediate certificates. The root certificate is the certificate that is trusted by the -holder. The holder maintains a list of trusted CAs that the holder trusts. The holder can then -verify the signature of the certificate chain by verifying the signature of the CA that signed the intermediate -certificate and the intermediate certificates that lead to the signing certificate. +An **X.509 certificate** is a digital certificate that follows the X.509 Public Key Infrastructure (PKI) standard. It is widely used for secure communication over the internet, such as HTTPS, email encryption, and digital signatures. +### Key Features of X.509 Certificates: +- **Structure**: It contains information about the certificate owner (e.g., organization, common name, public key) and the issuing Certificate Authority (CA). The certificate is signed by the CA's private key to ensure authenticity. +- **Trust Hierarchy**: + - Trust is anchored in a **Certificate Authority (CA)**, which is a trusted third party. + - Certificates can form a chain of trust, starting from a **root certificate** (trusted CA) to **intermediate certificates**, down to the **end-user/client certificates** (specific use-case certificates). + +Example of the trust chain hierarchy: + ```asciidoc ┌────────────────────┐ -│ CA │ +│ Root CA │ └─────────┬──────────┘ │ ┌─────────▼──────────┐ -│ Intermediate │ +│ Intermediate CA │ └─────────┬──────────┘ │ ┌─────────▼──────────┐ -│ Intermediate │ +│ Intermediate CA │ └─────────┬──────────┘ │ ┌─────────▼──────────┐ │Signing Certificate │ └────────────────────┘ ``` +### Nuts and X.509: +The Nuts framework extends X.509 certificates into its decentralized identity (DID) ecosystem using the `did:x509` DID method. This method facilitates linking an X.509 certificate to a verifiable credential (`NutsX509Credential`), providing trust while bridging traditional PKI with decentralized trust models. This is especially relevant in systems reliant on existing X.509 implementations, such as healthcare or government frameworks. ### Using x509 for signing JWTs From e60beb7aca4248f1024c7ec6b8954628297ea414 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 12:09:58 +0100 Subject: [PATCH 28/36] Simplify documentation by removing x5t description. The x5t field is deprecated and no longer supported, so its description has been removed for clarity. The document now accurately reflects current usage standards. --- rfc/rfc023-x509credential.md | 1 - 1 file changed, 1 deletion(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 04164da..72ceed8 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -116,7 +116,6 @@ verification of the certificate chain with the public key of the CA. This is don * x5c, the ordered certificate chain as a list of base64 encoded certificates in the DER format, with the signing certificate first and the root certificate last. -* x5t, the thumbprint of the signing certificate. * x5t#S256, the thumbprint of the signing certificate as a SHA256 hash. ### The `did:x509` DID Method From 64f27d0fce5526d78749656a731acb830133e601 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 12:10:10 +0100 Subject: [PATCH 29/36] Simplify and update the introduction for clarity. Revised the introduction to focus on the purpose and functionality of the `did:x509` method, ensuring clarity and alignment with interoperability goals. Removed redundant explanations and outdated statements to enhance readability and precision. --- rfc/rfc023-x509credential.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 72ceed8..4ff4186 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -32,18 +32,7 @@ specification. ## Introduction -The Nuts network is a network of trust. The trust is established by the use of Verifiable Credentials. These credentials -are issued by a trusted party and can be used to establish trust between parties. The Nuts network is a decentralised -network and the trust is established between parties that are not necessarily known to each other. The trust is -established by the use of Verifiable Credentials that are issued by trusted sources. Members of the Nuts network can -then trust their peers by verifying the Verifiable Credentials that are presented to them. - -At this time of writing, there are not many sources of trust available that act as trusted source of identity AND that -are capable of providing such trust in the form of Verifiable Credentials. Even tough work is being done in this area. -Most trusted sources in The Netherlands make use of systems like the x509 certificates to establish trust. This RFC -describes how x509 certificates can be used to establish trust in the Nuts network by bridging the gap between the x509 -certificates and the Nuts network. This is done by issuing a Verifiable Credential that is based on the x509 certificate -that makes use of the did:x509 method. +TThe [did:x509](https://trustoverip.github.io/tswg-did-x509-method-specification/) method aims to achieve interoperability between existing X.509 solutions and Decentralized Identifiers (DIDs) to support operational models in which a full transition to DIDs is not achievable or desired yet. It supports X.509-only verifiers as well as DID-based verifiers supporting this DID method. The `NutsX509Credential` is a W3C Verifiable Credential type designed for use cases where trust anchors are based on X.509 certificates. It leverages the `did:x509` method, as specified in @@ -52,8 +41,6 @@ the [Trust Over IP DID:X509 Method Specification](https://trustoverip.github.io/ By aligning credential subject validation with the fields of the associated `did:x509` DID and enforcing certificate revocation checks, the `NutsX509Credential` ensures integrity and adherence to the PKI trust model. -Its intended use is to bridge the gap in ecosystems where issuers don't support issuance of Verifiable Credentials yet, -but do issue X.509 certificates containing relevant information about the credential subject. ## Definitions From fb5532326b74910d6adb031c6d2bc13d89a48114 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 12:11:54 +0100 Subject: [PATCH 30/36] "Clarify signing and verification details for NutsX509Credential" Refined the explanation of credential signing to specify the use of private keys associated with the UZI certificate and improved clarity on verification steps. These updates ensure better accuracy and comprehensibility of the credential lifecycle. --- rfc/rfc023-x509credential.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 4ff4186..a65b11e 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -423,12 +423,14 @@ The main steps in the diagram are: * The holder set the `did:x509` of the UZI certificate as issuer to the `NutsX509Credential` Verifiable Credential. * The holder includes the complete chain in the `NutsX509Credential` Verifiable Credential. * The holder issues the `NutsX509Credential` Verifiable Credential to its own NUTS identity as `did:web` . - * The holder signs the `NutsX509Credential` Verifiable Credential with the keypair associated with the UZI certificate. + * The holder signs the `NutsX509Credential` Verifiable Credential with the keypair associated with the UZI + certificate. * The holder places the `NutsX509Credential` Verifiable Credential in the wallet. -* The holder presents the `NutsX509Credential` Verifiable Credential to the verifier, and signs the presentation with the - keypair associated with the `did:web` of the holder. +* The holder presents the `NutsX509Credential` Verifiable Credential to the verifier, and signs the presentation with + the keypair associated with the `did:web` of the holder. * The verifier now can verify that: - * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509` issued by the the UZI register. + * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509`, signed with a private key which is + associated with a certificate issued by the UZI register. * The `NutsX509Credential` Verifiable Credential is signed by the holder of the UZI certificate. * The attributes of the `NutsX509Credential` Verifiable Credential match the attributes of the UZI certificate. * The URA number of the holder of the UZI certificate is present in the `NutsX509Credential` Verifiable Credential. From fa3b45fca0e88606f5f00253201f3b04f8b0402f Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:00:19 +0100 Subject: [PATCH 31/36] Update X509 credential verification steps for clarity Revised the verification process to improve accuracy and alignment with trust anchors. Included a detailed check for the URA number in the Verifiable Credential against the trusted certificate, ensuring stricter validation. --- rfc/rfc023-x509credential.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index a65b11e..05ff5b7 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -429,9 +429,10 @@ The main steps in the diagram are: * The holder presents the `NutsX509Credential` Verifiable Credential to the verifier, and signs the presentation with the keypair associated with the `did:web` of the holder. * The verifier now can verify that: - * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509`, signed with a private key which is - associated with a certificate issued by the UZI register. - * The `NutsX509Credential` Verifiable Credential is signed by the holder of the UZI certificate. - * The attributes of the `NutsX509Credential` Verifiable Credential match the attributes of the UZI certificate. - * The URA number of the holder of the UZI certificate is present in the `NutsX509Credential` Verifiable Credential. + * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509` which trust anchor matches a trusted Root + or Intermediate CA. + * The `NutsX509Credential` Verifiable Credential is signed by the private key of the subject of the UZI certificate. + * The attributes of the `NutsX509Credential` Verifiable Credential match the attributes of the UZI certificate, and + more specific: + * The verifier verifies that the URA number as claimed by the VC is present in the (trusted) certificate. From b59f60e2de2126127f2fb41f14cb764d4c38f97c Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:04:36 +0100 Subject: [PATCH 32/36] Clarify validation steps in X509 credential documentation Reordered and refined the validation process for better clarity and consistency. Removed redundant section duplicating validation instructions and fixed a formatting issue with `ca-fingerprint`. --- rfc/rfc023-x509credential.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 05ff5b7..c54712f 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -225,24 +225,18 @@ Payload: ## Validation +### 1. Verify Credential Structure + To validate an `NutsX509Credential`, the following steps MUST be performed: - Verify that the credential is in JWT format. - Verify that the issuer's DID is a `did:x509` DID. -- Verify that the DID specifies an accepted trust anchor (CA certificate) for ca-fingerprint. +- Verify that the DID specifies an accepted trust anchor (CA certificate) for `ca-fingerprint`. - Resolve the `did:x509` DID document according to the [did:x509 specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) and check the certificate chain for revocation. - Validate that the `credentialSubject` fields match the policies in the `did:x509` DID. -### 1. Verify Credential Structure - -Ensure that the credential: - -- Includes the `NutsX509Credential` type. -- Contains a valid `did:x509` issuer. -- Includes a `credentialSubject` whose fields match the `did:x509` DID Document. - ### 2. Validate the Issuer Certificate The certificate associated with the `did:x509` issuer MUST be validated as follows: From 115c65acbc0afded2d85a910904ba206edcb3588 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:08:56 +0100 Subject: [PATCH 33/36] Clarify X.509 certificate validation requirements. Enhanced details on trust chain validation, including mandatory signature checks and the requirement for a DID-specified trust anchor in the certificate chain. These changes provide clearer guidance on securing credentials. --- rfc/rfc023-x509credential.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index c54712f..ce066bb 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -241,9 +241,12 @@ To validate an `NutsX509Credential`, the following steps MUST be performed: The certificate associated with the `did:x509` issuer MUST be validated as follows: -- **Certificate Chain Validation**: The certificate must have a valid trust chain. The use case determines if the CA is - trusted. +- **Certificate Chain Validation**: The certificate must have a valid trust chain. The chain MUST be complete and all + signatures need to be checked. - **Revocation Check**: Verify the revocation status of the certificate using CRL. +- The DID MUST specify an accepted trust anchor through its `ca-fingerprint` property and the trust anchor MUST be + present in the certificate chain as either the Root CA or on of the Intermediate CAs. What trust anchors are accepted + depends on the use case. Failure to validate the issuer certificate invalidates the credential. From 3a3798812d99a9d7fce04f72539348339234f66d Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:19:13 +0100 Subject: [PATCH 34/36] Expand security considerations in RFC023 Detailed security risks and mitigation steps were added to the document, addressing issues such as broken trust chains, revocation checks, expired certificates, and weak cryptographic practices. This update improves clarity on potential threats and their consequences, enhancing the guidance for secure implementation. --- rfc/rfc023-x509credential.md | 96 ++++++++++++++++++++++++++++-------- 1 file changed, 76 insertions(+), 20 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index ce066bb..5cb06df 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -272,26 +272,82 @@ validated to ensure the credential is within its valid timeframe. ## Security Considerations -The following security considerations are to be considered: - -- The Root CA of the did:x509 needs to be checked against the root CA structure of the use case. For instance, in case - of UZI certificates the `ca-fingerprint` must match the hash of (name of G3 intermediate CA(s) here). - -### Certificate Revocation - -The revocation status of the issuer's certificate is a critical component of `NutsX509Credential` validation. Implementers -MUST use reliable revocation checking mechanisms (e.g., OCSP or CRL) and handle failures (e.g., network issues) -appropriately to avoid false-positive validations. - -### Field Alignment - -Restricting the `credentialSubject` fields to those present in the `did:x509` DID Document ensures alignment with the -X.509 certificate, reducing the risk of unauthorized data inclusion. - -### Proof Verification - -The cryptographic proof verification ensures that the credential has not been tampered with and was issued by the -entity controlling the `did:x509` DID. +The following security considerations need to be addressed: + +### **1. Broken Trust Chain** + +- If the certificate chain is not validated, attackers could present fake certificates signed by an untrusted or rogue + Certificate Authority (CA). +- **Consequences**: + - Users or systems may accept malicious certificates, allowing attackers to impersonate legitimate entities (e.g., + phishing attacks or man-in-the-middle (MitM) attacks). + - Sensitive data (e.g., credentials, financial data) exchanged with fraudulent sites could be intercepted. + +### **2. Revocation Checks Not Performed** + +- If you fail to check the status of certificates for revocation using CRL (Certificate Revocation List), certificates + that have been compromised or expired could still be considered valid. +- **Consequences**: + - Attackers could use stolen or revoked certificates to bypass authentication or encryption. + - Systems may continue to trust certificates issued to malicious actors. + +### **3. Expired Certificates** + +- If credential expiry is ignored, certificates whose validity period has elapsed could still be used and trusted. +- **Consequences**: + - Attackers may exploit outdated certificates to perform replay attacks where previously valid credentials are reused. + - Trust in infrastructure degrades because expired certificates no longer reflect proper certificate holder + responsibility/accountability. + +### **4. Weak Keys or Algorithms** + +- If weak cryptographic algorithms (e.g., MD5, SHA-1) or small key sizes (e.g., <2048-bit RSA) are used, the + certificates or their signatures could be cracked by modern computational power. +- **Consequences**: + - An attacker could forge or spoof certificates. + - Sensitive data could be decrypted easily, exposing confidential information such as passwords, personal data, etc. + +### **5. Improper Credential Subject Validation** + +- If the `credentialSubject` field in frameworks like `NutsX509Credential` is not properly validated, it may allow + fields not aligned with the X.509 certificate to be added or accepted. +- **Consequences**: + - Attackers could inject unauthorized or false data (e.g., incorrect organization name or purpose), tricking verifiers + by impersonating trusted entities. + - Loss of trust in the system due to inconsistencies between certificates and credentials. + +### **6. Forged Proofs or Tampered Credentials** + +- Failure to verify cryptographic proofs tied to certificates could allow credentials or data to be tampered with. +- **Consequences**: + - Credentials could be modified to grant unauthorized access. + - The integrity of systems relying on these credentials could be compromised. + +### **7. Missing Root CA Verification** + +- If the source of trust (Root CA) is not explicitly verified and trusted, attackers could use certificates issued by + unapproved CAs.For instance, in case of UZI certificates the `ca-fingerprint` must match the hash of either the Root + CA or one of the Intermediate CAs as published by the [UZI register](https://www.zorgcsp.nl/ca-certificaten). +- **Consequences**: + - Fake certificates signed by rogue or unvalidated CAs could be accepted as valid. + - Attackers gain the ability to impersonate legitimate entities in scenarios such as encrypted communication or + identity verification. + +### **8. Certificate Misuse** + +- Without proper validation of certificate attributes (e.g., URA number in UZI certificates), certificates may be + misused in unintended contexts. +- **Consequences**: + - Fraud or impersonation using certificates outside their intended scope. + - Misrepresentation of organizations or individuals. + +### **9. Lack of Reliable Revocation Handling** + +- If revocation checks poorly handle network issues or failures (e.g., OCSP response unavailability), it could result in + the acceptance of revoked or invalid certificates. +- **Consequences**: + - Increased risk of improper trust, allowing revoked credentials to function within the system. + - Security-critical applications become susceptible to breaches. ## References From f77b2bb55fcc28c8de97e6e2365aa71720e246f3 Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:43:35 +0100 Subject: [PATCH 35/36] Clarify subject identification and trust establishment process Updated terminology from "holder" to "subject" for accuracy in describing entities linked to UZI certificates. Enhanced diagram explanations and added a detailed step-by-step breakdown of the trust establishment process using X.509 certificates, did:x509, and NutsX509Credential. --- rfc/rfc023-x509credential.md | 131 ++++++++++++++++++++++++++--------- 1 file changed, 98 insertions(+), 33 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index 5cb06df..ede7b8b 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -438,10 +438,10 @@ The following fields are commonly used for mapping UZI certificates to NutsX509C ## The use of UZI server certificate in the Nuts network or identifying organizations The focus on trust in the NUTS network for organizations lies primarily on the URA number identified as the -`` on the UZI certificate. This number is used to identify the holder of the certificate within the Dutch -healthcare ecosystem . The holder of the certificate can use the UZI certificate in combination with the private +`` on the UZI certificate. This number is used to identify the subject of the certificate within the Dutch +healthcare ecosystem . The subject of the certificate can use the UZI certificate in combination with the private key to proof the ownership of the URA number. The diagram below shows how the UZI certificate can be used to transfer -the trust from the UZI register into the NUTS ecosystem using the `did:x509` method and the `NutsX509Credential` Verifiable +the trust from the UZI register acting as "authentieke bron" into the NUTS ecosystem using the `did:x509` method and the `NutsX509Credential` Verifiable Credential. ```asciidoc @@ -451,41 +451,106 @@ Credential. │ │ │ │ ┌───────────┐ ┌───────┴───────┐ │ -│ ROOT CA │ │ UZI │ ┌───────┴────────────┐ ┌────┐ -└─────┬─────┘ │ Certificate │ │ NutsX509Credential ┼───────────► VP │ - │ └───────────────┘ └───────┬──┬─────────┘ └─┬──┘ +│ ROOT CA │ │ UZI │ ┌───────────────────┐ ┌────┐ +└─────┬─────┘ │ Certificate │ │ NutsX509Credential┼────────────► VP │ + │ └───────────────┘ └───────────────────┘ └─┬──┘ │ │ │ │ ┌────────────┐ │ ┌────────────┐ -┌─────┴─────┐ Request ┌───────┴───────┐ │ │ │ │ │ │ │ -│ Source of ◄────────────┼ Holder of ┼─────────┴──┼────► Wallet ┼─────┴─────► Verifier │ -│ Trust ┌────────────► Trust │ Issue│ │ │ Present │ │ -└───────────┘ Issue └───────────────┘ │ └──────┬─────┘ └────────────┘ - │ │ +┌─────┴─────┐ 1.Request ┌───────┴───────┐ │ │ │ │ │ │ │ +│ Authentic ◄────────────┼ Holder of ┼─────────┴──┼────► Wallet ┼─────┴─────► Verifier │ +│ Source of ┌────────────► Trust │ 3.Issue │ │ │ 4.Present │ │ +│ Trust │ 2.Issue └───────────────┘ │ └──────┬─────┘ └────────────┘ +└───────────┘ │ │ │ │ ┌───────┴─┐ ┌────┴────┐ │ did:web ├────┤ Keypair │ └─────────┘ └─────────┘ ``` -The main steps in the diagram are: - -* The holder generates a keypair and requests a UZI certificate from the UZI register with a Certificate Signing - Request (CSR). -* The UZI register issues the certificate to the holder of the UZI certificate and signs the request with the - intermediate CA, linked to the root CA. -* The holder of the UZI creates a `NutsX509Credential` Verifiable Credential: - * The holder set the `did:x509` of the UZI certificate as issuer to the `NutsX509Credential` Verifiable Credential. - * The holder includes the complete chain in the `NutsX509Credential` Verifiable Credential. - * The holder issues the `NutsX509Credential` Verifiable Credential to its own NUTS identity as `did:web` . - * The holder signs the `NutsX509Credential` Verifiable Credential with the keypair associated with the UZI - certificate. -* The holder places the `NutsX509Credential` Verifiable Credential in the wallet. -* The holder presents the `NutsX509Credential` Verifiable Credential to the verifier, and signs the presentation with - the keypair associated with the `did:web` of the holder. -* The verifier now can verify that: - * The `NutsX509Credential` Verifiable Credential is issued by a `did:x509` which trust anchor matches a trusted Root - or Intermediate CA. - * The `NutsX509Credential` Verifiable Credential is signed by the private key of the subject of the UZI certificate. - * The attributes of the `NutsX509Credential` Verifiable Credential match the attributes of the UZI certificate, and - more specific: - * The verifier verifies that the URA number as claimed by the VC is present in the (trusted) certificate. +This diagram represents the process of establishing trust, based on the use of X.509 certificates, the +`NutsX509Credential` and `did:x509` within a trust network. Below is a step-by-step explanation of the diagram: + +### **Key Components** + +1. **Root CA**: + - The starting point for trust. The Root Certificate Authority (CA) is a trusted source that issues and signs + certificates to intermediate or end-user entities. + +2. **UZI Certificate**: + - A specific X.509 certificate issued by the Root CA (or its intermediaries) to establish trust for the holder (e.g., + an organization or an individual). + +3. **Keypair**: + - Generated by the certificate holder, this is the private-public key pair required for signing and authentication + processes. + +4. **did:x509**: + - A Decentralized Identifier (DID) based on an X.509 certificate. It links decentralized systems with the trust of + traditional X.509 certificates. + +5. **NutsX509Credential**: + - A Verifiable Credential (VC), such as a "NutsX509Credential," which is issued by the certificate holder using its + `did:x509` identifier and signed with the corresponding keypair. This credential is stored in the holder's wallet. + +6. **Wallet**: + - A secure digital storage system for holding the NutsX509Credential. It manages credentials and is used for + presenting them to verifiers. + +7. **Verifier**: + - An entity that validates the presented credential and establishes the holder's identity based on its associated + trust components (e.g., did:x509, certificate chain, etc.). + +8. **did:web**: + - Another Decentralized Identifier (DID) the holder may use to represent their identity and interact within the + decentralized trust ecosystem. + +### **Process Steps** + +#### **Step 1: Keypair Generation and Request** + +The **holder** generates a keypair (private and public key) to represent their identity. They submit the +public key as part of a **Certificate Signing Request (CSR)** to the Root CA (or intermediate CA). Within the CSR +terminology, the **holder** is the **subject** of the CSR. + +#### **Step 2: Certificate Issuance** + +The Root CA (or its intermediate CA) verifies the request and issues an **X.509 certificate** (e.g., a UZI certificate) +to the subject. This certificate includes information about the subject (e.g., subject name and organization) and is +signed by the CA. This guarantees the authenticity of the certificate. Note that the **holder** and **subject** are the +same concepts but are named differently between the different terminologies. + +#### **Step 3: NutsX509Credential Issuance** + +The **holder** uses their X.509 certificate to create a **NutsX509Credential or Verifiable Credential**. The process +includes: + +1. Using the certificate's `did:x509` identifier as the credential's **issuer**. +2. Signing this credential with the holder's private key (from the keypair). +3. Storing the credential securely in the **Wallet** for future use. + +#### **Step 4: Credential Presentation** + +When the holder needs to prove their identity to a verifier (e.g., during authentication), they present the * +*NutsX509Credential** from their wallet to the **Verifier**. This process includes: + +1. The presentation of the digital credential as a Verifiable Presentation (VP). +2. Signing the presentation with the holder's private key to ensure it hasn't been tampered with. + +#### **Step 5: Verification** + +The **Verifier** validates the credential and presentation. This includes: + +1. Checking the integrity of the credential and presentation signature. +2. Confirming the certificate chain back to the **Root CA** to ensure the issuer of the X.509 certificate is authentic + and trusted. +3. Validating the use case-specific attributes in the credential (e.g., fields like organization, UZI number, or other + subject information). +4. Ensuring the credential has not been revoked using methods like CRL. + +#### Trust is Established: + +If all checks pass, the Verifier trusts the credential presented by the holder. The credential's trustworthiness is +derived from: +1. The Root CA that anchors trust. +2. The validity of the X.509 certificate and the associated DID (`did:x509`). +3. Alignment of attributes between the X509Credential and the certificate. From 30043aa926f70c191e25fb6a96aeae551bc8f7cd Mon Sep 17 00:00:00 2001 From: Roland Groen Date: Wed, 5 Feb 2025 13:48:25 +0100 Subject: [PATCH 36/36] Update references to Verifiable Credentials Data Model v1.1 Updated links and references to point to the latest version (v1.1) of the Verifiable Credentials Data Model for better accuracy and alignment with current standards. Minor formatting adjustments were also made for consistency. --- rfc/rfc023-x509credential.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/rfc023-x509credential.md b/rfc/rfc023-x509credential.md index ede7b8b..308c1e8 100644 --- a/rfc/rfc023-x509credential.md +++ b/rfc/rfc023-x509credential.md @@ -60,12 +60,12 @@ This RFC builds on the following standards and technologies: * [X.509 Certificate Standard](https://datatracker.ietf.org/doc/html/rfc5280) * [JSON Web Signature (JWS)](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.6) * [did:x509 method specification](https://trustoverip.github.io/tswg-did-x509-method-specification/), with modifications -* W3C Verifiable Credentials Data Model +* [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) ### x509 certificates, a brief introduction An **X.509 certificate** is a digital certificate that follows the X.509 Public Key Infrastructure (PKI) standard. It is widely used for secure communication over the internet, such as HTTPS, email encryption, and digital signatures. -### Key Features of X.509 Certificates: +#### Key Features of X.509 Certificates: - **Structure**: It contains information about the certificate owner (e.g., organization, common name, public key) and the issuing Certificate Authority (CA). The certificate is signed by the CA's private key to ensure authenticity. - **Trust Hierarchy**: - Trust is anchored in a **Certificate Authority (CA)**, which is a trusted third party. @@ -351,7 +351,7 @@ The following security considerations need to be addressed: ## References -- [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) +- [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) - [DID:X509 Method Specification](https://trustoverip.github.io/tswg-did-x509-method-specification/) - [X.509 Certificate Revocation (OCSP/CRL)](https://datatracker.ietf.org/doc/html/rfc5280)