This document describes a hypothetical alternative encoding of W3C Verifiable Credentials using JOSE.

This is an experimental specification and is undergoing regular revisions. It is not fit for production deployment.

Introduction

This document does not reflect working group consensus, and its filled with flawed langauge and half baked arguments.

[[VC-DATA-MODEL]] describes a JSON-LD representation for structured claims that an issuer can make about a subject, such that interested parties may be assured of semantic precision, integrity and authenticity.

There are 3 categories of information in a Verifiable Credential:

In v1.1 we rely on JWT encodings for these categories of information which yielded a number of limitations.

In v2 we should address the requirements of the core data model in a more generic way.

We should avoid overloading terminology or conflating semantic or structured data attributes / statments/ claims with security terminology and standard properties of security serialization formats.

We should design with the the intention of supporting a wider family of structured data representations including compact binary forms in the future.

We should design with an open mind towards security work happening at IETF on the following lists:

We should leverage IANA registries for terms critical for interoperability:

Actors

[[VC-DATA-MODEL]] describes 3 primary roles an entity can play: issuer, holder, verifier. An actor is an entity that acts in at least 1 of the roles.

Issuing

          credential -> header, payload (credential), signing capability -> verifiable credential

This section describes the action an issuer performs when acting in that role.

An issuer first obtains all statements they wish to make.

Next the issuer groups these statements into attributes, and at their discretion marks them as metadata or claims.

Next the issuer determins the cryptographic material they intend to use to secure these attributes with a proof.

The issuer might choose to register verification material prior to issuance or after the fact.

The issuer determins which attributes MUST be understood by a verifier.

The issuer formats their credential as a payload, constructs a security header and using a private key or signing capability constructs a verifiable credential using a software library.

The issuer might optionally verify the newly minted credential after creating it, to ensure that 3rd parties will be able to perform the verififcation process successfully.

The issuer might optionally present the newly minted credential to a first holder, or communicate a capability to this holder using some established protocol for offering credentials.

Presenting

          <- nonce, aud
          credentials, metadata -> presentation
          presentation -> header, payload (presentation), signing capability -> verifiable presentation

This section describes the action a holder performs when acting in that role.

The holder first determins any required or optional credentials and metadata that a verifier accepts. It is possible the verifier advertises this according to some established protocol for requesting information.

Next the holder prepares their presentation, including any credentials and metadata they wish to disclose or prove to the verifier.

In the case that the verifier requires a fresh proof, or replay attack mitigation, the holder must obtain a required nonce value from the verifier. An optional aud value might also be chosen by the holder. A verifier might offer suggested nonce and aud values via a well known location, or might accept other credentials or tokens from some issuer trusted by the verifier to facilitate proof freshness.

The holder might choose to register verification material prior to presenting or after the fact (presentations might not be processed immediatly).

Next the holder crafts their presentation as a payload and secures it using a protected header header and private key or signing capability. Using a software library the holder produces a verifiable presentation.

The holder might optionally verify the newly minted presentation after creating it, to ensure that 3rd parties will be able to perform the verififcation process successfully.

The holder might optionally transmit the verifiable presentation over a network, or to an internal software system or to a harware device via a transport protocol.

Verifying


          verifiable credential -> header, payload, signature, public key -> 
            verified: true | false, 
            details: []

          verifiable presentation -> header, payload, signature, public key -> 
            verified: true | false, 
            credential details: []

This section describes the action an verifier performs when acting in that role.

The verifier first obtains any required or optional credentials and presentations. Its possible the verifier advertises this according to some established protocol for requesting information.

The verifier first obtains the holder's registered verification material and validates proof associated with the presentation.

Next the verifier checks all the required to be understood attributes.

Next the verifier might at their discretion reject presentations or mark them as invalid based on their own understanding of attributes.

Next the verifier checks each credential presented.

Next the verifier obtains the verification material for each credential issuer, and uses a software library to check the credential proof.

Next the verifier might at their discretion reject credentials or mark them as invalid based on their own understanding of attributes.

The verifier might store the presentation, credentials or just the claims and associated metadata.

The verifier might acknowledge receipt or acceptance / rejection of the presentation as a whole or in parts to the holder.

Attributes

[[VC-DATA-MODEL]] describes claims and metadata. An attribute is a claim, and/or metadata.

Producing

Header and payload and signature are produced by the issuer, or prover.

Values for attributes in the header are more authoritative than those present in payloads.

Issuers and provers MUST NOT create contradictng metadata or claims associated with the header values, in the payload.

