LogoLogo
SpecificationsToepassingen op NutsNuts Node documentation
  • Nuts specifications
  • RFC
    • RFC001 Nuts Start Architecture
    • RFC002 Authentication token
    • RFC003 OAuth2 Authorization
    • RFC004 Verifiable Transactional Graph
    • RFC005 Distributed Network using gRPC
    • RFC006 Distributed Registry with Decentralized Identifiers (DID)
    • RFC008 Certificate Structure
    • RFC011 Verifiable Credential
    • RFC012 Nuts Organization Credential
    • RFC013 Verifiable Credential IRMA Proof Type
    • RFC014 Nuts Authorization Credential
    • RFC015 Node identity
    • RFC017 Distributed Network Protocol (v2) using gRPC
    • RFC019 Employee Identity Authentication Means
    • RFC020 Authorization credential extension
    • RFC021 VP Token Grant Type
    • RFC022 Discovery Service
    • RFC023 X509Credential
  • templates
    • Default RFC layout
Powered by GitBook
On this page
  • RFC011 Verifiable Credentials
  • Abstract
  • Status
  • Copyright Notice
  • 1. Introduction
  • 2. Terminology
  • 3. W3C Verifiable Credential
  • 3.1 JSON-LD context
  • 3.2 Supported proofs
  • 3.3 Content-type
  • 3.4 Updates
  • 3.5 Identifiers
  • 3.6 Active issuer
  • 3.7 Transaction requirements
  • 3.8 Validation
  • 3.9 VC Example
  • 4. Required chapters for a Verifiable Credential type
  • 4.1 CredentialSubject
  • 4.2 Issuance & distribution
  • 4.3 Supported proofs
  • 4.4 Trust
  • 4.5 Revocation
  • 4.5.1 Default revocation
  • 4.6 Use cases
  • 4.7 Privacy considerations
  • 4.8 Services

Was this helpful?

  1. RFC

RFC011 Verifiable Credential

PreviousRFC008 Certificate StructureNextRFC012 Nuts Organization Credential

Last updated 3 months ago

Was this helpful?

Nuts foundation

W.M. Slakhorst

Request for Comments: 011

Nedap

February 2021

RFC011 Verifiable Credentials

Abstract

This RFC describes the generic requirements for within the Nuts specification. It also lists all required chapters for a specific VC RFC. This RFC uses the specification.

Status

This document describes a Nuts standards protocol.

Copyright Notice

1. Introduction

It's to be expected that multiple parties can assert certain claims with information about a subject. These claims have to be structured in such a way that they are verifiable and searchable. Examples of such claims are a company name, or its chamber of commerce number. Users can search on the name of an organization to find out which services are supported. This will directly influence the interaction the user can have with the system of that organization. Making sure this information is correct and that it can be trusted is therefore extremely important.

2. Terminology

  • holder: The party that receives a VC from an issuer.

  • issuer: The party that issues a VC.

  • proof: Proof asserting that a VC is valid using cryptography.

3. W3C Verifiable Credential

3.1 JSON-LD context

3.2 Supported proofs

3.2.1 JsonWebSignature2020

The proof MUST have a verificationMethod which contains an assertMethod ID from a resolvable Nuts DID Document of a public key of the JSONWebKey2020 type.

{
  "type": "JsonWebSignature2020",
  "proofPurpose": "assertionMethod",
  "verificationMethod": "did:nuts:EgFjg8zqN6eN3oiKtSvmUucao4VF18m2Q9fftAeANTBd#twlH6rB8ArZrknmBRWLXhao3FutZtvOm0hnNhcruenI",
  "created": "2021-03-09T11:44:56.382202+01:00"
  "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..ZXlKaGJHY2lPaUpGVXpJMU5pSjkuVHVqZndMVVJwcnUzbjhuZklhODB1M1M0LW9LcWY0WUs5S2hoZEktUkZPSzdlbnZJTTdLN1E5SzBSeHhRSzNIVWJPTUJyLVlZX1g0eW1YR0pXOHF4UkEuN0F4a3lZekNXTElPZ2Q5TlpnR3p2aHd2UzZZQ3FpRTRPX3FwWGVOSEN6X091S1c0TmJsWkJueTBkZVhXT0lXZ3JNczF4OTZlNmtnaGZGYTRNd0J3TlE="
}

3.3 Content-type

All VCs MUST have a content-type equal to application/vc+json when published on the network. VCs MAY NOT specify more than one additional type next to VerifiableCredential.

3.4 Updates

VCs are not updatable, an update can be performed by revoking the current and issuing a new VC.

3.5 Identifiers

VC identifiers MUST be constructed as DID#id where id is unique for the given issuer.

3.6 Active issuer

A VC MUST have an active issuer at the time of usage. Usage includes using the VC to generate a VP or sending it along in an OAuth flow. If the issuer is deactivated at the time of usage, the VC MUST be regarded as invalid.

3.7 Transaction requirements

3.8 Validation

A VC can only be used when it's valid. The validity of a VC is ultimately up to the verifier to check, but the holder can perform some basic checks before adding a VC to the internal storage. Before adding a VC to the node, the node MUST validate that:

  • all JSON-LD contexts are resolvable.

  • the embedded proof is correct.

Any additional requirements for a VC MUST be validated by the verifier when the VC is presented.

3.9 VC Example

