1secvarctl(1)                General Commands Manual               secvarctl(1)
2
3
4

NAME

6       secvarctl - A command line tool for simplifying the reading and writing
7       of secure boot variables.
8
9       Commands are:
10              read - read from the secure variable directory and print out in‐
11              formation on their current contents
12
13
14              write - update the given variable's key value
15
16              validate - checks that the format and basic content requirements
17              are met for the given file type
18
19              verify - checks that the given files are correctly signed by the
20              current variables
21
22              generate  -  generates  several  different types of file formats
23              relevant to updating secure variables
24
25

SYNOPSIS

27       secvarctl [OPTIONS]
28
29       secvarctl read [OPTIONS] <variable>
30
31
32       secvarctl write [OPTIONS] <variable> <file>
33
34       secvarctl validate [OPTIONS] <file type> <file>
35
36       secvarctl verify [OPTIONS] -u {Update Variables}
37
38       secvarctl generate <inputFormat>:<outputFormat>  [OPTIONS]  -i  <input‐
39       File> -o <outputFile>
40
41       secvarctl generate reset [OPTIONS] -o <outputFile> -k <key> -c <crt> -n
42       <variable>
43
44

DESCRIPTION

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
52              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
70              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
89              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
105              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
132              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
205
206

OPTIONS

208       For secvarctl [OPTIONS]:
209              --usage
210
211              --help
212
213       For secvarctl read [OPTIONS] <variable>:
214              --usage
215
216              --help
217
218              -r , raw output
219
220              -f <input.esl> , read from file
221
222              -p </path/to/vars/> ,  read  from  path  (subdirectories  {"PK",
223              "KEK,  "db",  "dbx",  "TS"} each with files {"data", "size"} ex‐
224              pected)
225
226              <variable>  , one of {"PK", "KEK, "db", "dbx", "TS"}
227
228
229       For secvarctl write [OPTIONS] <variable> <file>:
230              REQUIRED:
231                     <variable> , one of {"PK", "KEK, "db", "dbx"}
232
233                     <file> , an auth file
234              OPTIONS:
235                     --usage
236
237                     --help
238
239                     -v , verbose output
240
241                     -f , force update, no validation
242
243                     -p </path/to/vars/> , write to file in path  (subdirecto‐
244                     ries  {"PK",  "KEK,  "db", "dbx"} each with "update" file
245                     expected)
246
247       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
254                     --help
255
256                     -v , verbose output
257
258                     -x , dbx file (contains hash not x509)
259
260                     -e <file> , ESL
261
262                     -p <file> , PKCS7/Signed Data
263
264                     -c <file> , DER or PEM certificate
265
266                     -a <file>, DEFAULT,  a signed authenticated file containg
267                     a pkcs7 and appended ESL
268
269       For secvarctl verify [OPTIONS] -u {Update Variables}:
270              REQUIRED:
271                     -u {Update Variables} , the updates to be run
272              OPTIONAL:
273                     --usage
274
275                     --help
276
277                     -v , verbose output
278
279                     -p  </path/to/vars/>,  read  from  path   (subdirectories
280                     {"PK",  "KEK, "db", "dbx", "TS"} each with files {"data",
281                     "size"} expected)
282
283                     -w , write updates if verified
284
285                     -c {Current Variables} , list of current variables
286
287              {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
298       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
306                     -i <inputFile> , input file that has the format specified
307                     by <inputFormat>
308
309                     -o  <outputFile>  , output file that will have the format
310                     specified by <outputFormat>
311              OPTIONAL:
312                     --usage
313
314                     --help
315
316                     -v , verbose output
317
318                     -f , force generation, skips validation of input file and
319                     assumes it to be formatted according to <inputFormat>
320
321                     -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
326                     -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
343                     -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
347                     -k <privKey> , private key, used when generating pkcs7 or
348                     auth file
349
350                     -s <sigFile> , signed data file, alternative to  internal
351                     signing, replacement of private key argument
352
353                     -c  <certFile> , x509 certificate (PEM), used when gener‐
354                     ating pkcs7 or auth file
355
356                     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

EXAMPLES

363       To read all current variables in default path:
364            $secvarctl read
365
366       To read the raw data of the PK in a specific location:
367                 $secvarctl read -p /home/user1/myVars/ -r PK
368
369       To validate and write an auth file to the default KEK location:
370                 $secvarctl write KEK updateFile.auth
371
372       To write to /home/user1/myVars/KEK/update with no formatting checks:
373                 $secvarctl write -p /home/user1/ -f KEK updateFile.auth
374
375       To validate the format of an auth file:
376                 $secvarctl validate authFile.auth
377
378       To validate the format of a ESL with extra process info:
379                 $secvarctl validate -e eslFile.esl -v
380
381       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
385       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
390       To get the attatched ESL from an auth file:
391                 $secvarctl generate a:e -i file.auth -o file.esl
392
393       To create an ESL from an x509 certificate:
394             $secvarctl generate c:e -i file.pem -o file.esl
395
396       To create SHA512 from a file:
397             $secvarctl generate f:h -h SHA512 -i file.txt -o file.hash
398
399       To create ESL from a hash:
400             $secvarctl generate h:e -h 512 -i file.has -o file.esl
401
402       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
406       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
411       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
416       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
420       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
429

AUTHOR

431       Nick Child nick.child@ibm.com,
432
433       Eric Richter,
434
435       Nayna Jain
436
437
438
439version 0.1                     1 OCTOBER 2020                    secvarctl(1)
Impressum