Rationalize command line option long and short names

[emmanuel-deloget]

There are multiple cases in the code where a similar option on two different tools are named differently. For example, the long name of option -g (alg) in tpm2_getpubek.c is "alg", where the same option tpm2_hmac.c is named "algorithm". Similarly, option in-file is -I in most tools, and -f in tpm2_activatecredential.

Here is the output of a (rather convoluted) command

grep -rHn -- '{[[:space:]]*"[a-zA-Z0-9_-]\+"' tools/* | awk -F ':' '{ print $1 " --- " $3 }' | sed 's/[[:space:]]*//;s/{"/{ "/;s/,/ /g;s/}/ }/g;s/[[:space:]]\+/ /g' | awk '{ printf("%-30s %-6s %s\n",$4,$7,$1); }' | LANG=C sort

"--output"                     'o'    tools/tpm2_send.c
"Hierachy"                     'H'    tools/tpm2_loadexternal.c
"Password"                     'P'    tools/tpm2_activatecredential.c
"SSL-NO-VERIFY"                'U'    tools/tpm2_getmanufec.c
"ak-context"                   'c'    tools/tpm2_quote.c
"ak-handle"                    'k'    tools/tpm2_getpubak.c
"ak-handle"                    'k'    tools/tpm2_quote.c
"ak-name"                      'n'    tools/tpm2_getpubak.c
"ak-passwd"                    'P'    tools/tpm2_getpubak.c
"ak-password"                  'P'    tools/tpm2_quote.c
"alg"                          'g'    tools/tpm2_getmanufec.c
"alg"                          'g'    tools/tpm2_getpubak.c
"alg"                          'g'    tools/tpm2_getpubek.c
"algorithm"                    'g'    tools/tpm2_hmac.c
"algorithm"                    'g'    tools/tpm2_pcrlist.c
"algorithm"                    'g'    tools/tpm2_quote.c
"algs"                         's'    tools/tpm2_pcrlist.c
"attest-file"                  'a'    tools/tpm2_certify.c
"attribute"                    't'    tools/tpm2_nvdefine.c
"auth"                         'A'    tools/tpm2_evictcontrol.c
"auth-handle"                  'a'    tools/tpm2_nvdefine.c
"auth-handle"                  'a'    tools/tpm2_nvread.c
"auth-handle"                  'a'    tools/tpm2_nvreadlock.c
"auth-handle"                  'a'    tools/tpm2_nvrelease.c
"auth-handle"                  'a'    tools/tpm2_nvwrite.c
"auth-policy-session"          'a'    tools/tpm2_createpolicy.c
"capability"                   'c'    tools/tpm2_getcap.c
"clear"                        'c'    tools/tpm2_startup.c
"clear-lockout"                'c'    tools/tpm2_dictionarylockout.c
"context"                      'C'    tools/tpm2_createprimary.c
"context"                      'C'    tools/tpm2_load.c
"context"                      'C'    tools/tpm2_loadexternal.c
"context"                      'c'    tools/tpm2_activatecredential.c
"context"                      'c'    tools/tpm2_evictcontrol.c
"context-object"               'c'    tools/tpm2_readpublic.c
"context-parent"               'c'    tools/tpm2_create.c
"context-parent"               'c'    tools/tpm2_load.c
"dbg"                          'd'    tools/tpm2_getpubek.c
"decrypt"                      'D'    tools/tpm2_encryptdecrypt.c
"digest"                       'D'    tools/tpm2_verifysignature.c
"digest-alg"                   'D'    tools/tpm2_getpubak.c
"ec-cert"                      'E'    tools/tpm2_getmanufec.c
"ek-handle"                    'E'    tools/tpm2_getpubak.c
"ek-passwd"                    'P'    tools/tpm2_getmanufec.c
"ek-passwd"                    'P'    tools/tpm2_getpubek.c
"enc-key"                      'e'    tools/tpm2_makecredential.c
"endorse-passwd"               'e'    tools/tpm2_activatecredential.c
"endorse-passwd"               'e'    tools/tpm2_changeauth.c
"endorse-passwd"               'e'    tools/tpm2_getmanufec.c
"endorse-passwd"               'e'    tools/tpm2_getpubak.c
"endorse-passwd"               'e'    tools/tpm2_getpubek.c
"extend-policy-session"        'e'    tools/tpm2_createpolicy.c
"file"                         'f'    tools/tpm2_getpubak.c
"file"                         'f'    tools/tpm2_getpubek.c
"format"                       'f'    tools/tpm2_certify.c
"format"                       'f'    tools/tpm2_pcrlist.c
"format"                       'f'    tools/tpm2_quote.c
"format"                       'f'    tools/tpm2_readpublic.c
"format"                       'f'    tools/tpm2_sign.c
"halg"                         'g'    tools/tpm2_certify.c
"halg"                         'g'    tools/tpm2_create.c
"halg"                         'g'    tools/tpm2_createprimary.c
"halg"                         'g'    tools/tpm2_hash.c
"halg"                         'g'    tools/tpm2_listpersistent.c
"halg"                         'g'    tools/tpm2_sign.c
"halg"                         'g'    tools/tpm2_verifysignature.c
"handle"                       'H'    tools/tpm2_activatecredential.c
"handle"                       'H'    tools/tpm2_evictcontrol.c
"handle"                       'H'    tools/tpm2_flushcontext.c
"handle"                       'H'    tools/tpm2_getmanufec.c
"handle"                       'H'    tools/tpm2_getpubek.c
"handle-passwd"                'P'    tools/tpm2_nvdefine.c
"handle-passwd"                'P'    tools/tpm2_nvread.c
"handle-passwd"                'P'    tools/tpm2_nvreadlock.c
"handle-passwd"                'P'    tools/tpm2_nvrelease.c
"handle-passwd"                'P'    tools/tpm2_nvwrite.c
"help"                         'h'    tools/tpm2_getpubek.c
"hierachy"                     'H'    tools/tpm2_hash.c
"hierarchy"                    'H'    tools/tpm2_createprimary.c
"id-list"                      'l'    tools/tpm2_quote.c
"import-key-private"           'r'    tools/tpm2_import.c
"import-key-public"            'q'    tools/tpm2_import.c
"in-file"                      'I'    tools/tpm2_create.c
"in-file"                      'I'    tools/tpm2_encryptdecrypt.c
"in-file"                      'I'    tools/tpm2_rsadecrypt.c
"in-file"                      'f'    tools/tpm2_activatecredential.c
"index"                        'x'    tools/tpm2_nvdefine.c
"index"                        'x'    tools/tpm2_nvread.c
"index"                        'x'    tools/tpm2_nvreadlock.c
"index"                        'x'    tools/tpm2_nvrelease.c
"index"                        'x'    tools/tpm2_nvwrite.c
"index-passwd"                 'I'    tools/tpm2_nvdefine.c
"input-key-file"               'k'    tools/tpm2_import.c
"input-session-handle"         'S'    tools/tpm2_create.c
"input-session-handle"         'S'    tools/tpm2_createprimary.c
"input-session-handle"         'S'    tools/tpm2_dictionarylockout.c
"input-session-handle"         'S'    tools/tpm2_encryptdecrypt.c
"input-session-handle"         'S'    tools/tpm2_getmanufec.c
"input-session-handle"         'S'    tools/tpm2_getpubek.c
"input-session-handle"         'S'    tools/tpm2_hmac.c
"input-session-handle"         'S'    tools/tpm2_load.c
"input-session-handle"         'S'    tools/tpm2_nvdefine.c
"input-session-handle"         'S'    tools/tpm2_nvread.c
"input-session-handle"         'S'    tools/tpm2_nvreadlock.c
"input-session-handle"         'S'    tools/tpm2_nvrelease.c
"input-session-handle"         'S'    tools/tpm2_nvwrite.c
"input-session-handle"         'S'    tools/tpm2_pcrevent.c
"input-session-handle"         'S'    tools/tpm2_quote.c
"input-session-handle"         'S'    tools/tpm2_rsadecrypt.c
"input-session-handle"         'S'    tools/tpm2_sign.c
"input-session-handle"         'S'    tools/tpm2_unseal.c
"input-session-handle"         'i'    tools/tpm2_evictcontrol.c
"item"                         'H'    tools/tpm2_unseal.c
"item-context"                 'c'    tools/tpm2_unseal.c
"kalg"                         'G'    tools/tpm2_create.c
"kalg"                         'G'    tools/tpm2_createprimary.c
"kalg"                         'G'    tools/tpm2_listpersistent.c
"key-context"                  'C'    tools/tpm2_activatecredential.c
"key-context"                  'c'    tools/tpm2_certify.c
"key-context"                  'c'    tools/tpm2_encryptdecrypt.c
"key-context"                  'c'    tools/tpm2_hmac.c
"key-context"                  'c'    tools/tpm2_rsadecrypt.c
"key-context"                  'c'    tools/tpm2_rsaencrypt.c
"key-context"                  'c'    tools/tpm2_sign.c
"key-context"                  'c'    tools/tpm2_verifysignature.c
"key-handle"                   'k'    tools/tpm2_activatecredential.c
"key-handle"                   'k'    tools/tpm2_certify.c
"key-handle"                   'k'    tools/tpm2_encryptdecrypt.c
"key-handle"                   'k'    tools/tpm2_hmac.c
"key-handle"                   'k'    tools/tpm2_rsadecrypt.c
"key-handle"                   'k'    tools/tpm2_rsaencrypt.c
"key-handle"                   'k'    tools/tpm2_sign.c
"key-handle"                   'k'    tools/tpm2_verifysignature.c
"loaded-session"               'l'    tools/tpm2_flushcontext.c
"lock-passwd"                  'l'    tools/tpm2_changeauth.c
"lockout-passwd"               'P'    tools/tpm2_dictionarylockout.c
"lockout-password"             'L'    tools/tpm2_clear.c
"lockout-recovery-time"        'l'    tools/tpm2_dictionarylockout.c
"max-tries"                    'n'    tools/tpm2_dictionarylockout.c
"message"                      'm'    tools/tpm2_quote.c
"msg"                          'm'    tools/tpm2_sign.c
"msg"                          'm'    tools/tpm2_verifysignature.c
"name"                         'n'    tools/tpm2_load.c
"name"                         'n'    tools/tpm2_makecredential.c
"non-persistent"               'N'    tools/tpm2_getmanufec.c
"obj-context"                  'C'    tools/tpm2_certify.c
"object"                       'H'    tools/tpm2_readpublic.c
"object-attributes"            'A'    tools/tpm2_create.c
"object-attributes"            'A'    tools/tpm2_createprimary.c
"object-attributes"            'A'    tools/tpm2_import.c
"object-handle"                'H'    tools/tpm2_certify.c
"offline"                      'O'    tools/tpm2_getmanufec.c
"offset"                       'o'    tools/tpm2_nvread.c
"offset"                       'o'    tools/tpm2_nvwrite.c
"oldEndorsePasswd"             'E'    tools/tpm2_changeauth.c
"oldLockPasswd"                'L'    tools/tpm2_changeauth.c
"oldOwnerPasswd"               'O'    tools/tpm2_changeauth.c
"opu"                          'o'    tools/tpm2_readpublic.c
"out-file"                     'o'    tools/tpm2_activatecredential.c
"out-file"                     'o'    tools/tpm2_encryptdecrypt.c
"out-file"                     'o'    tools/tpm2_makecredential.c
"out-file"                     'o'    tools/tpm2_rsadecrypt.c
"out-file"                     'o'    tools/tpm2_rsaencrypt.c
"outfile"                      'o'    tools/tpm2_hash.c
"outfile"                      'o'    tools/tpm2_hmac.c
"outfile"                      'o'    tools/tpm2_unseal.c
"output"                       'f'    tools/tpm2_getmanufec.c
"output"                       'f'    tools/tpm2_nvread.c
"output"                       'o'    tools/tpm2_getrandom.c
"output"                       'o'    tools/tpm2_pcrlist.c
"owner-passwd"                 'o'    tools/tpm2_changeauth.c
"owner-passwd"                 'o'    tools/tpm2_getmanufec.c
"owner-passwd"                 'o'    tools/tpm2_getpubak.c
"owner-passwd"                 'o'    tools/tpm2_getpubek.c
"parent"                       'H'    tools/tpm2_create.c
"parent"                       'H'    tools/tpm2_load.c
"parent-key-handle"            'H'    tools/tpm2_import.c
"parent-key-public"            'f'    tools/tpm2_import.c
"passwdInHex"                  'X'    tools/tpm2_activatecredential.c
"passwdInHex"                  'X'    tools/tpm2_nvdefine.c
"passwdInHex"                  'X'    tools/tpm2_nvreadlock.c
"password"                     'P'    tools/tpm2_pcrevent.c
"pcr-index"                    'i'    tools/tpm2_pcrevent.c
"pcr-input-file"               'F'    tools/tpm2_createpolicy.c
"pcr-input-file"               'F'    tools/tpm2_nvread.c
"pcr-input-file"               'F'    tools/tpm2_nvwrite.c
"pcr-input-file"               'F'    tools/tpm2_unseal.c
"persistent"                   'S'    tools/tpm2_evictcontrol.c
"platform"                     'p'    tools/tpm2_clear.c
"policy-digest-alg"            'g'    tools/tpm2_createpolicy.c
"policy-file"                  'L'    tools/tpm2_create.c
"policy-file"                  'L'    tools/tpm2_createprimary.c
"policy-file"                  'L'    tools/tpm2_nvdefine.c
"policy-file"                  'f'    tools/tpm2_createpolicy.c
"policy-pcr"                   'P'    tools/tpm2_createpolicy.c
"privfile"                     'r'    tools/tpm2_create.c
"privfile"                     'r'    tools/tpm2_load.c
"privfile"                     'r'    tools/tpm2_loadexternal.c
"pubfile"                      'u'    tools/tpm2_create.c
"pubfile"                      'u'    tools/tpm2_load.c
"pubfile"                      'u'    tools/tpm2_loadexternal.c
"pwda"                         'P'    tools/tpm2_evictcontrol.c
"pwdk"                         'K'    tools/tpm2_certify.c
"pwdk"                         'K'    tools/tpm2_create.c
"pwdk"                         'K'    tools/tpm2_createprimary.c
"pwdk"                         'P'    tools/tpm2_encryptdecrypt.c
"pwdk"                         'P'    tools/tpm2_hmac.c
"pwdk"                         'P'    tools/tpm2_rsadecrypt.c
"pwdk"                         'P'    tools/tpm2_sign.c
"pwdk"                         'P'    tools/tpm2_unseal.c
"pwdo"                         'P'    tools/tpm2_certify.c
"pwdp"                         'P'    tools/tpm2_create.c
"pwdp"                         'P'    tools/tpm2_createprimary.c
"pwdp"                         'P'    tools/tpm2_load.c
"qualify-data"                 'q'    tools/tpm2_quote.c
"raw"                          'r'    tools/tpm2_verifysignature.c
"recovery-time"                't'    tools/tpm2_dictionarylockout.c
"save-session-context"         'S'    tools/tpm2_createpolicy.c
"saved-session"                's'    tools/tpm2_flushcontext.c
"sec"                          's'    tools/tpm2_makecredential.c
"sel-list"                     'L'    tools/tpm2_pcrlist.c
"sel-list"                     'L'    tools/tpm2_quote.c
"set-list"                     'L'    tools/tpm2_createpolicy.c
"set-list"                     'L'    tools/tpm2_nvread.c
"set-list"                     'L'    tools/tpm2_nvwrite.c
"set-list"                     'L'    tools/tpm2_unseal.c
"setup-parameters"             's'    tools/tpm2_dictionarylockout.c
"sig"                          's'    tools/tpm2_sign.c
"sig"                          's'    tools/tpm2_verifysignature.c
"sig-file"                     's'    tools/tpm2_certify.c
"sig-hash-algorithm"           'G'    tools/tpm2_quote.c
"sign-alg"                     's'    tools/tpm2_getpubak.c
"signature"                    's'    tools/tpm2_quote.c
"size"                         's'    tools/tpm2_nvdefine.c
"size"                         's'    tools/tpm2_nvread.c
"ticket"                       't'    tools/tpm2_hash.c
"ticket"                       't'    tools/tpm2_sign.c
"ticket"                       't'    tools/tpm2_verifysignature.c
"transient-object"             't'    tools/tpm2_flushcontext.c

