update documentation and help output for how to specify secrets on stdin

also update all examples to have no space after short option.
2017-04-19 13:54:24 +02:00
parent a7ef1315f4
commit 9dfe04cd06
5 changed files with 72 additions and 74 deletions
@@ -91,49 +91,46 @@ on exactly what happens --verbose or --verbose=2 may be added.
 Generate a new ECC-P256 key on device in slot 9a, will print the public
 key on stdout:

-  $ yubico-piv-tool -s 9a -A ECCP256 -a generate
+  $ yubico-piv-tool -s9a -AECCP256 -agenerate

 Generate a certificate request with public key from stdin, will print
 the resulting request on stdout:

-  $ yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
-    -a verify -a request
+  $ yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest

 Generate a self-signed certificate with public key from stdin, will print
 the certificate, for later import, on stdout:

-  $ yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
-    -a verify -a selfsign
+  $ yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify -aselfsign

 Import a certificate from stdin:

-  $ yubico-piv-tool -s 9a -a import-certificate
+  $ yubico-piv-tool -s9a -aimport-certificate

 Set a random chuid, import a key and import a certificate from a PKCS12
-file with password test, into slot 9c:
+file, into slot 9c:

-  $ yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
-    -a import-key -a import-cert
+  $ yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key \
+    -aimport-cert

 Change the management key used for administrative authentication:

-  $ yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
-    -a set-mgm-key
+  $ yubico-piv-tool -aset-mgm-key

-Delete a certificate in slot 9a:
+Delete a certificate in slot 9a, with management key being asked for:

-  $ yubico-piv-tool -a delete-certificate -s 9a
+  $ yubico-piv-tool -adelete-certificate -s9a -k

 Show some information on certificates and other data:

-  $ yubico-piv-tool -a status
+  $ yubico-piv-tool -astatus

 Read out the certificate from a slot and then run a signature test:

-  $ yubico-piv-tool -a read-cert -s 9a
-  $ yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
+  $ yubico-piv-tool -aread-cert -s9a
+  $ yubico-piv-tool -averify-pin -atest-signature -s9a

 Import a key into slot 85 (only available on YubiKey 4) and set the
 touch policy (also only available on YubiKey 4):

-  $ yubico-piv-tool -a import-key -s 85 --touch-policy=always -i key.pem
+  $ yubico-piv-tool -aimport-key -s85 --touch-policy=always -ikey.pem
@@ -32,10 +32,14 @@ contactless interfaces (contrary to what the specifications mandate).
 You would typically change the management key to make sure nobody but
 you can modify the state of the PIV application on the YubiKey.  Make sure to
 keep a copy of the key around for later use.
+All of these invocations will leave traces of keys and pins in the command line
+history, this can be avoided by leaving the argument out all-together and the
+software will ask for key/pin to be input. For the management key option (-k)
+this is achieved by leaving out the value but will specifying -k.

  $ key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
  $ echo $key
-  $ yubico-piv-tool -a set-mgm-key -n $key
+  $ yubico-piv-tool -aset-mgm-key -n$key

 The PIN and PUK should be changed as well.

@@ -45,37 +49,37 @@ The PIN and PUK should be changed as well.
  $ puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
  $ echo $puk

-  $ yubico-piv-tool -a change-pin -P 123456 -N $pin
-  $ yubico-piv-tool -a change-puk -P 12345678 -N $puk
+  $ yubico-piv-tool -achange-pin -P123456 -N$pin
+  $ yubico-piv-tool -achange-puk -P12345678 -N$puk

 === Other useful commands
 To generate a new private key:

-  $ yubico-piv-tool -k $key -a generate -s 9c
+  $ yubico-piv-tool -k$key -agenerate -s9c

 To reset PIN/PUK retry counter AND codes (default pin 123456 puk
 12345678):

-  $ yubico-piv-tool -k $key -a verify -P $pin -a pin-retries --pin-retries 3 --puk-retries 3
+  $ yubico-piv-tool -k$key -averify -P$pin -apin-retries --pin-retries=3 --puk-retries=3

 To reset the application (PIN/PUK need to be blocked hence trying a couple
 of times -- you need to modify this if you have changed the default
 number of PIN/PUK retries).

