August 11, 2015 4:19 PM
1. Introduction
Whether information printed on a credential or other information, possible methods of use are (1) transmitting and using it as digital data and (2) displaying it on a screen or paper for use, for a total of 2 methods. In the former case, it may be provided as signed structured data, such as JSON with a JWS attestation, and standard API delivery methods can be applied. In the latter case, however, merely displaying or printing a value generally cannot ensure its integrity. Traditionally, integrity has been ensured by printing on special paper in a secure environment, but that approach makes broad use difficult.
This document therefore describes a method using QR codes that can ensure data integrity even when data is delivered to another party through a screen or paper.
2. Terminology and Definitions
This document adopts the terminology defined in RFC7515 and RFC7519.
3. Abbreviations
- JSON JavaScript Object Notation
- JWS JSON Web Signature
- JWT JSON Web Token
4. Method
4.1 Signature Method
To fit a signature into a QR code, an algorithm that produces a relatively small signature must be selected. The signature method shall be as follows.
- Signature format: JWS[RFC7615] detached signature
- Algorithm (alg): ES256
- Payload type (cty): URL or CJWT
4.2 JWS Header
The JWS header contains the following:
- Required headers: alg, cty
- Recommended headers: jku, kid
Unless the JWK is known out of band, jku must be included in the header. Unless it is clear out of band which key was used, kid must be included in the JWS header.
4.3 Payload
Because a payload may be stored in a database or used in combination with other information, it must be in a structured format such as JSON. Such a payload, however, is often too large to fit directly into a QR code. It must therefore be transformed into a smaller form. This document proposes 2 methods: a URL-reference method and a dictionary-compression method.
4.3.1 URL-Reference Method
Under the URL-reference method, the data itself is stored at a network location identified by a URL. To protect confidentiality when retrieving the data, the URL must be an HTTPS URL. To allow the integrity of the target data to be checked, the URL must include the SHA256 hash value of the data itself.
Example:
The URL-reference method is simpler to process than the dictionary-compression method and has the advantage of supporting large payloads. Its disadvantage is that it cannot operate entirely offline.
4.3.2 Dictionary-Compression Method
Because payloads are generally relatively small and contain little repetition, general-purpose compression is not very effective. Therefore, the variable order is specified and variable names are omitted, while an application-specific compression dictionary is prepared for values and used to compress them.
The file specifying the variable order must be retrievable from the issuer’s .well-known/jwt-orders.json.
jwt-orders.json is a JSON file containing the following 2 members.
- delim
- Required. The JSON String representation of the character used to delimit each member value in the compressed JSON.
- mem
- Required. An ordered JSON array specifying the order of member values when generating compressed JSON. It must include issuer. Nested values must use flat notation.
The dictionary used to compress variable values must be retrievable from the issuer’s .well-known/compress-dict.json.
compress-dict.json is a JSON file representing the values used to replace each member value. A top-level member is a variable name, and its value is a JSON object whose member names are the terms to be replaced and whose member values are the replacement terms. The top-level members include the special value “_default.” Its value contains replacement dictionaries not specified by other top-level members.
Compression is performed using the following process.
- Flatten the target JSON.
- Reorder the flattened JSON in the order specified by mem in jwt-order.json.
- Using each member name, select the applicable replacement dictionary from compress-dict.json and replace the member value with the corresponding value.
- While preserving order, concatenate the replaced values using the value of the delim member in jwt-orders.json to generate a single UTF8 string.
The advantage of the dictionary-compression method is its strength in offline environments. Its disadvantages are more complex processing than the URL method and a smaller supported payload size.
4.4 Signature Generation
Signature generation must follow the provisions of JWS[RFC7615].
The target payload is the one generated in 4.2.
4.5 QR-Code Encoding
The signed data is a JWS detached signature. Represent the payload and detached signature in separate QR codes. Arrange the 2 QR codes vertically or horizontally. When arranged vertically, the payload is on top; when arranged horizontally, the payload is on the left.
4.6 Signature Verification
Signature verification follows the JWS signature-verification process.
4.7 Application Determination
Determining whether the JWS is valid requires checking not only that the signature is correct, but also that the payload content satisfies the application’s requirements. For example, in the case of an attribute credential, the value of “iss” in the payload might be required to match the prefix of the “jku” value in the JWS header. This must be specified for each application.
5. Example
Payload
{“name”:”Hikari Go”,”gender”:”F”,”birth_date”:”1964-10-01″,”address”:{“region”:”Tokyo”,”locality”:”Chiyoda-ku”,”street_address”:”Otemachi 1-chome 1-123, Otemachi Residence Room 1504″},”email”:”hikari.go@example.com”,”email_verified”:true,”jti”:”EFGX9F”,”sub”:”1234567890128″,”iat”:1494669600,”exp”:1546300799,”iss”:”https://example.com”}
JWS Header
{“alg”:”ES256″,”kid”:”C03MT”, “jku”:”https://example.com/jwks”,”cty”:”JWT”}
Compressed Payload
Hikari Go:F:boz3d:d:2t:Otemachi 1-chome 1-123 Otemachi Residence Room 1504:hikari.go@example.com:1:EFGX9F:1234567890128:pkmlbz:opvyg0:https://example.com
Signature
eyJhbGciOiJFUzI1NiIsImtpZCI6IkMwM01UIn0..iXNAHvr55iw4LSnaGGZI7nq7hM4mOON0ccj7PnW5He9LuqAX5MSaNpeIFQM4HnkOkUPVunmQz6Yi3zLIfisfkQ
Payload URL
Signature
6. Security Considerations
7. Privacy Considerations
8. IANA Considerations
9. Acknowledgement
Normative References
Informative References