A verifiable credential is produced when a credential is used as a JWS Payload and secured with a protected header and signature.

Consuming

A verifier MUST process the header and understand all critical values in it.

Metadata associated with the security of the payload is exclusive to the header.

Values for attributes in the header are more authoritative than those present in payloads.

Once a credential or presenation has been verified, the header can be ignored and the payload becomes the source of truth for claims made by the issuer.

A credential is consumed when a verifiable credential, represented as a header, payload and signature is verified using a public key trusted by the verifier.

Header

See JWS Header Parameters.

See JWE Header Parameters.

Headers MAY contain attributes.

Actors MUST understand all attributes marked critical via the header.

The header is in a sense a collection of metadata about the "statements" or "claims" the issuer is making about the payload and its security properties.

The security of the serialization scheme comes exclusively from processing the header, payload and signature using the verification material. The header and payload must be treated as opaque until this process has suceeded or failed. Leveraging of iss and kid as a hint to obtain the verification material is the only exception to this rule.

iss

            did:example:123 
            https://government.example
            https://organization.example
            https://person.example
            https://device.example

kid

            did:example:123#key-0
            https://government.example/path/bar?query=foo#fragment-baz
          
            #key-0
            /path/bar?query=foo#fragment-baz
          
            _Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A

using hints: The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS.

[[RFC3986]] MUST be used for interpertation and resolution of URIs, and defines the rules for relative URIs.

In the case that a kid is some form of absolute IRI, the issuer is assumed to be optional, and MUST NOT be used to obtain verification material.

In the case that a kid is some form of relative IRI, the iss MUST be present, and MUST be used to obtain verification material.

In the case that a kid is not an IRI, it is assumed to be a sufficient hint for a verifier to verification material.

alg

            ES256
            EdDSA

allow unregistered algorithms "alg" values should either be registered in the IANA "JSON Web Signature and Encryption Algorithms" registry established by [JWA] or be a value that contains a Collision-Resistant Name.

cty

            application/vc+json
            application/vc+ld+json

See omit media type prefix: To keep messages compact in common situations, it is RECOMMENDED that producers omit an "application/" prefix of a media type value in a "cty" Header Parameter when no other '/' appears in the media type value. A recipient using the media type value MUST treat it as if "application/" were prepended to any "cty" value not containing a '/'. For instance, a "cty" value of "example" SHOULD be used to represent the "application/example" media type, whereas the media type "application/example;part="1/2"" cannot be shortened to "example;part="1/2"".

crit

We should use crit to require verifiable credentials encoded using JOSE to be distinguishable and consistently processed relative to existing token formats, such as id_token, access_token or other JWTs.

See extensions that MUST be understood: The "crit" (critical) Header Parameter indicates that extensions to this specification and/or [JWA] are being used that MUST be understood and processed. Its value is an array listing the Header Parameter names present in the JOSE Header that use those extensions. If any of the listed extension Header Parameters are not understood and supported by the recipient, then the JWS is invalid. Producers MUST NOT include Header Parameter names defined by this specification or [JWA] for use with JWS, duplicate names, or names that do not occur as Header Parameter names within the JOSE Header in the "crit" list. Producers MUST NOT use the empty list "[]" as the "crit" value. Recipients MAY consider the JWS to be invalid if the critical list contains any Header Parameter names defined by this specification or [JWA] for use with JWS or if any other constraints on its use are violated. When used, this Header Parameter MUST be integrity protected; therefore, it MUST occur only within the JWS Protected Header. Use of this Header Parameter is OPTIONAL. This Header Parameter MUST be understood and processed by implementations.

nbf

Explain how payload is activated as distinct from how claims in payload are interpretted.

exp

Explain how payload is expired as distinct from how claims in payload are interpretted.

jti

Seems relevant to verifiable presentations and NOT relevant to verifiable credentials.

The "jti" claim MAY be used to prevent the JWT from being replayed.

The "jti" (JWT ID) claim provides a unique identifier for the JWT.

x5c

X.509 certificate chain: The "x5c" (X.509 certificate chain) parameter contains a chain of one or more PKIX certificates [[RFC5280]].

x5u

X.509 URL: The "x5u" (X.509 URL) parameter is a URI [[RFC3986]] that refers to a resource for an X.509 public key certificate or certificate chain [[RFC5280]].

Payload

Payloads MAY contain attributes.

allowed payload types: The JWS Payload used in this example is the octets of the UTF-8 representation of the JSON object below. (Note that the payload can be any base64url-encoded octet sequence and need not be a base64url- encoded JSON object.)