-  $ yubico-piv-tool -a verify-pin -P 471112
-  $ yubico-piv-tool -a verify-pin -P 471112
-  $ yubico-piv-tool -a verify-pin -P 471112
-  $ yubico-piv-tool -a verify-pin -P 471112
-  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  $ yubico-piv-tool -a change-puk -P 471112 -N 6756789
-  $ yubico-piv-tool -a reset
+  $ yubico-piv-tool -averify-pin -P471112
+  $ yubico-piv-tool -averify-pin -P471112
+  $ yubico-piv-tool -averify-pin -P471112
+  $ yubico-piv-tool -averify-pin -P471112
+  $ yubico-piv-tool -achange-puk -P471112 -N6756789
+  $ yubico-piv-tool -achange-puk -P471112 -N6756789
+  $ yubico-piv-tool -achange-puk -P471112 -N6756789
+  $ yubico-piv-tool -achange-puk -P471112 -N6756789
+  $ yubico-piv-tool -areset

 === Software
 Card management has been tested with the tools from the OpenSC
 project, specifically piv-tool, and Yubico's PIV software (see
-below).  Basic features should work with any PIV compliant 
+below).  Basic features should work with any PIV compliant
 middleware.

 * https://github.com/OpenSC/OpenSC/wiki
@@ -27,7 +27,7 @@

 option "verbose" v "Print more information" int optional default="0" argoptional
 option "reader" r "Only use a matching reader" string optional default="Yubikey"
-option "key" k "Management key to use" string optional default="010203040506070801020304050607080102030405060708" argoptional
+option "key" k "Management key to use, if no value is specified key will be asked for" string optional default="010203040506070801020304050607080102030405060708" argoptional
 option "action" a "Action to take" values="version","generate","set-mgm-key",
       "reset","pin-retries","import-key","import-certificate","set-chuid",
       "request-certificate","verify-pin","change-pin","change-puk","unblock-pin",
@@ -46,21 +46,21 @@ text   "
       82-95 is for Retired Key Management\n"
 option "algorithm" A "What algorithm to use" values="RSA1024","RSA2048","ECCP256","ECCP384" enum optional default="RSA2048"
 option "hash" H "Hash to use for signatures" values="SHA1","SHA256","SHA384","SHA512" enum optional default="SHA256"
-option "new-key" n "New management key to use for action set-mgm-key" string optional
+option "new-key" n "New management key to use for action set-mgm-key, if omitted key will be asked for" string optional
 option "pin-retries" - "Number of retries before the pin code is blocked" int optional dependon="puk-retries"
 option "puk-retries" - "Number of retries before the puk code is blocked" int optional dependon="pin-retries"
 option "input" i "Filename to use as input, - for stdin" string optional default="-"
 option "output" o "Filename to use as output, - for stdout" string optional default="-"
 option "key-format" K "Format of the key being read/written" values="PEM","PKCS12","GZIP","DER","SSH" enum optional default="PEM"
-option "password" p "Password for decryption of private key file" string optional
+option "password" p "Password for decryption of private key file, if omitted password will be asked for" string optional
 option "subject" S "The subject to use for certificate request" string optional
 text   "
       The subject must be written as:
       /CN=host.example.com/OU=test/O=example.com/\n"
 option "serial" - "Serial number of the self-signed certificate" int optional
 option "valid-days" - "Time (in days) until the self-signed certificate expires" int optional default="365"
-option "pin" P "Pin/puk code for verification" string optional
-option "new-pin" N "New pin/puk code for changing" string optional dependon="pin"
+option "pin" P "Pin/puk code for verification, if omitted pin/puk will be asked for" string optional
+option "new-pin" N "New pin/puk code for changing, if omitted pin/puk will be asked for" string optional dependon="pin"
 option "pin-policy" - "Set pin policy for action generate or import-key" values="never","once","always" enum optional
 option "touch-policy" - "Set touch policy for action generate, import-key or set-mgm-key" values="never","always","cached" enum optional
 option "id" - "Id of object for write/read object" int optional
@@ -32,55 +32,53 @@ to any command. For much more information --verbose=2 may be used.

 Display what version of the application is running on the YubiKey:

-   yubico-piv-tool -a version
+   yubico-piv-tool -aversion

 Generate a new ECC-P256 key on device in slot 9a, will print the public
 key on stdout:

-   yubico-piv-tool -s 9a -A ECCP256 -a generate
+   yubico-piv-tool -s9a -AECCP256 -agenerate

 Generate a certificate request with public key from stdin, will print
 the resulting request on stdout:

-   yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \
-     -a verify -a request
+   yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest

 Generate a self-signed certificate with public key from stdin, will print
 the certificate, for later import, on stdout:

-   yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \
-     -a verify -a selfsign
+   yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify \
+     -aselfsign

 Import a certificate from stdin:

-   yubico-piv-tool -s 9a -a import-certificate
+   yubico-piv-tool -s9a -aimport-certificate

 Set a random chuid, import a key and import a certificate from a PKCS12
-file with password test, into slot 9c:
+file, into slot 9c:

-   yubico-piv-tool -s 9c -i test.pfx -K PKCS12 -p test -a set-chuid \
-     -a import-key -a import-cert
+   yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key \
+     -aimport-cert

 Import a certificate which is larger than 2048 bytes and thus requires
 compression in order to fit:

  openssl x509 -in cert.pem -outform DER | gzip -9 > der.gz
