diff --git a/index.html b/index.html index 2b11b55c..74a2ed47 100644 --- a/index.html +++ b/index.html @@ -1,10 +1,13 @@ - + - + JSON Web Token - - +
-

- This specification does neat stuff. -

-
-
+

This specification does neat stuff.

+

Introduction

- See ReSpec's user guide + See + ReSpec's user guide for how to get started!

+
+

JSON Web Token

+ +

+ JSON Web Token (JWT) [[!RFC7519]] is still a widely used means to + express + claims to be transferred between two parties. Providing a + representation of the Verifiable Credentials Data Model for JWT allows + existing systems and libraries to participate in the ecosystem described + in Section . A JWT encodes a set of + claims as a JSON object that is contained in a JSON Web Signature + (JWS) [[!RFC7515]] or JWE [[?RFC7516]]. For this specification, the use + of JWE is out of scope. +

+ +
+
Relation to the Verifiable Credentials Data Model
+ +

+ This specification defines encoding rules of the Verifiable Credential + Data Model onto JWT and JWS. It further defines processing rules how + and when to make use of specific JWT-registered claim names and + specific JWS-registered header parameter names to allow systems based + on JWT to comply with this specification. If these specific + claim names and header parameters are present, their respective + counterpart in the standard verifiable credential and + verifiable presentation MAY be omitted to avoid duplication. +

+
+ +
+
JSON Web Token Extensions
+ +

+ This specification introduces two new registered claim names, + which contain those parts of the standard + verifiable credentials and + verifiable presentations where no explicit encoding rules for + JWT exist. These objects are enclosed in the JWT payload as follows: +

+ + +
+ +
+
JWT and JWS Considerations
+ +
+
JWT Encoding
+ +

+ To encode a verifiable credential as a JWT, specific + properties + introduced by this specification MUST be either: +

+ +
    +
  • Encoded as standard JOSE header parameters, or
    • +
  • Encoded as registered JWT claim names, or
    • +
  • Contained in the JWS signature part.
    • +
+ +

+ If no explicit rule is specified, properties are encoded in + the same way as with a standard credential, and are added to + the vc claim of the JWT. As with all JWTs, the + JWS-based signature of a verifiable credential represented in + the JWT syntax is calculated against the literal JWT string value as + presented across the wire, before any decoding or transformation + rules are applied. The following paragraphs describe these encoding + rules. +

+ +

+ If a JWS is present, the digital signature refers either to the + issuer of the verifiable credential, or in the case of + a verifiable presentation, to the holder of the + verifiable credential. The JWS proves that the + iss of the JWT signed the contained JWT payload and + therefore, the proof property can be omitted. +

+ +

+ If no JWS is present, a proof property MUST be + provided. The proof property can be used to + represent a more complex proof, as may be necessary if the creator + is different from the issuer, or a proof not based on digital + signatures, such as Proof of Work. The issuer MAY include + both a JWS and a proof property. For backward + compatibility reasons, the issuer MUST use JWS to represent proofs + based on a digital signature. +

+ +

+ The following rules apply to JOSE headers in the context of this + specification: +

+ +
    +
  • + alg MUST be set for digital signatures. If only the + proof property is needed for the chosen + signature method (that is, if there is no choice of algorithm + within that method), the alg header MUST be set to + none. +
    • +
  • + kid MAY be used if there are multiple keys associated + with the issuer of the JWT. The key discovery is out of the + scope of this specification. For example, the kid can + refer to a key in a DID document, or can be the identifier + of a key inside a JWKS. +
    • +
  • + typ, if present, MUST be set to JWT. +
    • +
+ +

+ For backward compatibility with JWT processors, the following + registered JWT claim names MUST be used, instead of or in addition + to, their respective standard + verifiable credential counterparts: +