It shows what should be all options used within the various tools (minus those defined in the private library).

Best regards,

-- Emmanuel Deloget

[martinezjavier]

@emmanuel-deloget agreed. It used to be even worse, there have been some work to make the options more consistent, as an example:

cd3a1c72b278 tpm2_create: rename options for public and sensitive portions of the object 634ea6a795e5 tpm2_createprimary: add attribute support

Since there are a lot of tools and options, sometime is hard to be consistent though. For example -H is --hierarchy for most tools, but some tools use -H has --handle. So if a tool gets both a hierarchy and a handle you have to make a compromise.

But yes, we should try to be as consistent as possible to avoid confusing users.

[emmanuel-deloget]

@martinezjavier honestly, this is a proposal, as I don't have much idea on how to correctly achieve that. There are a few change I can make (alg --> algorithm, password --> passwd, and a few other obvious fixes) but this is the tip of the iceberg (the iceberg itself is not that big).

[martinezjavier]

@emmanuel-deloget yes, whatever change you may do is always welcomed. The more consistent the options, the better for users.

[emmanuel-deloget]

With the hereby mentionned commits, the following changes occurs.

I did not changed the short option names right now, as this is more difficult (and may have more impact on real world scripts).

@@ -1,4 +1,3 @@
-"--output"                     'o'    tools/tpm2_send.c
 "Hierachy"                     'H'    tools/tpm2_loadexternal.c
 "Password"                     'P'    tools/tpm2_activatecredential.c
 "SSL-NO-VERIFY"                'U'    tools/tpm2_getmanufec.c
