-
Notifications
You must be signed in to change notification settings - Fork 0
/
cvrdecode.1
186 lines (184 loc) · 8.12 KB
/
cvrdecode.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
.TH cvrdecode "1" "Aug 2021" "cvrdecode VERSION" "User Commands"
.SH NAME
cvrdecode \- extract data and verify a California digital vaccine record
.SH SYNOPSIS
.PP
.B
cvrdecode
[\fI\,OPTION\/\fR] [\fI\,FILENAME\/\fR|\fI\,URI\/\fR]...
.SH FLATPAK SYNOPSIS
.B flatpak run org.bzdev.CVRDecode --help\fR|\fB-?
.br
.B flatpak run org.bzdev.CVRDecode
[\fI\,OPTION\/\fR] [\fI\,FILENAME\/\fR|\fI\,URI\/\fR]...
.SH DESCRIPTION
.PP
The program cvrdecode, or its flatpak equivalent, prints out
information about a California digital vaccine record. The California
Department of Public Health is providing those vaccinated against
COVID-19 with a digital vaccination records consisting of a logo, some
text, and a QR code (Quick Response code). The printed text contains a
summary whereas the QR code contains the same data that is on the CDC
vaccination record one gets after a vaccination. This digital record
also contains a digital signature to show that the record is authentic
- that it was in fact obtained from the California Department of
Public Health. The program
.B cvrdecode
was written in part to handle a common use case: private events where
participants email vaccination records to whoever is hosting the event.
Those records are then used to generate a list that is checked as people
show up. A printout is typically used because the person checking
vaccination status is usually a volunteer and who is going to do what is
not known in advance. Automatically generating a sorted list from a
collection of records makes the process easier for the individual hosting
the event.
.PP
This program's arguments, aside from options, are the names of
files containing images of the QR code, files containing the URI the QR code
encodes as plain ASCII text, the URI itself, or the symbol
.B -
indicating that standard input should be read to obtain an image.
Files with the extension ".shc" are assumed to contain a single
line - an shc URI. Image files should have names that end in the
file-name extensions Java recognizes for image files (e.g., "png"
or "jpg", with the choice possibly system dependent).
.PP
The default output is in CSV (Comma Separated Values) format and
consists of one line for each file name or URI, with an initial line
labeling each column. CSV lines are sorted. Options can change the
format of the output and are described below. The CSV file can be
opened by programs such as LibreOffice: spreadsheets typically allow
CSV data to be imported.
.PP
If there are no command-line arguments, cvrdecode will be run as
a window-based application. It will display a window containing
buttons with the ones applicable enabled. The user must select an
input directory and an output file by clicking the buttons named
.B Set Input Directory
and
.B Set Output File
respectively. When a value is set, the button will change color to
a pale yellow. The input directory will contain
the vaccination records, either as text files with the "shc" extension
containing an
.B shc
URI in textual form, or as images containing QR codes. The output file
is the name of a CSV file. If the output file name does
not end in ".csv", that suffix will be appended to the file name.
When the "Run" button is pressed, the output will be generated. The
user will be able to view this table by pressing the "Show Table"
button. Similarly, to check for errors, one can press the "Show Console"
button. Finally the "Exit" button will close the window and exit.
A CSV-formatted output will be generated. Generally, a user is expected
to press the buttons in the order in which they appear, skipping ones
that are not applicable. Using the first two, which set the input and
output, is necessary as otherwise the "Run" option will not be enabled.
Once enabled, the use of the "Show Table" and "Show Console" buttons is
optional. The "Show Table" option just provides the data in the output
file in a readable form and the "Show Console" button merely opens a
console that contains any error messages generated by the software.
.PP
When the output indicates that an individual is fully vaccinated, that
basically means that the individual has received the number of
injections expected for the first vaccination in the record, and that
will be immediatedly followed by the number of vaccinations in
parentheses if booster vaccinations were given. The software does not
detect an inappropriate mix of vaccine types or vaccinations given at
the wrong time - the assumption is that these sort of errors would be
checked when the vaccine is provided. One has to check the last
vaccination date manually to verify that the required two weeks have
elapsed. Finally, when keys are downloaded at run time, a reference
number in square brackets will label the key. A series of records at
the end of the output will indicate the domain name corresponding to
each reference number. The user is expected to check this domain name
in order to verify that it is from a trusted source.
.SH OPTIONS
.PP
The options are
.TP
.B \-\-
End of options. This argument is necessary if the first non-option
argument if a file name that for some reason starts with "-". Otherwise
it is not needed.
.TP
.BR \-i \ [\fI\,FILE\/\fR]
There can be at most one remaining argument. If there is no additional
argument or the additional argument is
.BR \- ,
a series of
.B shc
URIs, one per line, is read from the standard input. If there is an
additional argument other than
.BR \- ,
it must be the file name for a file containing
.B 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.
.TP
.B \-u
The remaining arguments must be file names or URIs that start
with
.BR 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.
.TP
.BR \-v \ [\fI\,FILE\/\fR]
The remaining argument
.IR FILE .
if present, must be either a file name for an image file, the character
.B \-
(denoting standard input), or a URI that start
with
.BR 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. This data
will be sent to the standard output.
.TP
.BR \-z \ [\fI\,FILE\/\fR]
There may be at most one additional argument: a file name
.IR FILE ,
which may be either the name of a file or
.BR \- ,
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.
.SH FLATPAK OPTIONS
When run using
.BR flatpak ,
an additional option is available:
.TP
.BR \-\-help | \-h | \-?
The manual page is displayed. These three options are equivalent and
are provided to match various expectations of what options generate
"help" output.
.SH PRIVACY
If a web server is set up to collect California digital vaccine
records, the GPG public keys for users authorized to see these records
can be stored and the server can allow these users to download a
GPG-encrypted ZIP file containing the records. The following command
will print out the CSV file for these records without having any
stored in the file system:
.IP
.B gpg -d
.I ENCRYPTED_ZIPFILE
.B | cvrdecode \-z
.PP
GPG will ask for a passphrase to get access to the public key.
The CSV output does not contain particularly sensitive information:
just a full name with a birth date, the last vaccination date,
a true/false value indicating if a person is fully vaccinated, and
a true/false value indicating if the record was signed by the
California Department of Public Health. The vaccine type and
the location where the vaccine was provided are not shown when the
.B \-z
option is used.
\" LocalWords: cvrdecode fI fR URI COVID shc CSV TP URIs csv png fB
\" LocalWords: jpg GPG gpg ZIPFILE FLATPAK flatpak br