1secvarctl(1) General Commands Manual secvarctl(1)
2
6 secvarctl - A command line tool for simplifying the reading and writing
7 of secure boot variables.
8 Commands are:
10 read - read from the secure variable directory and print out in‐
11 formation on their current contents
12 write - update the given variable's key value
15 validate - checks that the format and basic content requirements
17 are met for the given file type
18 verify - checks that the given files are correctly signed by the
20 current variables
21 generate - generates several different types of file formats
23 relevant to updating secure variables
24
27 secvarctl [OPTIONS]
28 secvarctl read [OPTIONS] <variable>
30 secvarctl write [OPTIONS] <variable> <file>
33 secvarctl validate [OPTIONS] <file type> <file>
35 secvarctl verify [OPTIONS] -u {Update Variables}
37 secvarctl generate <inputFormat>:<outputFormat> [OPTIONS] -i <input‐
39 File> -o <outputFile>
40 secvarctl generate reset [OPTIONS] -o <outputFile> -k <key> -c <crt> -n
42 <variable>
43
46 secvarctl is a suite of tools to manipulate secure boot keys on POWER.
47 The purpose of this tool is to simplify and automate the process of
48 reading, writing and generating secure boot keys. It allows the user to
49 communicate, via terminal commands, with the keys efficiently. These
50 commands are ( read , write , validate , verify , generate )
51 secvarctl read will read from the secure variable directory and
53 print out information on their current contents. By default, the
54 program assumes the data is an EFI Signature List and prints the
55 contents in human readable form.
56 To print the raw data, use -r
57 The default secure variable directiory is /sys/firmware/sec‐
58 var/vars/ defined in secvarctl.h
59 To specify a path to the variables, use -p <newPath>.Expected
60 variable subdirectory names :{"PK", "KEK", "db", "dbx", "TS"}
61 with contained data file "<varName>/data".
62 If no variable name is given, the program will try to print the
63 data for any variable named one of the following
64 {'PK','KEK','db','dbx', 'TS'} NOTE 'TS' variable is not an
65 ESL, it is 4 timestamps (64 bytes total) for each of the other
66 variables Type one of the variable names to get info on that
67 key, NOTE does not work when -f option is present
68 To read the data of any esl file use -f <eslFileName>
69 secvarctl write will update the given variable's key value.
71 The new key value is expected to be contained in a
72 PKCS7/Signed Data Authenticated file signed with the current
73 key.
74 By default, the write function will validate the contents of
75 the auth file. If it is a success the file will be written to
76 the variables "update" file.
77 The "update" file is expected to be in "<pathToVars>/<vari‐
78 able>/update".
79 The -p <pathToVars> option is the location of the subdirecto‐
80 ries {"PK","KEK", "db", "dbx"} which contain an "update" file,
81 the default path is /sys/firmware/secvar/vars/ defined in sec‐
82 varctl.h
83 The -v option prints process info
84 The -f option skips the validation step and immediadetly
85 writes content of "<file>" to "<variable/upate"
86 The <variable> requirement is expected to be one of the fol‐
87 lowing {"PK","KEK", "db", "dbx"}
88 secvarctl validate will determine if the format and basic con‐
90 tent requirements are met for the given file
91 The default type of "<file>" is an auth file containing a
92 PKCS7/Signed Data and attatched esl.
93 ALL KEYS ARE EXPECTED TO BE SHA-256 and RSA 2048
94 THIS FUNCTION DOES NOT DO ANY COMPARISON AGAINST CURRENT KEYS
95 (use verify for that)
96 For extra process and file content information use -v for
97 verbose
98 To validate a file that contains update data for the dbx
99 variable use -x
100 To validate a PKCS7 (expected DER), use -p <file>
101 To validate an Efi Signature List (ESL), use -e <file>
102 To validate a certificate (x509 in DER or PEM format), use
103 -c <file>
104 secvarctl verify will determine if the update files are cor‐
106 rectly signed by the current variables or not.
107 The -v command will give extra information on process informa‐
108 tion.
109 All given update files are expected to be a signed PKCS7/Signed
110 Data authenticated file containing an attatched new ESL.
111 The updates should be signed according to the correct hierarchy
112 rules:
113 --PK can sign all other keys, (including itself),
114 --KEK can sign db and dbx, cannot sign PK
115 --db/dbx cannot sign KEK or PK
116 --TS holds no power of the variables, only functions to
117 hold the timestamps of the last update for each of the
118 other variables. Cannot be manually updated
119 All updates have their format validated before any verification
120 is done.
121 The -p <pathToVars> option is used to set the location of cur‐
122 rent variables with subdirectories {"PK","KEK", "db", "dbx",
123 "TS"} which contain the {"update, "data", "size"} files, the de‐
124 fault path is /sys/firmware/secvar/vars/ defined in secvarctl.h
125 The -c {Current Variables} option is used to specify the cur‐
126 rent variables manually. See OPTIONS for correct format of {Cur‐
127 rent variables}.
128 If the -w option is given then, if the verification passes, the
129 updates will be commited to the "update" file of the given vari‐
130 able
131 secvarctl generate will use the given input file to generate the
133 output file of the given file format type.
134 The -v option will give more process information.
135 To specify the desired input and output format the user must
136 use the argument <inputFormat>:<outputFormat> with no spaces be‐
137 tween the colon and the format types. The accepted values for
138 <inputFormat> are:
139 [h]ash , A file containing only hashed data, use -h
140 <hashAlg> to specifify the hash function used (default
141 SHA256)
142 [c]ert , An x509 certificate (PEM), RSA2048 and SHA256
143 ONLY
144 [e]sl , An EFI Signature List
145 [p]kcs7 , a PKCS7 file containing signed data
146 [a]uth , A signed authensticated file containing a PKCS7
147 and the new data
148 [f]ile , Any file type, Warning: no format validation
149 will be done
150 The accepted values for <outputFormat> are:
151 [h]ash , A file containing only hashed data, use -h
152 <hashAlg> to specifify the hash function used (default
153 SHA256)
154 [e]sl , An EFI Signature List
155 [p]kcs7 , a PKCS7 file containing signed data, must
156 specify public and private keys and digest algorithm (de‐
157 fault SHA256)
158 [a]uth , A signed authenticated file containing a PKCS7
159 and the new data, must specify public and private keys,
160 digest algorithm (default SHA256) and secure variable
161 name
162 [x] A presigned digest file containing only the hash of
163 the new data in ESL format with extra metadata. This for‐
164 mat need only be used when the user does not have access
165 to private keys for signing and must send the digest to
166 be signed through an external framework.
167 All input formats besides [f]ile will be prevalidated. To skip
168 prevalidation of the input file, use -f to force to generation.
169 If [h]ash is input or output type be sure to specify the hashing
170 algorithm to use by using the argument -h <hashAlg>. This argu‐
171 ment does not effect the digest algortithm of the signed data in
172 a [p]kcs7 or [a]uth file, these will always use SHA256.
173 Accepted values for <hashAlg> are one of {'SHA256', 'SHA224',
174 'SHA1', 'SHA384', 'SHA512'}
175 Additionally, when the output type is [p]kcs7 or [a]uth, the
176 user must give at least one pair of public and private keys -c
177 <cert> -k <privKey> to sign the input file with. However, if the
178 user does not have access to their private keys and are only
179 able to interact with a signing framework, they can use -s <sig‐
180 File> in replacement of the private key argument. <sigFile>
181 would contain only the raw signed data of a digest generated
182 with `secvarctl generate c:x`, it is important that both these
183 commands use the same custom timestamp argument -t <YYYY-MM-
184 DDThh:mm:ss>.
185 When generating an [a]uth file, it is required the user give
186 the secure variable name that the auth file is for, -n <varName>
187 , where <varName> is one of {"PK","KEK", "db", "dbx"}. This ar‐
188 gument is also useful when the input file is an ESL for the dbx
189 (use -n dbx) because then the prevalidation will look for an ESL
190 containing a hash rather than an x509.
191 Also, when the output type is a [p]kcs7 or [a]uth file, the
192 user can use a custom timestamp with -t <time> , where <time> is
193 in the format 'YYYY-MM-DDThh:mm:ss'. If this argument is not
194 used then the current date and time are used.
195 When using the input type '[f]ile' it will be assumed to be a
196 text file and if output file is '[e]sl', '[p]kcs7' or '[a]uth'
197 it will be hashed according to <hashAlg> (default SHA256).
198 To make a variable reset file, the user can replace generate
199 <inputFormat>:<outputFormat> with generate reset This will gen‐
200 erate an auth file around an empty ESL. Thus, no input argument
201 -i is required when making a reset file.
202 NOTE: GENERATION OF PKCS7 AND AUTH FILES ARE IN EXPERIMENTAL
203 DEVELEPOMENT PHASE. THEY HAVE NOT BEEN THOROUGHLY TESTED YET.
204
208 For secvarctl [OPTIONS]:
209 --usage
210 --help
212 For secvarctl read [OPTIONS] <variable>:
214 --usage
215 --help
217 -r , raw output
219 -f <input.esl> , read from file
221 -p </path/to/vars/> , read from path (subdirectories {"PK",
223 "KEK, "db", "dbx", "TS"} each with files {"data", "size"} ex‐
224 pected)
225 <variable> , one of {"PK", "KEK, "db", "dbx", "TS"}
227 For secvarctl write [OPTIONS] <variable> <file>:
230 REQUIRED:
231 <variable> , one of {"PK", "KEK, "db", "dbx"}
232 <file> , an auth file
234 OPTIONS:
235 --usage
236 --help
238 -v , verbose output
240 -f , force update, no validation
242 -p </path/to/vars/> , write to file in path (subdirecto‐
244 ries {"PK", "KEK, "db", "dbx"} each with "update" file
245 expected)
246 For secvarctl validate [OPTIONS] <file type> <file>:
248 REQUIRED:
249 <file> , the input file, assumed to be auth file if not
250 specified
251 OPTIONS:
252 --usage
253 --help
255 -v , verbose output
257 -x , dbx file (contains hash not x509)
259 -e <file> , ESL
261 -p <file> , PKCS7/Signed Data
263 -c <file> , DER or PEM certificate
265 -a <file>, DEFAULT, a signed authenticated file containg
267 a pkcs7 and appended ESL
268 For secvarctl verify [OPTIONS] -u {Update Variables}:
270 REQUIRED:
271 -u {Update Variables} , the updates to be run
272 OPTIONAL:
273 --usage
274 --help
276 -v , verbose output
278 -p </path/to/vars/>, read from path (subdirectories
280 {"PK", "KEK, "db", "dbx", "TS"} each with files {"data",
281 "size"} expected)
282 -w , write updates if verified
284 -c {Current Variables} , list of current variables
286 {Update Variables}:
288 Format: <varname_1> <file_1> <varname_2> <file_2> ...
289 Where <varname> is one of {"PK", "KEK, "db", "dbx"} and
290 <file> is an auth file
291 Note: Updates are verified in the order they are submit‐
292 ted
293 {Current Variables}:
294 Format: <varname_1> <file_1> <varname_2> <file_2> ...
295 Where <varname> is one of {"PK", "KEK, "db", "dbx", "TS"}
296 and <file> is an esl file (unless TS)
297 For secvarctl generate <inputFormat>:<outputFormat> [OPTIONS] -i <in‐
299 putFile> -o <outputFile> :
300 REQUIRED:
301 <inputFormat>:<outputFormat> , {'[c]ert', '[h]ash',
302 '[e]sl', '[p]kcs7', '[a]uth', '[f]ile'}:{ '[h]ash',
303 '[e]sl', '[p]kcs7', '[a]uth', '[x] presigned digest'} SEE
304 DESCRIPTION FOR HELP
305 -i <inputFile> , input file that has the format specified
307 by <inputFormat>
308 -o <outputFile> , output file that will have the format
310 specified by <outputFormat>
311 OPTIONAL:
312 --usage
313 --help
315 -v , verbose output
317 -f , force generation, skips validation of input file and
319 assumes it to be formatted according to <inputFormat>
320 -n <varName> , name of secure boot variable, used when
322 generating an auth file, PKCS7, or when the input file
323 contains hashed data rather than x509 (use '-n dbx'),
324 current <varName> are: {'PK','KEK','db','dbx'}
325 -t <time> , where <time> is of the format described be‐
327 low. creates a custom timestamp used when generating an
328 auth or PKCS7 file, if not given then current time is
329 used, all times are in UTC
330 format of <time> = 'YYYY-MM-DDThh:mm:ss' where:
331 - 'YYYY' four-digit year
332 - 'MM' two-digit month (01=January, etc.)
333 - 'DD' two-digit day of month (01 through
334 31)
335 - 'T' appears literally
336 - 'hh' two digits of hour (00 through 23)
337 (am/pm NOT allowed)
338 - 'mm' two digits of minute (00 through
339 59)
340 - 'ss' two digits of second (00 through
341 59)
342 -h <hashAlg> , hash function, used when output or input
344 format is hash, current values for <hashAlg> are :
345 {'SHA256', 'SHA224', 'SHA1', 'SHA384', 'SHA512'}
346 -k <privKey> , private key, used when generating pkcs7 or
348 auth file
349 -s <sigFile> , signed data file, alternative to internal
351 signing, replacement of private key argument
352 -c <certFile> , x509 certificate (PEM), used when gener‐
354 ating pkcs7 or auth file
355 reset , replaces <inputFormat>:<outputFormat> and gener‐
357 ates an auth file with an empty ESL (a valid variable re‐
358 set file), no input file required. Required arguments are
359 output file, signer public and private key and variable
360 name.
361
363 To read all current variables in default path:
364 $secvarctl read
365 To read the raw data of the PK in a specific location:
367 $secvarctl read -p /home/user1/myVars/ -r PK
368 To validate and write an auth file to the default KEK location:
370 $secvarctl write KEK updateFile.auth
371 To write to /home/user1/myVars/KEK/update with no formatting checks:
373 $secvarctl write -p /home/user1/ -f KEK updateFile.auth
374 To validate the format of an auth file:
376 $secvarctl validate authFile.auth
377 To validate the format of a ESL with extra process info:
379 $secvarctl validate -e eslFile.esl -v
380 To verify the desired updates against the default path and, if success‐
382 ful, commit the updates:
383 $secvarctl verify -w -u db dbUpdate.auth KEK kekUpdate.auth
384 To verify the desired updates against a specific set of signers with
386 extra process info:
387 $secvarctl verify -v -c PK myPK.esl KEK myKEK.esl dbx my‐
388 DBX.esl -u DB dbUpdate.auth PK pkUpdate.auth
389 To get the attatched ESL from an auth file:
391 $secvarctl generate a:e -i file.auth -o file.esl
392 To create an ESL from an x509 certificate:
394 $secvarctl generate c:e -i file.pem -o file.esl
395 To create SHA512 from a file:
397 $secvarctl generate f:h -h SHA512 -i file.txt -o file.hash
398 To create ESL from a hash:
400 $secvarctl generate h:e -h 512 -i file.has -o file.esl
401 To create an auth file from the esl containg a hash for a dbx update:
403 $secvarctl generate e:a -k signer.key -c signer.crt -n dbx -i
404 file.esl -o file.auth
405 To create an auth file from a certificate for a KEK update (this will
407 create an ESL from the certificate and use the ESL for the Auth File):
408 $secvarctl generate c:a -k signer.key -c signer.crt -n KEK -i
409 file.crt -o file.auth
410 To create a PKCS7 file from an ESL for a db update with a custom time‐
412 stamp:
413 $secvarctl generate e:p -k signer.key -c signer.crt -n db -t
414 2020-10-1T13:45:42 -i file.crt -o file.pkcs7
415 To create an empty update to reset the db variable:
417 $secvarctl generate reset -k signer.key -c signer.crt -n db -o
418 db.auth
419 To create an auth file using an external signing framework for db up‐
421 date:
422 $secvarctl generate c:x -n db -t 2021-1-1T1:1:1 -i file.crt -o
423 file.hash
424 <user sends file.hash to be signed by external entity, signature
425 is now in file.sig>
426 $secvarctl generate c:a -n db -t 2021-1-1T1:1:1 -c signer.crt -s
427 file.sig -i file.crt -o file.auth
428
431 Nick Child nick.child@ibm.com,
432 Eric Richter,
434 Nayna Jain
436version 0.1 1 OCTOBER 2020 secvarctl(1)