+ +
    +
  • + exp MUST represent the expirationDate + property, encoded as a UNIX timestamp + (NumericDate). +
    • +
  • + iss MUST represent the issuer + property of a verifiable credential or the + holder property of a verifiable presentation. +
    • +
  • + nbf MUST represent issuanceDate, encoded + as a UNIX timestamp (NumericDate). +
    • +
  • + jti MUST represent the id + property of the verifiable credential or + verifiable presentation. +
    • +
  • + sub MUST represent the id + property contained in the credentialSubject. +

    + In bearer credentials and + presentations, sub will not be + present. +

    +
    • +
  • + aud MUST represent (i.e., identify) the intended + audience of the verifiable presentation (i.e., the + verifier intended by the presenting holder to + receive and verify the verifiable presentation). +
    • +
+ +

+ Other JOSE header parameters and JWT claim names not specified + herein can be used if their use is not explicitly discouraged. + Additional + verifiable credential claims MUST be added to the + credentialSubject property of the JWT. +

+ +

+ For more information about using JOSE header parameters and/or JWT + claim names not specified herein, see the Verifiable Credentials + Implementation Guidelines [[?VC-IMP-GUIDE]] document. +

+ +

+ This version of the specification defines no JWT-specific encoding + rules for the concepts outlined in Section + Advanced Concepts (for example, + refreshService, termsOfUse, and + evidence). These concepts can be encoded as they are + without any transformation, and can be added to the + vc JWT claim. +

+ +

+ Implementers are warned that JWTs are not capable of encoding + multiple + subjects and are thus not capable of encoding a + verifiable credential with more than one subject. JWTs + might support multiple subjects in the future and implementers are + advised to refer to the + + JSON Web Token Claim Registry + for multi-subject JWT claim names or the + + Nested JSON Web Token + specification. +

+
+ +
+
JWT Decoding
+ +

+ To decode a JWT to a standard credential or + presentation, the following transformation MUST be performed: +

+ +
    +
  1. Create a JSON object.
    2. +
  2. + Add the content from the vc or vp + claim to the new JSON object. +
    3. +
  3. + Transform the remaining JWT specific headers and claims, + and add the results to the new credential or + presentation JSON object. +
    4. +
+ +

+ To transform the JWT specific headers and claims, the + following MUST be done: +

+ +
    +
  • + If exp is present, the UNIX timestamp MUST be + converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of + the expirationDate property of + credentialSubject of the new JSON object. +
    • +
  • + If iss is present, the value MUST be used to set the + issuer property of the new + credential JSON object or the holder + property of the new presentation JSON object. +
    • +
  • + If nbf is present, the UNIX timestamp MUST be + converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of + the issuanceDate property of the new JSON + object. +
    • +
  • + If sub is present, the value MUST be used to set the + value of the id property of + credentialSubject of the new credential + JSON object. +
    • +
  • + If jti is present, the value MUST be used to set the + value of the id property of the new JSON + object. +
    • +
+ + 
+{
+"alg": "RS256",
+"typ": "JWT",
+"kid": "did:example:abfe13f712120431c276e12ecab#keys-1"
+}
+
+ +

+ In the example above, the verifiable credential uses a + proof based on JWS digital signatures, and + the corresponding verification key can be obtained using the + kid + header parameter. +

+ + 
+{
+"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+"jti": "http://example.edu/credentials/3732",
+"iss": "https://example.com/keys/foo.jwk",
+"nbf": 1541493724,
+"iat": 1541493724,
+"exp": 1573029723,
+"nonce": "660!6345FSer",
+"vc": {
+"@context": [
+  "https://www.w3.org/2018/credentials/v1",
+  "https://www.w3.org/2018/credentials/examples/v1"
+],
+"type": ["VerifiableCredential", "UniversityDegreeCredential"],
+"credentialSubject": {
+  "degree": {
+    "type": "BachelorDegree",
+    "name": "Bachelor of Science and Arts"
+  }
+}
+}
+}
+
+ +

