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
11 information 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
124 default path is /sys/firmware/secvar/vars/ defined in sec‐
125 varctl.h
126 The -c {Current Variables} option is used to specify the cur‐
127 rent variables manually. See OPTIONS for correct format of {Cur‐
128 rent variables}.
129 If the -w option is given then, if the verification passes, the
130 updates will be commited to the "update" file of the given vari‐
131 able
132 secvarctl generate will use the given input file to generate the
134 output file of the given file format type.
135 The -v option will give more process information.
136 To specify the desired input and output format the user must
137 use the argument <inputFormat>:<outputFormat> with no spaces
138 between the colon and the format types. The accepted values for
139 <inputFormat> are:
140 [h]ash , A file containing only hashed data, use -h
141 <hashAlg> to specifify the hash function used (default
142 SHA256)
143 [c]ert , An x509 certificate (PEM), RSA2048 and SHA256
144 ONLY
145 [e]sl , An EFI Signature List
146 [p]kcs7 , a PKCS7 file containing signed data
147 [a]uth , A signed authensticated file containing a PKCS7
148 and the new data
149 [f]ile , Any file type, Warning: no format validation
150 will be done
151 The accepted values for <outputFormat> are:
152 [h]ash , A file containing only hashed data, use -h
153 <hashAlg> to specifify the hash function used (default
154 SHA256)
155 [e]sl , An EFI Signature List
156 [p]kcs7 , a PKCS7 file containing signed data, must
157 specify public and private keys and digest algorithm
158 (default SHA256)
159 [a]uth , A signed authenticated file containing a PKCS7
160 and the new data, must specify public and private keys,
161 digest algorithm (default SHA256) and secure variable
162 name
163 [x] A presigned digest file containing only the hash of
164 the new data in ESL format with extra metadata. This for‐
165 mat need only be used when the user does not have access
166 to private keys for signing and must send the digest to
167 be signed through an external framework.
168 All input formats besides [f]ile will be prevalidated. To skip
169 prevalidation of the input file, use -f to force to generation.
170 If [h]ash is input or output type be sure to specify the hashing
171 algorithm to use by using the argument -h <hashAlg>. This argu‐
172 ment does not effect the digest algortithm of the signed data in
173 a [p]kcs7 or [a]uth file, these will always use SHA256.
174 Accepted values for <hashAlg> are one of {'SHA256', 'SHA224',
175 'SHA1', 'SHA384', 'SHA512'}
176 Additionally, when the output type is [p]kcs7 or [a]uth, the
177 user must give at least one pair of public and private keys -c
178 <cert> -k <privKey> to sign the input file with. However, if the
179 user does not have access to their private keys and are only
180 able to interact with a signing framework, they can use -s <sig‐
181 File> in replacement of the private key argument. <sigFile>
182 would contain only the raw signed data of a digest generated
183 with `secvarctl generate c:x`, it is important that both these
184 commands use the same custom timestamp argument -t <y-m-d
185 h:m:s>.
186 When generating an [a]uth file, it is required the user give
187 the secure variable name that the auth file is for, -n <varName>
188 , where <varName> is one of {"PK","KEK", "db", "dbx"}. This
189 argument is also useful when the input file is an ESL for the
190 dbx (use -n dbx) because then the prevalidation will look for an
191 ESL containing a hash rather than an x509.
192 Also, when the output type is a [p]kcs7 or [a]uth file, the
193 user can use a custom timestamp with -t <time> , where <time> is
194 in the format "y-m-d h:m:s". If this argument is not used then
195 the current date and time are used.
196 When using the input type '[f]ile' it will be assumed to be a
197 text file and if output file is '[e]sl', '[p]kcs7' or '[a]uth'
198 it will be hashed according to <hashAlg> (default SHA256).
199 To make a variable reset file, the user can replace generate
200 <inputFormat>:<outputFormat> with generate reset This will gen‐
201 erate an auth file around an empty ESL. Thus, no input argument
202 -i is required when making a reset file.
203 NOTE: GENERATION OF PKCS7 AND AUTH FILES ARE IN EXPERIMENTAL
204 DEVELEPOMENT PHASE. THEY HAVE NOT BEEN THOROUGHLY TESTED YET.
205
209 For secvarctl [OPTIONS]:
210 --usage
211 --help
213 For secvarctl read [OPTIONS] <variable>:
215 --usage
216 --help
218 -r , raw output
220 -f <input.esl> , read from file
222 -p </path/to/vars/> , read from path (subdirectories {"PK",
224 "KEK, "db", "dbx", "TS"} each with files {"data", "size"}
225 expected)
226 <variable> , one of {"PK", "KEK, "db", "dbx", "TS"}
228 For secvarctl write [OPTIONS] <variable> <file>:
231 REQUIRED:
232 <variable> , one of {"PK", "KEK, "db", "dbx"}
233 <file> , an auth file
235 OPTIONS:
236 --usage
237 --help
239 -v , verbose output
241 -f , force update, no validation
243 -p </path/to/vars/> , write to file in path (subdirecto‐
245 ries {"PK", "KEK, "db", "dbx"} each with "update" file
246 expected)
247 For secvarctl validate [OPTIONS] <file type> <file>:
249 REQUIRED:
250 <file> , the input file, assumed to be auth file if not
251 specified
252 OPTIONS:
253 --usage
254 --help
256 -v , verbose output
258 -x , dbx file (contains hash not x509)
260 -e <file> , ESL
262 -p <file> , PKCS7/Signed Data
264 -c <file> , DER or PEM certificate
266 -a <file>, DEFAULT, a signed authenticated file containg
268 a pkcs7 and appended ESL
269 For secvarctl verify [OPTIONS] -u {Update Variables}:
271 REQUIRED:
272 -u {Update Variables} , the updates to be run
273 OPTIONAL:
274 --usage
275 --help
277 -v , verbose output
279 -p </path/to/vars/>, read from path (subdirectories
281 {"PK", "KEK, "db", "dbx", "TS"} each with files {"data",
282 "size"} expected)
283 -w , write updates if verified
285 -c {Current Variables} , list of current variables
287 {Update Variables}:
289 Format: <varname_1> <file_1> <varname_2> <file_2> ...
290 Where <varname> is one of {"PK", "KEK, "db", "dbx"} and
291 <file> is an auth file
292 Note: Updates are verified in the order they are submit‐
293 ted
294 {Current Variables}:
295 Format: <varname_1> <file_1> <varname_2> <file_2> ...
296 Where <varname> is one of {"PK", "KEK, "db", "dbx", "TS"}
297 and <file> is an esl file (unless TS)
298 For secvarctl generate <inputFormat>:<outputFormat> [OPTIONS] -i
300 <inputFile> -o <outputFile> :
301 REQUIRED:
302 <inputFormat>:<outputFormat> , {'[c]ert', '[h]ash',
303 '[e]sl', '[p]kcs7', '[a]uth', '[f]ile'}:{ '[h]ash',
304 '[e]sl', '[p]kcs7', '[a]uth', '[x] presigned digest'} SEE
305 DESCRIPTION FOR HELP
306 -i <inputFile> , input file that has the format specified
308 by <inputFormat>
309 -o <outputFile> , output file that will have the format
311 specified by <outputFormat>
312 OPTIONAL:
313 --usage
314 --help
316 -v , verbose output
318 -f , force generation, skips validation of input file and
320 assumes it to be formatted according to <inputFormat>
321 -n <varName> , name of secure boot variable, used when
323 generating an auth file, PKCS7, or when the input file
324 contains hashed data rather than x509 (use '-n dbx'),
325 current <varName> are: {'PK','KEK','db','dbx'}
326 -t <time> , where time is of the format 'y-m-d h:m:s'.
328 creates a custom timestamp used when generating an auth
329 or PKCS7 file, if not given then current time is used
330 -h <hashAlg> , hash function, used when output or input
332 format is hash, current values for <hashAlg> are :
333 {'SHA256', 'SHA224', 'SHA1', 'SHA384', 'SHA512'}
334 -k <privKey> , private key, used when generating pkcs7 or
336 auth file
337 -s <sigFile> , signed data file, alternative to internal
339 signing, replacement of private key argument
340 -c <certFile> , x509 certificate (PEM), used when gener‐
342 ating pkcs7 or auth file
343 reset , replaces <inputFormat>:<outputFormat> and gener‐
345 ates an auth file with an empty ESL (a valid variable
346 reset file), no input file required. Required arguments
347 are output file, signer public and private key and vari‐
348 able name.
349
351 To read all current variables in default path:
352 $secvarctl read
353 To read the raw data of the PK in a specific location:
355 $secvarctl read -p /home/user1/myVars/ -r PK
356 To validate and write an auth file to the default KEK location:
358 $secvarctl write KEK updateFile.auth
359 To write to /home/user1/myVars/KEK/update with no formatting checks:
361 $secvarctl write -p /home/user1/ -f KEK updateFile.auth
362 To validate the format of an auth file:
364 $secvarctl validate authFile.auth
365 To validate the format of a ESL with extra process info:
367 $secvarctl validate -e eslFile.esl -v
368 To verify the desired updates against the default path and, if success‐
370 ful, commit the updates:
371 $secvarctl verify -w -u db dbUpdate.auth KEK kekUpdate.auth
372 To verify the desired updates against a specific set of signers with
374 extra process info:
375 $secvarctl verify -v -c PK myPK.esl KEK myKEK.esl dbx
376 myDBX.esl -u DB dbUpdate.auth PK pkUpdate.auth
377 To get the attatched ESL from an auth file:
379 $secvarctl generate a:e -i file.auth -o file.esl
380 To create an ESL from an x509 certificate:
382 $secvarctl generate c:e -i file.pem -o file.esl
383 To create SHA512 from a file:
385 $secvarctl generate f:h -h SHA512 -i file.txt -o file.hash
386 To create ESL from a hash:
388 $secvarctl generate h:e -h 512 -i file.has -o file.esl
389 To create an auth file from the esl containg a hash for a dbx update:
391 $secvarctl generate e:a -k signer.key -c signer.crt -n dbx -i
392 file.esl -o file.auth
393 To create an auth file from a certificate for a KEK update (this will
395 create an ESL from the certificate and use the ESL for the Auth File):
396 $secvarctl generate c:a -k signer.key -c signer.crt -n KEK -i
397 file.crt -o file.auth
398 To create a PKCS7 file from an ESL for a db update with a custom time‐
400 stamp:
401 $secvarctl generate e:p -k signer.key -c signer.crt -n db -t
402 2020-10-1 13:45:42 -i file.crt -o file.pkcs7
403 To create an empty update to reset the db variable:
405 $secvarctl generate reset -k signer.key -c signer.crt -n db -o
406 db.auth
407 To create an auth file using an external signing framework for db
409 update:
410 $secvarctl generate c:x -n db -t 2021-1-1 1:1:1 -i file.crt -o
411 file.hash
412 <user sends file.hash to be signed by external entity, signature
413 is now in file.sig>
414 $secvarctl generate c:a -n db -t 2021-1-1 1:1:1 -c signer.crt -s
415 file.sig -i file.crt -o file.auth
416
419 Nick Child nick.child@ibm.com,
420 Eric Richter,
422 Nayna Jain
424version 0.1 1 OCTOBER 2020 secvarctl(1)