@@ -7,10 +6,10 @@
 "ak-handle"                    'k'    tools/tpm2_quote.c
 "ak-name"                      'n'    tools/tpm2_getpubak.c
 "ak-passwd"                    'P'    tools/tpm2_getpubak.c
-"ak-password"                  'P'    tools/tpm2_quote.c
-"alg"                          'g'    tools/tpm2_getmanufec.c
-"alg"                          'g'    tools/tpm2_getpubak.c
-"alg"                          'g'    tools/tpm2_getpubek.c
+"ak-passwd"                    'P'    tools/tpm2_quote.c
+"algorithm"                    'g'    tools/tpm2_getmanufec.c
+"algorithm"                    'g'    tools/tpm2_getpubak.c
+"algorithm"                    'g'    tools/tpm2_getpubek.c
 "algorithm"                    'g'    tools/tpm2_hmac.c
 "algorithm"                    'g'    tools/tpm2_pcrlist.c
 "algorithm"                    'g'    tools/tpm2_quote.c
@@ -75,8 +74,8 @@
 "handle-passwd"                'P'    tools/tpm2_nvrelease.c
 "handle-passwd"                'P'    tools/tpm2_nvwrite.c
 "help"                         'h'    tools/tpm2_getpubek.c
-"hierachy"                     'H'    tools/tpm2_hash.c
 "hierarchy"                    'H'    tools/tpm2_createprimary.c