Below is an example of a credential. Issuer and Subject are the same in the example. This specification neither requires nor prevents this.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://nuts.nl/credentials/v1"
  ],
  "type": [
    "NutsOrganizationCredential",
    "VerifiableCredential"
  ],
  "id": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv#6f91673b-afa9-4d26-9e0f-00d989943275",
  "issuanceDate": "2021-03-15T16:34:17.687862+01:00",
  "issuer": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv",
  "credentialSubject": {
    "id": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv",
    "organization": {
      "city": "IJbergen",
      "name": "Because we care B.V."
    }
  },
  "proof": {
    "type": "JsonWebSignature2020",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv#h22vbXHX7-lRd1qAJnU63liaehb9sAoBS7RavhvfgR8",
    "created": "2021-03-15T16:34:17.687862+01:00",
    "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..hKcboC8m6YnZPi6ReJAYs0J0Ztn5nxcx2EavoXdtrkWxmE1JZmImW89_8IIgjvfI8XtGeDlEnGywAuY2u7y9Bw"
  }
}

4. Required chapters for a Verifiable Credential type

All the following chapters MUST be present in the specification of a VC.

4.1 CredentialSubject

It MUST specify the contents of the credentialSubject JSON field. It MUST specify which parts of the credentialSubject are mandatory or optional, and the format.

4.2 Issuance & distribution

A VC specification MUST specify how a VC is issued and if there are any requirements on the issuer. It MUST specify any requirements for the holder. It MUST specify if VCs or other credentials are required in order to obtain the VC. It MUST specify the content-type type selector.

4.3 Supported proofs

It MUST specify which proof types are acceptable or if there's a limitation to certain proof types. This also means that specifications SHOULD to be updated when new proof types are available.

4.4 Trust

It MUST list the requirements for when a VC is to be trusted. It could, for example, require every node to trust a certain issuer by default.

4.5 Revocation

It MUST specify how a VC can be revoked by the issuer, or it MUST specify an expiration duration. It MAY refer to the default revocation mechanism stated below.

4.5.1 Default revocation

VCs that are issued by a Nuts DID can be revoked by publishing the following transaction on the network:

{
  "issuer": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv",
  "subject": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv#6f91673b-afa9-4d26-9e0f-00d989943275",
  "date": "2021-03-15T16:34:47.422436+01:00",
  "proof": {
    "type": "JsonWebSignature2020",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:nuts:t1DVVAs5fmNba8fdKoTSQNtiGcH49vicrkjZW2KRqpv#h22vbXHX7-lRd1qAJnU63liaehb9sAoBS7RavhvfgR8",
    "created": "2021-03-15T16:34:47.422436+01:00",
    "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..Rc7iK7wXabMx24ZNAFJIwxqpYGCdye0EmdOYwu5CO54pwEPNIQt-9qIvqEZ7ZBFcFUdhnNCvYkR8IDtFAM18Rw"
  }
}

Such a revocation transaction has the following requirements:

  • the issuer MUST match the DID as the issuer field of the VC.

  • the subject MUST match the id field of the VC.

  • a reason MAY be filled with a revocation reason.

  • the date MUST provide the date in RFC3339 format. From this moment in time the VC is revoked.

  • the proof MUST be a JsonWebSignature2020 proof.

The transaction MUST be published on the Nuts network. The content-type is application/vc+json;type=revocation

The signature is calculated as stated in §3.1.1.

4.6 Use cases

4.7 Privacy considerations

It MUST specify if a VC SHOULD be published via some means. It MUST specify if it contains personal information as identified by the GDPR or local legislation. It MUST specify who MAY receive and/or store the VC.

4.8 Services

It MUST specify if other services than the Nuts network are required for the VC to be issued and/or obtained. If so, it MUST specify the protocol.

This document is released under the .

DID: .

VC: Verifiable Credential according to the .

VP: Verifiable Presentation according to the .

To support a variety of claims, Nuts uses the Verificable Credential (VC) format as described by . Every Nuts specific VC and proof type must follow the W3C specification. If the W3C specification offers optional fields then the specification of that credential must specify if and how they should be used. All VCs MUST use DIDs as specified in to reference the issuer.

Verifiable Credentials are usually represented in format. Every JSON-LD document requires one or more context definitions. Every Nuts VC type and proof type SHOULD be specified in the . Nodes MUST support this context and the . A node MAY support additional contexts.

To ensure the authenticity and integrity of the VC, a VC document MUST contain an embedded proof in a proof section as described in section 2.2.1 of . The following proof types must be supported by a Nuts node implementation:

This signature suite is specified by . It uses a detached JWS for presenting the signature in the jws part of the proof. describes how a detached JWS works. The hashing algorithm MUST be of type ES256.

If a VC issuer is a Nuts DID Subject and the VC is published via a transaction according to and then the transaction MUST refer to the correct transaction as specified by . This ensures the correct ordering of transactions.

It MUST specify where the VC SHOULD be used: as requirement for other VCs, in the OAuth flow according to or any other use case. If a VC can be used in a Verifiable Presentation (VP), it MUST specify if additional VCs are to be expected in the VP. It SHOULD describe the use case well enough so any implementation can take appropriate measures for optimizing querying/checking, such as indexing certain fields.

Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license
Decentralized Identifiers
Verifiable Credential Data Model
Verifiable Credential Data Model
W3C Verifiable Credential specification
RFC004
JSON-LD
Nuts JSON-LD context
W3C Verifiable Credential context
Verifiable Credential Data Integrity Specification
https://w3c-ccg.github.io/lds-jws2020
RFC7797
RFC003
Verifiable Credentials (VC)
Verifiable Credential Data Model
RFC004
RFC005
RFC004