+ In the example above, vc does not contain the + id property because the JWT encoding uses the + jti attribute to represent a unique identifier. The + sub attribute encodes the information represented by + the id property of + credentialSubject. The nonce has been + added to stop a replay attack. +

+ + 
+eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0
+MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
+zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc
+yI6Imh0dHBzOi8vZXhhbXBsZS5jb20va2V5cy9mb28uandrIiwibmJmIjoxNTQxNDkzNzI0LCJpYXQiO
+jE1NDE0OTM3MjQsImV4cCI6MTU3MzAyOTcyMywibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY
+29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd
+3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZ
+UNyZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjd
+CI6eyJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IjxzcGFuIGxhbmc9J2ZyL
+UNBJz5CYWNjYWxhdXLDqWF0IGVuIG11c2lxdWVzIG51bcOpcmlxdWVzPC9zcGFuPiJ9fX19.KLJo5GAy
+BND3LDTn9H7FQokEsUEi8jKwXhGvoN3JtRa51xrNDgXDb0cq1UTYB-rK4Ft9YVmR1NI_ZOF8oGc_7wAp
+8PHbF2HaWodQIoOBxxT-4WNqAxft7ET6lkH-4S6Ux3rSGAmczMohEEf8eCeN-jC8WekdPl6zKZQj0YPB
+1rx6X0-xlFBs7cl6Wt8rfBP_tZ9YgVWrQmUWypSioc0MUyiphmyEbLZagTyPlUyflGlEdqrZAv6eSe6R
+txJy6M1-lD7a5HTzanYTWBPAUHDZGyGKXdJw-W_x0IWChBzI8t3kpG253fg6V3tPgHeKXE94fz_QpYfg
+--7kLsyBAfQGbg
+
+ + 
+{
+"alg": "RS256",
+"typ": "JWT",
+"kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1"
+}
+
+ +

+ In the example above, the verifiable presentation uses a + proof based on JWS digital signatures, and + the corresponding verification key can be obtained using the + kid + header parameter. +

+ + 
+{
+"iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+"jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
+"aud": "did:example:4a57546973436f6f6c4a4a57573",
+"nbf": 1541493724,
+"iat": 1541493724,
+"exp": 1573029723,
+"nonce": "343s$FSFDa-",
+"vp": {
+"@context": [
+  "https://www.w3.org/2018/credentials/v1",
+  "https://www.w3.org/2018/credentials/examples/v1"
+],
+"type": ["VerifiablePresentation"],
+// base64url-encoded JWT as string
+"verifiableCredential": ["..."]
+}
+}
+
+ +

+ In the example above, vp does not contain the + id property because the JWT encoding uses the + jti attribute to represent a unique identifier. + verifiableCredential contains a string array of + verifiable credentials using JWT compact + serialization. The nonce has been added to stop a + replay attack. +