+"hierarchy"                    'H'    tools/tpm2_hash.c
 "id-list"                      'l'    tools/tpm2_quote.c
 "import-key-private"           'r'    tools/tpm2_import.c
 "import-key-public"            'q'    tools/tpm2_import.c
@@ -132,14 +131,14 @@
 "key-handle"                   'k'    tools/tpm2_sign.c
 "key-handle"                   'k'    tools/tpm2_verifysignature.c
 "loaded-session"               'l'    tools/tpm2_flushcontext.c
-"lock-passwd"                  'l'    tools/tpm2_changeauth.c
+"lockout-passwd"               'L'    tools/tpm2_clear.c
 "lockout-passwd"               'P'    tools/tpm2_dictionarylockout.c
-"lockout-password"             'L'    tools/tpm2_clear.c
+"lockout-passwd"               'l'    tools/tpm2_changeauth.c
 "lockout-recovery-time"        'l'    tools/tpm2_dictionarylockout.c
 "max-tries"                    'n'    tools/tpm2_dictionarylockout.c
 "message"                      'm'    tools/tpm2_quote.c
-"msg"                          'm'    tools/tpm2_sign.c
-"msg"                          'm'    tools/tpm2_verifysignature.c
+"message"                      'm'    tools/tpm2_sign.c
+"message"                      'm'    tools/tpm2_verifysignature.c
 "name"                         'n'    tools/tpm2_load.c
 "name"                         'n'    tools/tpm2_makecredential.c
 "non-persistent"               'N'    tools/tpm2_getmanufec.c
