diff --git a/README b/README index b0ac4a8..d571154 100644 --- a/README +++ b/README @@ -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 diff --git a/doc/YubiKey_PIV_introduction.adoc b/doc/YubiKey_PIV_introduction.adoc index 61c464f..793136e 100644 --- a/doc/YubiKey_PIV_introduction.adoc +++ b/doc/YubiKey_PIV_introduction.adoc @@ -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 diff --git a/tool/cmdline.ggo b/tool/cmdline.ggo index 48dc1b6..c533ba6 100644 --- a/tool/cmdline.ggo +++ b/tool/cmdline.ggo @@ -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 diff --git a/tool/yubico-piv-tool.adoc b/tool/yubico-piv-tool.adoc index 420942c..fec3e0b 100644 --- a/tool/yubico-piv-tool.adoc +++ b/tool/yubico-piv-tool.adoc @@ -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 diff --git a/tool/yubico-piv-tool.h2m b/tool/yubico-piv-tool.h2m index ac5279a..9f60beb 100644 --- a/tool/yubico-piv-tool.h2m +++ b/tool/yubico-piv-tool.h2m @@ -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