An overview of CVRDecode

CVRDecode (or cvrdecode) is a small utility that reads multiple California digital vaccine records, provided as image files, shc URIs, or files, ending in the file-name extension ".shc" that contain shc URIs. These records are then printed using a CSV (Comma Separated Values) format, with only selected portions of the records shown. This list is sorted by name and date of birth. CSV data can be readily imported by spreadsheets. Please see the installer web page for installation instructions.

CVRDecode can be run in four ways:

• as a desktop application. The procedure for starting a desktop application is window-system dependent. This is automatically supported when CVRDecode is installed by a package manager (e.g., apt, synaptic, etc.) or by flatpak. It may be supported when CVRDecode is installed by running the installer, provided some additional configuration is performed manually.
• as a program started from the command line by running the command

  
    cvrdecode
  	

  possibly with command-line arguments This is supported when CVRDecode is installed by a package manager (e.g., apt, synaptic, etc.) or by running the installer application.
• as a flatpak program started from the command line by running the command

  
    flatpak run org.bzdev.CVRDecode
  	

  possibly with command-line arguments. This is supported when flatpak was used to install CVRDecode.
• as a web server running in a Docker container.

When run from the command line, the CSV data will be written to standard output (with the exception of the -u and -v options described below). When run as a desktop application, the CSV data will be written to a file.

1.0 Command-line Options

The command-line options are

• --: end of options.
• -i: there can be at most one remaining argument. If there is no additional argument or the additional argument is -, a series of shc URIs, one per line, is read from the standard input. If there is an additional argument other than -, it must be the file name for a file containing shc URIs, one per line. The output will be in CSV (Comma Separated Values) format, with a header followed by a description of each record, one record per line. The records will be sorted by family name, given names, and date of birth.
• -u: the remaining arguments must be file names or URIs that start with shc:/ The URIs will be extracted from the inputs by either decoding a QR code, reading a URI contained in a file as text, or accepting the URI passed literally as an argument. Each URI will be printed, one per line, on standard output.
• -v: the remaining argument, if present, must be either a file name for an image file, the character - (denoting standard input), or a URI that start with shc:/. If there are no remaining arguments, standard input is used. The URI will be either extracted from a QR code, copied from the content of the input or obtained from the literal value of an argument. The URI will then be decoded, and its contents pretty-printed. A final line indicates if the signature was valid or not. The output will be written to standard output.
• -z: there may be at most one additional argument: a file name, which may be either the name of a file or -, which denotes standard input. If there are no additional arguments, standard input is read. The input must be a ZIP file. The files contained in the ZIP file will be processed to generate a sorted CSV file as described above.
• -h, -?, or --help: a copy of the manual page will be displayed. This option is provided for flatpak alone: what is displayed is the manual page.

If there are no command-line arguments, a GUI will start. If there no options, the command-line arguments should be image files or text files containing SHC URIs with file names ending in the suffix ".shc".

2.0 Use as a desktop application

Linux distributions typically come with window managers that can display the installed desktop applications, so that a user can click on an icon to start a program. The following is one example - the upper right icon in the following illustration will start CVRDecode.

When started as a desktop application, CVRDecode displays a window with several buttons:

The first two buttons determine the input and output. The first button sets the input directory (or ZIP file) and the second sets the output file for CSV data. Once the corresponding file or directory is set, the button changes its background color to a pale yellow. Once the input and output are set, the Run button becomes active, and clicking it will generate the CSV file. Two additional buttons let one view the table immediately and check for any error messages. The final button, named Exit, terminates the program. The table is mostly self explanatory, with two exceptions:

• the column indicating if an individual is fully vaccinated is a boolean value and when true, the boolean value is followed by a number in parentheses. That number indicates the number of vaccine doses received and is present when booster vaccinations were given.
• the last column, which provides an indication of the file containing the vaccine record, may be prefaced with a number in square brackets that is basically a footnote. When these exist, a short table at the end gives the host name for whatever organization provided the public key used to verify a record. The user should check this domain name to verify that it belongs to a trusted organization.

3.0 Privacy

If the records, whether as images or as files containing shc URIs, are stored in a GPG-encrypted file, the command

  gpg -d ENCRYPTED_FILE | cvrdecode -z > table.csv
    

4.0 Docker

CVRDecode is available as a Docker image. The Docker image provides a web server that will except a ZIP file containing California digital vaccine records as an input and that will produce a table as its output. To start it, use the command

  docker run --publish 80:80 --detach --name cvrdecode wtzbzdev/cvrdecode:1.0
    

The server is configured using 5 environment variables, three of which can by set with the --env option provided by docker run:

• BACKLOG=M where M is a positive integer providing the TCP backlog. The default is 30.
• NTHREADS=M where M is a positive integer indicating the number of threads the server may use. The default is 50.
• TRACE=TRUE turns on tracing (which is off by default).
• IPADDR=ADDR sets the server's IP address. Well-known values are wildcard and loopback. The default is wildcard and should not be changed unless a new Dockerfile is created.
• PORT=PORT. This sets the server's TCP port to PORT. The default is 80 and should not be changed unless the Dockerfile is modified.

The variables BACKLOG, NTHREAD, and TRACE can be set using the docker run option --env. Changing the others using the --env option may prevent the web server from being visible outside of its container.

To stop the server, run the commands

  docker stop cvrdecode
  docker rm cvrdecode
    

4.1 Using the server

  http://localhost/
    

When this URL is visited by a browser, a simple web page will be shown. This page contains an HTML form with two controls. One control allows the user to specify a ZIP file containing images of California digital vaccine records and/or text files with the suffix ".shc", each containing a Smart Health Card URI. . When the button labeled Download Table is pushed, the server will upload the ZIP file and return a CSV file that the user can save or open with a suitable application such as a spreadsheet.

4.2 Deploying the server

The commands provided above are sufficient for using the docker image locally or on a private network. For public use, one should treat the server as an application server and configure a publicly visible web server as a reverse proxy using HTTPS. For large scale use, one may want to use Docker Swarm or Kubenetes in order to add CVRDecode servers as needed. The CVRDecode server is stateless.

5.0 Use Cases

CVRDecode was written based on a use case generated from personal experience. During the summer of 2021, people were hosting private events, typically outdoors, with a requirement that everyone attending was vaccinated. You could provide a vaccination record upon arrival, but you could also email a photo of a vaccination record in advance. a volunteer would then check a list (a paper copy as who was helping with what was often not known in advance). Manually copying records for 50 or so people is time consuming. CVRDecode was written to help automate the process.

For an event run by a business or organization, it is easy to provide an appropriate device for scanning the QR codes. When the person checking the records is chosen at the last moment, however, that person might not want to load additional software onto his or her smart phone or drain the phone's battery. In this case, a "low tech" solution is a good choice.

CVRDecode can also be used with the -v option so that user's can determine if their California digital vaccine record is correct - it will display all the information encoded by the QRCode (although the actual reason for this option was as an aid for software development).