@@ -152,22 +151,23 @@
 "offline"                      'O'    tools/tpm2_getmanufec.c
 "offset"                       'o'    tools/tpm2_nvread.c
 "offset"                       'o'    tools/tpm2_nvwrite.c
-"oldEndorsePasswd"             'E'    tools/tpm2_changeauth.c
-"oldLockPasswd"                'L'    tools/tpm2_changeauth.c
-"oldOwnerPasswd"               'O'    tools/tpm2_changeauth.c
-"opu"                          'o'    tools/tpm2_readpublic.c
+"old-endorse-passwd"           'E'    tools/tpm2_changeauth.c
+"old-ockout-passwd"            'L'    tools/tpm2_changeauth.c
+"old-owner-passwd"             'O'    tools/tpm2_changeauth.c
+"out-file"                     'f'    tools/tpm2_getmanufec.c
+"out-file"                     'f'    tools/tpm2_nvread.c
 "out-file"                     'o'    tools/tpm2_activatecredential.c
 "out-file"                     'o'    tools/tpm2_encryptdecrypt.c
+"out-file"                     'o'    tools/tpm2_getrandom.c
+"out-file"                     'o'    tools/tpm2_hash.c
+"out-file"                     'o'    tools/tpm2_hmac.c
 "out-file"                     'o'    tools/tpm2_makecredential.c