The "JWS Payload" MUST be of a content type defined by the [[VC-DATA-MODEL]].

Credential

TODO: Point to core data model definition of credential.

TODO: Provide guidance regarding handling embedded proof property. (ignore by default.)

application/vc+ld+json

Payloads of this type MUST conform to [[RFC8259]].

Payloads of this type MUST be a JSON-LD Document as described in JSON-LD

Presentation

TODO: Point to core data model definition of presentation.

TODO: Provide guidance regarding handling embedded proof property. (ignore by default.)

application/vp+ld+json

Payloads of this type MUST conform to [[RFC8259]].

Credential Examples

Government ID

{
  "header": {
    "iss": "https://government.example",
    "kid": "/issuers/42#key-1337",
    "alg": "ES256",
    "cty": "application/vc+ld+json",
    "nbf": 1575375592000,
    "exp": 1890994792000,
    "crit": ["cty", "nbf", "exp"]
  },
  "payload": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/citizenship/v1"
    ],
    "id": "urn:uuid:e42a1c3c-3cbf-4834-9430-dc2376b8ef0c",
    "type": ["VerifiableCredential", "PermanentResidentCard"],
    "issuer": "https://government.example",
    "identifier": "e42a1c3c-3cbf-4834-9430-dc2376b8ef0c",
    "name": "Permanent Resident Card",
    "description": "Government of Example Permanent Resident Card.",
    "issuanceDate": "2019-12-03T12:19:52Z",
    "expirationDate": "2029-12-03T12:19:52Z",
    "credentialSubject": {
      "id": "did:example:b34ca6cd37bbf23",
      "type": ["PermanentResident", "Person"],
      "givenName": "JOHN",
      "familyName": "SMITH",
      "gender": "Male",
      "image": "data:image/png;base64,iVBORw0KGgo...kJggg==",
      "residentSince": "2015-01-01",
      "lprCategory": "C09",
      "lprNumber": "999-999-999",
      "commuterClassification": "C1",
      "birthCountry": "Bahamas",
      "birthDate": "1958-07-17"
    }
  },
  "signature": "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h"
}

Bill of Ladding

{
  "header": {
    "iss": "https://logistics.example",
    "kid": "/issuers/32#deadbeef",
    "alg": "EdDSA",
    "cty": "application/vc+ld+json",
    "nbf": 1576036255000,
    "crit": ["cty", "nbf"]
  },
  "payload": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/traceability/v1"
    ],
    "id": "https://logistics.example/credential/123",
    "type": ["VerifiableCredential", "BillOfLadingCertificate"],
    "name": "Bill Of Lading Certificate",
    "description": "This document includes recommended bill of lading fields.",
    "issuanceDate": "2019-12-11T03:50:55Z",
    "issuer": {
      "id": "https://logistics.example",
      "type": "Organization",
      "name": "Hauck Group",
      "description": "Focused secondary synergy",
      "address": {
        "type": "PostalAddress",
        "streetAddress": "3198 O'Kon Wall",
        "addressLocality": "North Adolphchester",
        "addressRegion": "Nevada",
        "postalCode": "50788",
        "addressCountry": "Cote d'Ivoire"
      },
      "email": "Bernita.Quitzon98@example.com",
      "phoneNumber": "555-171-4411",
      "faxNumber": "+1-555-758-9761"
    },
    "credentialSubject": {
      "type": ["BillOfLading"],
      "billOfLadingNumber": "991205182A",
      "bookingNumber": "991205182",
      "scac": "NISC",
      "carrier": {
        "type": ["Organization"],
        "name": "Carrior Goods And More",
        "email": "Adaline29@example.com",
        "phoneNumber": "+1 555-234-9983"
      },
      "consignor": {
        "type": ["Organization"],
        "name": "Consignor Is Us",
        "email": "Idella60@example.org",
        "phoneNumber": "+1-555-953-9479"
      },
      "consignee": {
        "type": ["Organization"],
        "name": "Victorian Consignee",
        "email": "Victoria.Hane74@example.org",
        "phoneNumber": "+1-555-455-9053"
      },
      "notify": {
        "type": ["Organization"],
        "name": "Florida Contact Org",
        "email": "Florida91@example.net",
        "phoneNumber": "+1-555-104-1126"
      },
      "freight": {
        "type": ["ParcelDelivery"],
        "deliveryAddress": {
          "type": ["Place"],
          "geo": {
            "type": ["GeoCoordinates"],
            "latitude": "-20.840731978309044",
            "longitude": "-159.78393883134225"
          },
          "address": {
            "type": ["PostalAddress"],
            "organizationName": "Hahn LLC",
            "streetAddress": "786 Pfeffer Plains",
            "addressLocality": "West Ottilie",
            "addressRegion": "Nebraska",
            "postalCode": "50878-0870",
            "addressCountry": "Cook Islands"
          }
        },
        "originAddress": {
          "type": ["Place"],
          "geo": {
            "type": ["GeoCoordinates"],
            "latitude": "-23.25979250428427",
            "longitude": "-58.36431415044023"
          },
          "address": {
            "type": ["PostalAddress"],
            "organizationName": "Rosenbaum, Hills and Pagac",
            "streetAddress": "71834 Zelma Trail",
            "addressLocality": "West Gerhardview",
            "addressRegion": "North Carolina",
            "postalCode": "78251-3640",
            "addressCountry": "Paraguay"
          }
        },
        "deliveryMethod": "Ocean transport",
        "trackingNumber": "178380801954"
      },
      "portOfLoading": {
        "type": ["Place"],
        "unLocode": "USMOB"
      },
      "portOfDischarge": {
        "type": ["Place"],
        "unLocode": "MXATM"
      }
    }
  },
  "signature": "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h"
}

