Data Format

Overview

Your data is stored in QR Codes in a custom format developed keeping security and optimization of space usage in mind. Somewhat like network protocols, the data format has two layers: Transport and Message. The Message layer is the top level one, and defines how a document is encoded in a usually compressed and encrypted data buffer. The Transport layer defines the lower level, specifically the data stores in each individual QR Code, which includes a segment of the Message data buffer (or the entire message, if it fits a single QR Code) plus additional information to guide the scanning process.

All numeric data types are stored in network byte order. In every table, consider n to be the number of bytes in the relevant buffer for that table.

Message

The message format is the following. Consider n to be the total number of bytes.

Offset (bytes)	Length (bytes)	Description
0	1	Clear-text flags (UInt8)
1	n-1	Encrypted payload

The clear-text flags is a byte reserved for flags that are needed before decrypting the content (like specifying the encryption type). For now, they are not used and the value of the byte should be zero. It's implicit all the data after the initial byte is the encrypted payload. Do the following:

1. Verify is the clear-text flags byte is zero. If not, fail, as the data is either corrupt or generated by a newer version of the app (and this documentation may be outdated).

The encrypted payload has the following format:

Offset (bytes)	Length (bytes)	Description
0	4	Key derivation rounds (UInt32)
4	2	Salt size in bytes (UInt16)
6	Salt size	Salt
6 + salt size	Until the end of the buffer	Encrypted data

To obtain the unencrypted data, do the following:

1. Derive the encryption key from the user provided password using code like the following:

   let err = CCKeyDerivationPBKDF(
       CCPBKDFAlgorithm(kCCPBKDF2),
       passwordPtr, strlen(passwordPtr),
       saltBuf.baseAddress!.assumingMemoryBound(to: UInt8.self),
       saltBuf.count,
       CCPseudoRandomAlgorithm(kCCPRFHmacAlgSHA256),
       rounds,
       &output, output.count)
   

2. Decrypt the encrypted data with the resulting key using the ChaCha20-Poly1305 algorithm. If decryption or authentication fails, either the password is wrong, or the data was tampered with.

After doing this, you end up with the padded document data:

Offset (bytes)	Length (bytes)	Description
0	variable	Serialized document data + flags
n - number of padding bytes - 1	Number of padding bytes	Random padding data
n - 1	1	Number of padding bytes (UInt8)

This looks confusing but it's fairly simple: the last byte is the number of padding bytes (excluding the byte used for the size). So, for example, if the last byte is 10, the useful data is the entire buffer after removing the last 11 bytes:

1. Let paddingSize be the value of the last byte.
2. Remove the last paddingSize + 1 bytes of the buffer.

You are now left with the serialized document data and control flags. Here's the structure:

Offset (bytes)	Length (bytes)	Description
0	1	Control flags (UInt8)
1	n - 1	Serialized document data (possibly compressed)

Currently, only the first bit is used, to indicate if compression was used or not. Do this:

1. If control flags is zero, the data is not compressed. Use the serialized document data as is and skip the next step. If control flags is 1, data is compressed using the brotli algorithm. If control flags is > 1, fail, as the data is either corrupt or generated by a newer version of the app (and this documentation may be outdated).
2. If control flags is 1 in the step above, decompress the serialized document data using the brotli algorithm.

You have now finally reached the clear-text, uncompressed, ready to use document data! Here's the structure:

Offset (bytes)	Length (bytes)	Description
0	2	Document title size in bytes (UInt16)
2	Document title size	Document title (UTF-8 data)
2 + Document title size	2	Document content type (UInt16)
4 + Document title size	Until the end of the buffer	Document content

At the time of this writing, the content type value must be zero, and represents text. More data types may be added in the future.

1. Obtain the document title size in bytes, grab the relevant part of the buffer and decode it as UTF-8 data. This is the document title.
2. Verify content type is zero. Otherwise, fail, as the data is either corrupt or generated by a newer version of the app (and this documentation may be outdated).
3. Grab the rest of the buffer and treat it as the document content, based on the document type. Since the only supported type for now is text, treat the buffer as UTF-8 data.