diff --git a/index.html b/index.html index 2b11b55c..74a2ed47 100644 --- a/index.html +++ b/index.html @@ -1,10 +1,13 @@ - +
- +- This specification does neat stuff. -
-This specification does neat stuff.
- See ReSpec's user guide + See + ReSpec's user guide for how to get started!
+ 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. +
+ ++ 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. +
++ 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: +
+ +vc
: JSON object, which MUST be present in a JWT
+ verifiable credential. The object contains the
+ credential according to this specification.
+ vp
: JSON object, which MUST be present in a JWT
+ verifiable presentation. The object contains the
+ presentation according to this specification.
+ + To encode a verifiable credential as a JWT, specific + properties + introduced by this specification MUST be either: +
+ +
+ 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. +
++ To decode a JWT to a standard credential or + presentation, the following transformation MUST be performed: +
+ +vc
or vp
+ claim to the new JSON object.
+ + To transform the JWT specific headers and claims, the + following MUST be done: +
+ +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.
+ 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.
+ 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.
+ sub
is present, the value MUST be used to set the
+ value of the id
property of
+ credentialSubject
of the new credential
+ JSON object.
+ 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
+
+