Presentation Examples

These examples are framed in language that is meant to be understandable by the general public, these examples are not reflective of suggested use for the specification.

Purchasing alcohol

Some verifiers might require proof of age prior to the purchase of certain products. 

{
  "header": {
    "iss": "did:example:123",
    "kid": "#555",
    "alg": "ES256",
    "cty": "application/vp+ld+json",
    "aud": "drug-store.example",
    "nonce": "fe3b66da-6faa-4f48-9a28-3e66febc737b",
    "crit": ["cty", "aud", "nonce"]
  },
  "payload": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": "VerifiablePresentation",
    "holder": "did:example:123",
    // encoded government id verifiable credential
    "verifiableCredential": ["ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h..."] 
  },
  "signature": "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h"
}

Clearing customs

Some verifiers might require scientific tests or provenance assertions prior to allowing products to move into logistics infrastructure. 

{
  "header": {
    "iss": "did:example:123",
    "kid": "#555",
    "alg": "ES256",
    "cty": "application/vp+ld+json",
    "aud": "customs.example",
    "nonce": "fe3b66da-6faa-4f48-9a28-3e66febc737b",
    "crit": ["cty", "aud", "nonce"]
  },
  "payload": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/traceability/v1"
    ],
    "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
    "type": ["VerifiablePresentation", "TraceablePresentation"],
    "workflow": {
      "definition": ["urn:uuid:n1552885-cc91-4bb3-91f1-5466a0be084e"],
      "instance": ["urn:uuid:f5fb6ce4-b0b1-41b8-89b0-331ni58b7ee0"]
    },
    "holder": {
      "id": "did:example:456",
      "type": "Organization",
      "location": {
        "type": "Place",
        "geo": {
          "type": "GeoCoordinates",
          "latitude": "68.7083",
          "longitude": "4.6377"
        },
        "address": {
          "type": "PostalAddress",
          "organizationName": "Ratke - Bergstrom",
          "streetAddress": "21851 Ima Heights",
          "addressLocality": "O'Connellborough",
          "addressRegion": "Missouri",
          "postalCode": "65587",
          "addressCountry": "Cyprus"
        }
      }
    },
    // bill of ladding and certificate of origin for products 
    // encoded as verifiable credentials
    "verifiableCredential": [
      "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h...",
      "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h..."
    ]
  },
  "signature": "ZW5jb2RpbmctaXMtbm90LWVuY3J5cHRpb24h"
}

Security Considerations

Authority of the verification material

The verification material (public key or certificate) is the ultimate authority regarding the security of the serialization of the data model.

Hints used to obtain this material such as iss, or kid ought to be helpful, but are not required to be.

For example:

          {
            "iss": "https://gov.example",
            "kid": "did:example:789#key-234",
            "alg": "ES256"
          }

A verifier might choose to hash this object and then lookup a certificate. If the verifier trusts the certificate, that is all they need to proceed to processing the associated payload.

Some actors might rely on defined protocols for obtaining keys or certificates based on hints.

A verifier is not required to disclose how they obtain the issuer's key material.

Opacity of claims

Issuers are not required to disclose attributes in plaintext.

This might result in awkwardness for the holder, as they cannot see what claims are in a given credential.