169 - QR Code Specifications
<v1.2.0 Draft - WIP>
CBOR Identity Data in QR Code
Tag: 169 (identity-data)
Data Item: JSON Object
Semantics: Identity Data of a Person in QR-Code
Point of Contact: Resham Chugani ([email protected])
IANA Registration: IANA CWT Registry (Search for: 169)
Version: 1.2.0 <Draft-WIP> (As a result of the revived/ongoing Claim 169 Working Group effort)
1. Introduction
This document specifies an enhanced version of the generic data structure and encoding mechanism for storing the Identity Data of a registered person using any ID platform, along with the corresponding transport encoding mechanism in a machine-readable optical format (QR).
This enhanced version is the outcome of the revival of the Claim 169 Working Group in September 2025, which undertook a collaborative effort to refine and extend the specification. As part of the detailed discussions and brainstorming sessions within the working group, additional attributes (19–23) were introduced to strengthen applicability, usability, and interoperability across diverse identity ecosystems, along with certain updates on guidelines, standard CWT attributes, credential status and security considerations. For details, refer to the section titled, "What Changed" below.
Further details on the evolution of these changes and detailed discussions can be found under the section titled "Iteration 2" here.
2. Rationale
Once a person is registered in an identity system, their data serves as the foundation for identification, granting them access to social benefits and government services. The level of assurance in this identification process varies depending on the authentication methods employed. Low assurance is achieved through basic identifiers like ID numbers, demographic data, passwords, or PINs. Conversely, higher assurance levels are attained through one-time passwords (OTP) and biometrics.
Among these methods, biometric-based authentication, such as facial authentication, offers the highest level of assurance as it assures the presence of the individual. While this is effective for online systems & personal phones where verification is conducted on a server or a personal device; offline authentication presents challenges in maintaining a similarly high level of assurance. The offline authentication mechanism should work for people with no phone.
For instance, in a cross-border scenario remote areas often face significant internet connectivity issues. Even when internet access is available, server reliability may be inconsistent. In such circumstances, scanning a QR code containing the person's facial photograph and identity information, alongside assurance that the data is country-signed, provides an additional layer of security and affirmation for the countries involved.
Please note: The trust layers required to sync the country's keys are beyond the scope of this document. We assume the app scanning the QR code already has the country's key to verify.
To tackle the challenge above, we propose a standard CBOR-based QR Code that involves embedding a low-resolution image of the person with a minimal demographic dataset within the QR code. This QR code would be digitally signed by the ID authorities (Issuer) and then printed on a physical card. Subsequently, the signed data within the QR code can be utilized for facial authentication. However, it's essential to recognize that QR codes have limitations regarding size. We suggest leveraging CBOR Web Token (CWT) with ED25519/ECC keys to generate a smaller signature and more condensed data.
Claim 169 represents a JSON Object that includes the below table as ID attributes. You can find an illustration of the ID structure contained within Claim 169, where:
3. Semantics
3.1 CBOR Map Structure Overview
Note:
All the fields here are optional.
The issuer of IDClaim169 is expected to host the JWKS file at the standard .well-known URL. This allows relying parties to verify the signature of the issued IDClaim169.
Please ensure to review the Guidelines and important note(s) below with respect to standard CWT attributes and credential status.
1
tstr
ID
Unique ID to indicate the PII data
2
tstr
Version
Version of the ID data
4
tstr
Full Name
Full name of the person
5
tstr
First Name
First name of the person
6
tstr
Middle Name
Middle name of the person
7
tstr
Last Name
Last name of the person
8
tstr
Date of Birth
Date of birth in YYYYMMDD format
9
int
Gender
Gender with the following values 1 - Male, 2 - Female, 3 - Others
10
tstr
Address
Address of the person, separator character \n
11
tstr
Email ID
Email id of the person
13
tstr
Nationality
Nationality of the person: Use the two-letter ISO 3166-2 country code or three-letter ISO 3166-1 alpha-3 country code
14
int
Marital Status
Marital status - Can contain the following values 1 - Unmarried, 2 - Married, 3 - Divorced
15
tstr
Guardian
Name/id of the entity playing the role of a guardian, such as a mother, father, spouse, sister, legal guardian etc.
16
tstr
Binary Image
Binary image of the person's photograph
17
int
Binary Image Format
Binary image format. Can contain the following values 1 - JPEG, 2 - JPEG2, 3 - AVIF, 4 - WEBP
18
[int]
Best Quality Fingers
An unsigned 8-bit number encoding the hand position of the finger. It must be in the range 0-10, where 0 represents "Unknown", 1-5 represents right thumb to little finger, and 6-10 represents left thumb to little finger in sequence
19
tstr
Full Name
Secondary Language Identity Full Name
20
tstr
Language
Secondary Language Code. Language used in other attributes: Use the three-letter ISO 639-3 language code
21
tstr
Location Code
Geo Location/Code
22
tstr
Legal Status
Legal Status of the identity
23
tstr
Country of Issuance
Country of Issuance
24.. 49
Unassigned
For future - For Demographic Data attributes
50
[Biometrics]
Right Thumb
Person's Right Thumb biometrics
51
[Biometrics]
Right Pointer Finger
Person's Right Pointer Finger biometrics
52
[Biometrics]
Right Middle Finger
Person's Right Middle Finger biometrics
53
[Biometrics]
Right Ring Finger
Person's Right Ring Finger biometrics
54
[Biometrics]
Right Little Finger
Person's Right Little Finger biometrics
55
[Biometrics]
Left Thumb
Person's Left Thumb biometrics
56
[Biometrics]
Left Pointer Finger
Person's Left Pointer Finger biometrics
57
[Biometrics]
Left Middle Finger
Person's Left Middle Finger biometrics
58
[Biometrics]
Left Ring Finger
Person's Left Ring Finger biometrics
59
[Biometrics]
Left Little Finger
Person's Left Little Finger biometrics
60
[Biometrics]
Right Iris
Person's Right Iris biometrics
61
[Biometrics]
Left Iris
Person's Left Iris biometrics
62
[Biometrics]
Face
Person's Face biometrics
63
[Biometrics]
Right Palm Print
Person's Right Palm Print biometrics
64
[Biometrics]
Left Palm Print
Person's Left Palm Print biometrics
65
[Biometrics]
Voice
Person's Voice biometrics
66.. 74
Unassigned
For future - For Biometrics Data attributes
75.. 99
Unassigned
For future - For any other data
Biometrics
0
bstr
Data
Biometrics binary data
1
int
Data format
Optional biometrics data format
2
int
Data sub format
Optional biometrics data sub format
3
tstr
Data issuer
Optional biometric data issuer
Data formats
0
Image
1
Template
2
Sound
3
Bio hash
Data sub formats
Image
0
PNG
1
JPEG
2
JPEG2000
3
AVIF
4
WEBP
5
TIFF
6
WSQ
100..200
Vendor specific
Template
0
Fingerprint Template ANSI 378
1
Fingerprint Template ISO 19794-2
2
Fingerprint Template NIST
100..200
Vendor specific
Sound
0
WAV
1
MP3
Note on Standard CWT Attributes
The attributes listed below are already included as part of the standard CWT (CBOR Web Token) metadata in the payload and therefore do not need to be separately specified within Claim 169. Implementers should refer to the standard CWT definitions for format and usage.
These fields are inherently part of the CWT structure and must be interpreted according to the standard specification. For details, refer to the IANA CWT registry here.
Included Attributes:
1
tstr
Issuer (iss)
Identifier of the entity issuing the credential
2
tstr
Subject (sub)
Identifier of the subject of the credential
4
int
Expiration Time (exp)
Timestamp indicating when the credential expires
5
int
Not Before (nbf)
Timestamp before which the credential must not be accepted
6
int
Issued At (iat)
Timestamp indicating when the credential was issued
Note on Status of Credential
The status of the credential, when represented using CWT, is outside the scope of the Claim 169 CBOR structure. This specification does not define or constrain how credential status should be encoded or managed within a CWT. Issuers may determine the status handling mechanism independently, using the IETF-recommended CWT conventions, or any other standards-compliant method appropriate for their ecosystem. No specific guidance or constraints on CWT handling are prescribed by this specification.
3.2 CBOR Map Structure Example
3.2.1 Steps for Claim 169 Compliant QR Code Generation
Prepare Identity Data: Start with the sample JSON identity data provided for conversion into Claim 169 format.
Convert to Claim 169 Format
Transform the JSON data into the required Claim 169 structure.
Refer to the sample converted data for guidance.
Generate CWT Data
Use the Claim 169–formatted data to create the CBOR Web Token (CWT) for QR code generation.
Compress the CWT
Apply
zlibcompression to the generated CWT data.
Encode to Base45 and Generate QR Code
Encode the compressed CWT using Base45.
Use this encoded string to generate the final QR code.
4. Security Considerations
The current MAP structure is in plain text and is equivalent to having a physical card with printed details. Additionally, the QR code is digitally signed, providing trust and preventing tampering or the insertion of fake information. Please ensure that you do not include any data elements that are not permissible under your country’s legal and regulatory requirements.
CWT MUST be signed, create a COSE_Sign/COSE_Sign1 object using the Message as the COSE_Sign/COSE_Sign1 Payload; all steps specified in RFC8152 for creating a COSE_Sign/COSE_Sign1 object MUST be followed.
If the CWT is a COSE_Encrypt/COSE_Encrypt0 object,create a COSE_Encrypt/COSE_Encrypt0 using the Message as the plaintext for the COSE_Encrypt/COSE_Encrypt0 object; all steps specified in RFC8152 for creating a COSE_Encrypt/COSE_Encrypt0 object MUST be followed.
It is recommended that sensitive information, such as biometrics, be encrypted.
If you choose to encrypt the payload, please ensure that key sharing for decryption is handled separately, outside the scope of this specification. There are multiple key-sharing mechanisms that can be followed, and the choice remains to be outside of this specification. As an example, you could potentially follow the approach of the TOTP mobile authenticators.
A cached key may be used to enable offline encrypted QR code reading, where applicable.
To verify the claims the CWT is a COSE_Sign/COSE_Sign1. Follow the steps specified in Section 4 of RFC8152 ("Signing Objects") for validating a COSE_Sign/COSE_Sign1 object. Let the Message be the COSE_Sign/COSE_Sign1 payload. Once signature is valid we SHOULD validate the public key against a preconfigured key, in case encrypted. Else, if the CWT is a COSE_Encrypt/COSE_Encrypt0 object, follow the steps specified in Section 5 of [RFC8152] ("Encryption Objects") for validating a COSE_Encrypt/COSE_Encrypt0 object. Let the Message be the resulting plaintext.
The security of the CWT relies upon on the protections offered by COSE. Unless the claims in a CWT are protected, an adversary can modify, add, or remove claims.
Since the claims conveyed in a CWT are used to make identity claim decisions, it is not only important to protect the CWT but also to ensure that the recipient can authenticate the party that assembled the claims and created the CWT. Without trust of the recipient in the party that created the CWT, no sensible identity verification can be made. Furthermore, the creator of the CWT needs to carefully evaluate each claim value prior to including it in the CWT, so that the recipient can be assured of the validity of the information provided.
Syntactically, the signing and encryption operations for Nested CWTs may be applied in any order; however, if encryption is necessary, producers normally should sign the message and then encrypt the result (thus encrypting the signature). This prevents attacks in which the signature is stripped, leaving just an encrypted message, as well as providing privacy for the signer. Furthermore, signatures over encrypted text are not considered valid in many jurisdictions.
5. IANA Considerations:
5.1 Registry Content
Claim Name: identity-data Claim Description: Registering the claim for storing identity data of a person, which could be Personally Identifiable Data (PII) mostly used in Foundational/National ID for cross-border interoperability. Claim Key: 169 Claim Value Type(s): map Change Controller: MOSIP Specification Document(s): Section 3, Section 4
6. Acknowledgments
This work is the result of the dedicated efforts of contributors who recognize the critical importance of interoperability and a consistent QR code specification. The revised version has been shaped significantly by the input of our working group committee, comprising members from the following organizations: GetGroup, PWC, Tech 5, UNHCR, Ooru, GIZ.
We extend our gratitude to the committee members for their invaluable time and insights throughout the evaluation phase.
6.1 Working Group Committee Members:
GetGroup: Aiman Tarek PWC: Chaitanya Giri Tech 5: Bejoy Ak, Nelson Branco, Rahul Parthe UNHCR: Norbert Trosien, Samantha Eisenhauer, Sam Jefferies Ooru: Rounak Nayak, Priyank Trivdei GIZ: Anita Mittal, Aisha Merhebi MOSIP: Harini Sampathkumar, Janardhan BS, Mahammed Taheer, Mayura Deshmukh, Pragya Kumari, Preeti Hongal, Ramesh Narayanan, Reeba Thomas, Resham Chugani, Sanchi Singh, Sasikumar Ganesan, Sivanand Lanka, Sreenadh S, Swati Goel, Varaniya Selvaraja, Vishwanath V
7. Authors
Mahammed Taheer ([email protected])
Resham Chugani ([email protected])
Rounak Nayak ([email protected])
Sasikumar G ([email protected])
Sreenadh S ([email protected])
8. What Changed
Addition of new attributes (19–23)
#19: Full Name
#20: Language
#21: Location Code
#22: Legal Status
#23: Country of Issuance
Refer to the table above for details.
Inclusion of/updates to the following sections:
Last updated
Was this helpful?