-  yubico-piv-tool -s 9c -i der.gz -K GZIP -a import-cert
+  yubico-piv-tool -s9c -ider.gz -KGZIP -aimport-cert

 Change the management key used for administrative authentication:

-   yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \
-     -a set-mgm-key
+   yubico-piv-tool -aset-mgm-key

-Delete a certificate in slot 9a:
+Delete a certificate in slot 9a, with management key being asked for:

-  yubico-piv-tool -a delete-certificate -s 9a
+  yubico-piv-tool -adelete-certificate -s9a -k

 Show some information on certificates and other data:

-  yubico-piv-tool -a status
+  yubico-piv-tool -astatus

 Read out the certificate from a slot and then run a signature test:

-  yubico-piv-tool -a read-cert -s 9a
-  yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a
+  yubico-piv-tool -aread-cert -s9a
+  yubico-piv-tool -averify-pin -atest-signature -s9a
@@ -32,60 +32,59 @@ to any command. For much more information \-\-verbose=2 may be used.

 Display what version of the application is running on the YubiKey:

-   yubico\-piv\-tool \-a version
+   yubico\-piv\-tool \-aversion

 Generate a new ECC\-P256 key on device in slot 9a, will print the public
 key on stdout:

-   yubico\-piv\-tool \-s 9a \-A ECCP256 \-a generate
+   yubico\-piv\-tool \-s9a \-AECCP256 \-agenerate

 Generate a certificate request with public key from stdin, will print
 the resulting request on stdout:

-   yubico\-piv\-tool \-s 9a \-S '/CN=foo/OU=test/O=example.com/' \-P 123456 \\
-     \-a verify \-a request
+   yubico\-piv\-tool \-s9a \-S'/CN=foo/OU=test/O=example.com/' \-averify \\
+     \-arequest

 Generate a self\-signed certificate with public key from stdin, will print
 the certificate, for later import, on stdout:

-   yubico\-piv\-tool \-s 9a \-S '/CN=bar/OU=test/O=example.com/' \-P 123456 \\
-     \-a verify \-a selfsign
+   yubico\-piv\-tool \-s9a \-S'/CN=bar/OU=test/O=example.com/' \-averify \\
+     \-aselfsign

 Import a certificate from stdin:

-   yubico\-piv\-tool \-s 9a \-a import\-certificate
+   yubico\-piv\-tool \-s9a \-aimport\-certificate

 Set a random chuid, import a key and import a certificate from a PKCS12
-file with password test, into slot 9c:
+file, into slot 9c:

-   yubico\-piv\-tool \-s 9c \-i test.pfx \-K PKCS12 \-p test \-a set\-chuid \\
-     \-a import\-key \-a import\-cert
+   yubico\-piv\-tool \-s9c \-itest.pfx \-KPKCS12 \-aset\-chuid \\
+     \-aimport\-key \-aimport\-cert

 Import a certificate which is larger than 2048 bytes and thus requires
 compression in order to fit:

  openssl x509 \-in cert.pem \-outform DER | gzip \-9 > der.gz
-  yubico\-piv\-tool \-s 9c \-i der.gz \-K GZIP \-a import\-cert
+  yubico\-piv\-tool \-s9c \-ider.gz \-KGZIP \-aimport\-cert

 Change the management key used for administrative authentication:

-   yubico\-piv\-tool \-n 0807605403020108070605040302010807060504030201 \\
-     \-a set\-mgm\-key
+   yubico\-piv\-tool \-aset\-mgm\-key

-Delete a certificate in slot 9a:
+Delete a certificate in slot 9a, with management key being asked for:

-  yubico\-piv\-tool \-a delete\-certificate \-s 9a
+  yubico\-piv\-tool \-adelete\-certificate \-s9a \-k

 Show some information on certificates and other data:

-  yubico\-piv\-tool \-a status
+  yubico\-piv\-tool \-astatus

 Read out the certificate from a slot and then run a signature test:

-  yubico\-piv\-tool \-a read\-cert \-s 9a
-  yubico\-piv\-tool \-a verify\-pin \-P 123456 \-a test\-signature \-s 9a
+  yubico\-piv\-tool \-aread\-cert \-s9a
+  yubico\-piv\-tool \-averify\-pin \-atest\-signature \-s9a

 Import a key into slot 85 (only available on YubiKey 4) and set the
 touch policy (also only available on YubiKey 4):

-  yubico-piv-tool \-a import\-key \-s 85 \-\-touch-policy=always \-i key.pem
+  yubico-piv-tool \-aimport\-key \-s85 \-\-touch-policy=always \-ikey.pem