FAQ about shc-extractor

[obrassard]

How are SHC codes generated ?

The encoding of the QR code's data is relatively simple, it is a compressed JSON file. JSON is a file format commonly used in all kinds of apps which allows to represent data structures in the form of keys and values. The structure of the information in the JSON is standardized by the SHC protocol but in the end it is up to the person who creates the QR code (the issuer) to decide what information they include in the file. Then, the most important point of the process is that the json file is signed with a certificate or a cryptographic key that only the issuer knows. In a nutshell, several mathematical operations are performed with this secret key and the contents of the file to generate a unique digital signature. This allows anyone to verify that the QR code data has not been altered since it was issued, because if the content of the JSON file is altered the expected signature would become different. Once generated, the signature and the file are then zipped with a compression algorithm (to reduce the file size) and the QR code is generated with this compressed data.

How are SHC codes verified ?

To validate a QR code one must essentially do the opposite operations. First we read the QR code to get the compressed version of the data, then with a decompression algorithm we recover the JSON data and the signature. At this step we can verify the trustworthiness of the code. With the public key of the issuer (accessible to everyone) and the data contained in the QR code, it is possible to verify that the current signature fits with the original data encoded by the issuer.

The public key can verify the signature but it cannot generate a new signature with the data. Thus if the signature is valid, then we can assert that the data in the code has not been altered and we can trust the immunization information.

In other words, it would be difficult for someone to create a fake proof of vaccination with this system. If a counterfeiter tries to create a fake code using the same data structure and they don't have the issuer's secret key (which must match the public key used for validation), the code will be detected as invalid.

Can I create a custom SHC code from a JSON file ?

Short answer : Yes, but it probably won't validate.

Long answer :

The Smart Health Card technology prevent alteration by a third party on an existing QR code. The data contained in the code’s payload is signed with a cryptographic signature. Therefore, if any of the data changes, the digital signature won’t match anymore with the original QR code and the altered code will be rejected upon validation.

To resume, the content of the original QR code is signed (with a private key only the original issuer knows) this allows the issuer to generate what we could call a unique digital fingerprint. Later, we can verify that the fingerprint is valid using the issuer public key. Thus, if someone changes the information contained inside the QR code the signature won't match anymore and that's why the code will be rejected.

TLDR it's not possible to change the information contained in a SHC QR code and keeping it valid (while keeping the original issuer) unless you knew the private key of this issuer, which of course you don't.

What information is contained in my QR code ?

As explained above, the code's issuer is the one who decide what data is contained in the QR codes they emit. Therefore it could depend of the province, country or state you live in.

In Canada 🇨🇦 the following data is contained in the QR codes: first and last name, date of birth, gender, and some details on the doses of vaccines received (type of vaccine, date and location).

Why is my code validated in shc-extractor, but rejected in other SHC validator apps.

The main purpose of shc-extractor is to allow anyone to knows what information is contained in their QR code.shc-extractor do not verify the trustworthiness of issuers while other apps are likely to reject issuers that aren't trustable.

More about that : As briefly explained before, it is possible for someone to create a valid QR code with a custom signature if the "issuer" is a custom domain they control and a new private key is generated. However when a government or state will try to validate the code they are likely to check if the issuer is trusted, then if the signature matches this issuer's public key.

Unlike other apps,shc-extractor do not make this verification and will show a code as valid, as long as the signature matches with the issuers public key (regardless of the issuer).

Where can I find more information about SHC and QR code encoding ?

• Jupyter Notebooks demonstrating the creation of SMART Health Cards in different programming languages: https://github.com/dvci/health-cards-walkthrough

• The official SMART Health Cards specifications: https://spec.smarthealth.cards/