james/yubikey.rs
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
also update all examples to have no space after short option.
This commit is contained in:
Klas Lindfors
2017-04-19 13:54:24 +02:00
parent a7ef1315f4
commit 9dfe04cd06
5 changed files with 72 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README
+14 -17
View File
@@ -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 Generate a new ECC-P256 key on device in slot 9a, will print the public
key on stdout: 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 Generate a certificate request with public key from stdin, will print
the resulting request on stdout: the resulting request on stdout:
$ yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \ $ yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest
-a verify -a request
Generate a self-signed certificate with public key from stdin, will print Generate a self-signed certificate with public key from stdin, will print
the certificate, for later import, on stdout: the certificate, for later import, on stdout:
$ yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \ $ yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify -aselfsign
-a verify -a selfsign
Import a certificate from stdin: 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 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 \ $ yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key \
-a import-key -a import-cert -aimport-cert
Change the management key used for administrative authentication: Change the management key used for administrative authentication:
$ yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \ $ yubico-piv-tool -aset-mgm-key
-a set-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: 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: Read out the certificate from a slot and then run a signature test:
$ yubico-piv-tool -a read-cert -s 9a $ yubico-piv-tool -aread-cert -s9a
$ yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a $ yubico-piv-tool -averify-pin -atest-signature -s9a
Import a key into slot 85 (only available on YubiKey 4) and set the Import a key into slot 85 (only available on YubiKey 4) and set the
touch policy (also only available on YubiKey 4): 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
doc/YubiKey_PIV_introduction.adoc
+19 -15
View File
@@ -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 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 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. 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"'` $ key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
$ echo $key $ 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. 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` $ puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
$ echo $puk $ echo $puk
$ yubico-piv-tool -a change-pin -P 123456 -N $pin $ yubico-piv-tool -achange-pin -P123456 -N$pin
$ yubico-piv-tool -a change-puk -P 12345678 -N $puk $ yubico-piv-tool -achange-puk -P12345678 -N$puk
=== Other useful commands === Other useful commands
To generate a new private key: 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 To reset PIN/PUK retry counter AND codes (default pin 123456 puk
12345678): 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 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 of times -- you need to modify this if you have changed the default
number of PIN/PUK retries). number of PIN/PUK retries).
$ yubico-piv-tool -a verify-pin -P 471112 $ yubico-piv-tool -averify-pin -P471112
$ yubico-piv-tool -a verify-pin -P 471112 $ yubico-piv-tool -averify-pin -P471112
$ yubico-piv-tool -a verify-pin -P 471112 $ yubico-piv-tool -averify-pin -P471112
$ yubico-piv-tool -a verify-pin -P 471112 $ yubico-piv-tool -averify-pin -P471112
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789 $ yubico-piv-tool -achange-puk -P471112 -N6756789
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789 $ yubico-piv-tool -achange-puk -P471112 -N6756789
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789 $ yubico-piv-tool -achange-puk -P471112 -N6756789
$ yubico-piv-tool -a change-puk -P 471112 -N 6756789 $ yubico-piv-tool -achange-puk -P471112 -N6756789
$ yubico-piv-tool -a reset $ yubico-piv-tool -areset
=== Software === Software
Card management has been tested with the tools from the OpenSC Card management has been tested with the tools from the OpenSC
project, specifically piv-tool, and Yubico's PIV software (see 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. middleware.
* https://github.com/OpenSC/OpenSC/wiki * https://github.com/OpenSC/OpenSC/wiki
tool/cmdline.ggo
+5 -5
View File
@@ -27,7 +27,7 @@
option "verbose" v "Print more information" int optional default="0" argoptional option "verbose" v "Print more information" int optional default="0" argoptional
option "reader" r "Only use a matching reader" string optional default="Yubikey" 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", option "action" a "Action to take" values="version","generate","set-mgm-key",
"reset","pin-retries","import-key","import-certificate","set-chuid", "reset","pin-retries","import-key","import-certificate","set-chuid",
"request-certificate","verify-pin","change-pin","change-puk","unblock-pin", "request-certificate","verify-pin","change-pin","change-puk","unblock-pin",
@@ -46,21 +46,21 @@ text "
82-95 is for Retired Key Management\n" 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 "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 "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 "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 "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 "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 "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 "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 option "subject" S "The subject to use for certificate request" string optional
text " text "
The subject must be written as: The subject must be written as:
/CN=host.example.com/OU=test/O=example.com/\n" /CN=host.example.com/OU=test/O=example.com/\n"
option "serial" - "Serial number of the self-signed certificate" int optional 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 "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 "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" string optional dependon="pin" 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 "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 "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 option "id" - "Id of object for write/read object" int optional
tool/yubico-piv-tool.adoc
+16 -18
View File
@@ -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: 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 Generate a new ECC-P256 key on device in slot 9a, will print the public
key on stdout: 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 Generate a certificate request with public key from stdin, will print
the resulting request on stdout: the resulting request on stdout:
yubico-piv-tool -s 9a -S '/CN=foo/OU=test/O=example.com/' -P 123456 \ yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest
-a verify -a request
Generate a self-signed certificate with public key from stdin, will print Generate a self-signed certificate with public key from stdin, will print
the certificate, for later import, on stdout: the certificate, for later import, on stdout:
yubico-piv-tool -s 9a -S '/CN=bar/OU=test/O=example.com/' -P 123456 \ yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify \
-a verify -a selfsign -aselfsign
Import a certificate from stdin: 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 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 \ yubico-piv-tool -s9c -itest.pfx -KPKCS12 -aset-chuid -aimport-key \
-a import-key -a import-cert -aimport-cert
Import a certificate which is larger than 2048 bytes and thus requires Import a certificate which is larger than 2048 bytes and thus requires
compression in order to fit: compression in order to fit:
openssl x509 -in cert.pem -outform DER | gzip -9 > der.gz 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: Change the management key used for administrative authentication:
yubico-piv-tool -n 0807605403020108070605040302010807060504030201 \ yubico-piv-tool -aset-mgm-key
-a set-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: 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: Read out the certificate from a slot and then run a signature test:
yubico-piv-tool -a read-cert -s 9a yubico-piv-tool -aread-cert -s9a
yubico-piv-tool -a verify-pin -P 123456 -a test-signature -s 9a yubico-piv-tool -averify-pin -atest-signature -s9a
tool/yubico-piv-tool.h2m
+18 -19
View File
@@ -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: 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 Generate a new ECC\-P256 key on device in slot 9a, will print the public
key on stdout: 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 Generate a certificate request with public key from stdin, will print
the resulting request on stdout: the resulting request on stdout:
yubico\-piv\-tool \-s 9a \-S '/CN=foo/OU=test/O=example.com/' \-P 123456 \\ yubico\-piv\-tool \-s9a \-S'/CN=foo/OU=test/O=example.com/' \-averify \\
\-a verify \-a request \-arequest
Generate a self\-signed certificate with public key from stdin, will print Generate a self\-signed certificate with public key from stdin, will print
the certificate, for later import, on stdout: the certificate, for later import, on stdout:
yubico\-piv\-tool \-s 9a \-S '/CN=bar/OU=test/O=example.com/' \-P 123456 \\ yubico\-piv\-tool \-s9a \-S'/CN=bar/OU=test/O=example.com/' \-averify \\
\-a verify \-a selfsign \-aselfsign
Import a certificate from stdin: 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 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 \\ yubico\-piv\-tool \-s9c \-itest.pfx \-KPKCS12 \-aset\-chuid \\
\-a import\-key \-a import\-cert \-aimport\-key \-aimport\-cert
Import a certificate which is larger than 2048 bytes and thus requires Import a certificate which is larger than 2048 bytes and thus requires
compression in order to fit: compression in order to fit:
openssl x509 \-in cert.pem \-outform DER | gzip \-9 > der.gz 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: Change the management key used for administrative authentication:
yubico\-piv\-tool \-n 0807605403020108070605040302010807060504030201 \\ yubico\-piv\-tool \-aset\-mgm\-key
\-a set\-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: 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: Read out the certificate from a slot and then run a signature test:
yubico\-piv\-tool \-a read\-cert \-s 9a yubico\-piv\-tool \-aread\-cert \-s9a
yubico\-piv\-tool \-a verify\-pin \-P 123456 \-a test\-signature \-s 9a yubico\-piv\-tool \-averify\-pin \-atest\-signature \-s9a
Import a key into slot 85 (only available on YubiKey 4) and set the Import a key into slot 85 (only available on YubiKey 4) and set the
touch policy (also only available on YubiKey 4): 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