+ + 
+
+eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOjB4YWJjI2tleTEifQ.e
+yJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46d
+XVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzOTAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZ
+To0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJuYmYiOjE1NDE0OTM3MjQsImlhdCI6MTU0MTQ5M
+zcyNCwiZXhwIjoxNTczMDI5NzIzLCJub25jZSI6IjM0M3MkRlNGRGEtIiwidnAiOnsiQGNvbnRleHQiO
+lsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5vc
+mcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50Y
+XRpb24iLCJDcmVkZW50aWFsTWFuYWdlclByZXNlbnRhdGlvbiJdLCJ2ZXJpZmlhYmxlQ3JlZGVudGlhb
+CI6WyJleUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSXNJbXRwWkNJNkltUnBaRHBsZUdGd
+GNHeGxPbUZpWm1VeE0yWTNNVEl4TWpBME16RmpNamMyWlRFeVpXTmhZaU5yWlhsekxURWlmUS5leUp6Z
+FdJaU9pSmthV1E2WlhoaGJYQnNaVHBsWW1abFlqRm1OekV5WldKak5tWXhZekkzTm1VeE1tVmpNakVpT
+ENKcWRHa2lPaUpvZEhSd09pOHZaWGhoYlhCc1pTNWxaSFV2WTNKbFpHVnVkR2xoYkhNdk16Y3pNaUlzS
+W1semN5STZJbWgwZEhCek9pOHZaWGhoYlhCc1pTNWpiMjB2YTJWNWN5OW1iMjh1YW5kcklpd2libUptS
+WpveE5UUXhORGt6TnpJMExDSnBZWFFpT2pFMU5ERTBPVE0zTWpRc0ltVjRjQ0k2TVRVM016QXlPVGN5T
+Xl3aWJtOXVZMlVpT2lJMk5qQWhOak0wTlVaVFpYSWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpvZ
+EhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNJc0ltaDBkSEJ6T
+2k4dmQzZDNMbmN6TG05eVp5OHlNREU0TDJOeVpXUmxiblJwWVd4ekwyVjRZVzF3YkdWekwzWXhJbDBzS
+W5SNWNHVWlPbHNpVm1WeWFXWnBZV0pzWlVOeVpXUmxiblJwWVd3aUxDSlZibWwyWlhKemFYUjVSR1ZuY
+21WbFEzSmxaR1Z1ZEdsaGJDSmRMQ0pqY21Wa1pXNTBhV0ZzVTNWaWFtVmpkQ0k2ZXlKa1pXZHlaV1VpT
+25zaWRIbHdaU0k2SWtKaFkyaGxiRzl5UkdWbmNtVmxJaXdpYm1GdFpTSTZJanh6Y0dGdUlHeGhibWM5S
+jJaeUxVTkJKejVDWVdOallXeGhkWExEcVdGMElHVnVJRzExYzJseGRXVnpJRzUxYmNPcGNtbHhkV1Z6U
+EM5emNHRnVQaUo5ZlgxOS5LTEpvNUdBeUJORDNMRFRuOUg3RlFva0VzVUVpOGpLd1hoR3ZvTjNKdFJhN
+TF4ck5EZ1hEYjBjcTFVVFlCLXJLNEZ0OVlWbVIxTklfWk9GOG9HY183d0FwOFBIYkYySGFXb2RRSW9PQ
+nh4VC00V05xQXhmdDdFVDZsa0gtNFM2VXgzclNHQW1jek1vaEVFZjhlQ2VOLWpDOFdla2RQbDZ6S1pRa
+jBZUEIxcng2WDAteGxGQnM3Y2w2V3Q4cmZCUF90WjlZZ1ZXclFtVVd5cFNpb2MwTVV5aXBobXlFYkxaY
+WdUeVBsVXlmbEdsRWRxclpBdjZlU2U2UnR4Snk2TTEtbEQ3YTVIVHphbllUV0JQQVVIRFpHeUdLWGRKd
+y1XX3gwSVdDaEJ6STh0M2twRzI1M2ZnNlYzdFBnSGVLWEU5NGZ6X1FwWWZnLS03a0xzeUJBZlFHYmciX
+X19.ft_Eq4IniBrr7gtzRfrYj8Vy1aPXuFZU-6_ai0wvaKcsrzI4JkQEKTvbJwdvIeuGuTqy7ipO-EYi
+7V4TvonPuTRdpB7ZHOlYlbZ4wA9WJ6mSVSqDACvYRiFvrOFmie8rgm6GacWatgO4m4NqiFKFko3r58Lu
+eFfGw47NK9RcfOkVQeHCq4btaDqksDKeoTrNysF4YS89INa-prWomrLRAhnwLOo1Etp3E4ESAxg73CR2
+kA5AoMbf5KtFueWnMcSbQkMRdWcGC1VssC0tB0JffVjq7ZV6OTyV4kl1-UVgiPLXUTpupFfLRhf9QpqM
+BjYgP62KvhIvW8BbkGUelYMetA
+
+
+
+
+

Privacy Considerations