+"out-file"                     'o'    tools/tpm2_pcrlist.c
+"out-file"                     'o'    tools/tpm2_readpublic.c
 "out-file"                     'o'    tools/tpm2_rsadecrypt.c
 "out-file"                     'o'    tools/tpm2_rsaencrypt.c
-"outfile"                      'o'    tools/tpm2_hash.c
-"outfile"                      'o'    tools/tpm2_hmac.c
-"outfile"                      'o'    tools/tpm2_unseal.c
-"output"                       'f'    tools/tpm2_getmanufec.c
-"output"                       'f'    tools/tpm2_nvread.c
-"output"                       'o'    tools/tpm2_getrandom.c
-"output"                       'o'    tools/tpm2_pcrlist.c
+"out-file"                     'o'    tools/tpm2_send.c
+"out-file"                     'o'    tools/tpm2_unseal.c
 "owner-passwd"                 'o'    tools/tpm2_changeauth.c
 "owner-passwd"                 'o'    tools/tpm2_getmanufec.c
 "owner-passwd"                 'o'    tools/tpm2_getpubak.c
@@ -176,10 +176,10 @@
 "parent"                       'H'    tools/tpm2_load.c
 "parent-key-handle"            'H'    tools/tpm2_import.c
 "parent-key-public"            'f'    tools/tpm2_import.c
+"passwd"                       'P'    tools/tpm2_pcrevent.c
 "passwdInHex"                  'X'    tools/tpm2_activatecredential.c
 "passwdInHex"                  'X'    tools/tpm2_nvdefine.c
 "passwdInHex"                  'X'    tools/tpm2_nvreadlock.c
-"password"                     'P'    tools/tpm2_pcrevent.c
 "pcr-index"                    'i'    tools/tpm2_pcrevent.c
 "pcr-input-file"               'F'    tools/tpm2_createpolicy.c
 "pcr-input-file"               'F'    tools/tpm2_nvread.c