RFC023: X509Credential #283
Conversation
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.
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.
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.
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.
|
Request to change the structure of the attributes:
|
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.
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.
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.
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.
| * x5t, the thumbprint of the signing certificate. | ||
| * x5t#S256, the thumbprint of the signing certificate as a SHA256 hash. |
There was a problem hiding this comment.
I think at least one is required, right (not both)?
| * ST: California | ||
| * O: My Organisation | ||
|
|
||
| The did:x509 defines various attribute types that can be used as attributes, such as: |
There was a problem hiding this comment.
if this is the complete list, no need to specify "such as", since this is all there is
| "subject:O": "Library The Bookworm", | ||
| "subject:L": "Bookland", | ||
| "san:otherName": "123" |
rfc/rfc023-x509credential.md
Outdated
|
|
||
| ## Validation | ||
|
|
||
| To validate an `X509Credential`, the following steps MUST be performed: |
There was a problem hiding this comment.
We should add a step that the DID specifies an accepted trust anchor (CA certificate) for ca-fingerprint, referring to the Security Consideration
| - Contains a valid `did:x509` issuer. | ||
| - Includes a `credentialSubject` whose fields match the `did:x509` DID Document. | ||
|
|
||
| ### 2. Validate the Issuer Certificate |
There was a problem hiding this comment.
these steps don't match the list above
|
|
||
| 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 |
There was a problem hiding this comment.
I think we should separate these concerns:
- The DID should contain a valid certificate chain (it's complete and signatures have been checked)
- The DID should specify an accepted trust anchor through its
ca-fingerprintproperty (refer to Security Consideration)
Since the first is performed in the Nuts node, the second is configuration/use case dependant.
|
|
||
| - **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. |
There was a problem hiding this comment.
Nuts node doesn't support OCSP
There was a problem hiding this comment.
Also already described in step 3 of the read operation in the did:x509 spec: https://trustoverip.github.io/tswg-did-x509-method-specification/#read
| 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. |
There was a problem hiding this comment.
| 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). |
|
|
||
| ## Security Considerations | ||
|
|
||
| The following security considerations are to be considered: |
There was a problem hiding this comment.
also state which catastrophic failure might occur when you don't do this properly
| ### 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. |
There was a problem hiding this comment.
"otherwise, an attacker could ..."
| * 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. |
There was a problem hiding this comment.
is this the casing? ugly...
Co-authored-by: reinkrul <[email protected]>
|
|
||
| ### 3. Validate the Credential Subject | ||
|
|
||
| The `credentialSubject` MUST be verified against the `did:x509` DID Document. Specifically: |
There was a problem hiding this comment.
It can't be verified against the DID Document since the DID Document only has key material.
Must every credentialSubject assertion be present in the did:x509 issuer string
or
Must every credentialSubject assertion be present in the x509 certificate?
The did:x509 spec requires ...uses the subject policy to express criteria which a leaf certificate’s subject must fulfill. Which does not mean the certificate may contain more subject entries which could be useful to represent in the credentialSubject
There was a problem hiding this comment.
ps: current nuts-node validation requires a 1-on-1 mapping and credentialSubject assertions not present in a policy results in an error.
rfc/rfc023-x509credential.md
Outdated
| 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) |
There was a problem hiding this comment.
We might need to rename the credential to NutsX509Credential. Not sure why, but the online json-ld playground rejects names starting with a X.
rfc/rfc023-x509credential.md
Outdated
| 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 |
There was a problem hiding this comment.
Not sure of a holder is a thing in the certificate world, I would say the subject
| 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 |
There was a problem hiding this comment.
It feels like this RFC is trying to explain the concepts behind trust. And while doing that introducing terminology like "sources of trust" and "trusted source of identity". I would either skip that and assume the reader already knows this or leverage an existing model like Trust over IP and/or the ARF.
| ### 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 |
There was a problem hiding this comment.
I don't think the holder is a thing in x509 world. You also need the private key of the certificate and that is usually the subject.
|
|
||
| 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 |
There was a problem hiding this comment.
The root but also the intermediates are trusted, and not by the holder but by the verifier.
Do we really want to explain how x509 certs work here? Can we perhaps refer to a wiki page or something?
rfc/rfc023-x509credential.md
Outdated
| `<Abonnee-nr>` 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 |
There was a problem hiding this comment.
CIBG and UZI register are both mentioned here as issuer, I would stick with the latter.
| the trust from the CIBG register into the NUTS ecosystem using the `did:x509` method and the `X509Credential` Verifiable | ||
| Credential. | ||
|
|
||
| ```asciidoc |
There was a problem hiding this comment.
Nice diagram. Perhaps make it generic and move it to the introduction section of this spec?
There was a problem hiding this comment.
A few things which a vague for me:
- Source of Trust should be renamed to something else. I think the dutch term is "authentieke bron". I would advise to look into eidas 2 or de ARF
- Holder of Trust, I don't know what this means, is this a thing?
- Two views are mixed: the proces role (issuer, holder verifier) and compents (wallet, keys, credentials). Difficult to read.
- A dotted line looks like a flow, but why does the credential points to a VP?
- Perhaps add numbering to the steps if that is what you try to explain?
rfc/rfc023-x509credential.md
Outdated
| 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: |
rfc/rfc023-x509credential.md
Outdated
| * 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. |
There was a problem hiding this comment.
a
did:x509issued by the the UZI register.
This is a bit short through the corner ;)
The did is not issued be the UZI register (CIBG?). It is signed with a private key which is also associated with a certificate issued by the UZI register.
rfc/rfc023-x509credential.md
Outdated
| * 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. |
There was a problem hiding this comment.
Isn't this the other way around:
The verifier verifies that the URA number as claimed by the VC is present in the (trusted) certificate. Also implied by the bullet above.
Co-authored-by: reinkrul <[email protected]>
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.
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.
No description provided.