From d78df9ad6072c93ada9d1220a4cd92e4bfcdc335 Mon Sep 17 00:00:00 2001 From: Aveen Ismail Date: Wed, 11 Dec 2024 14:13:31 +0100 Subject: [PATCH] Docs: Update documentation --- README | 4 ++-- doc/Actions/key_generation.adoc | 5 +++-- doc/Actions/key_import.adoc | 2 +- doc/Actions/read_certificate.adoc | 2 +- doc/Actions/read_write_objects.adoc | 4 ++-- doc/Actions/reset.adoc | 29 ++++++++++++++++++++++++++++- doc/Actions/signing.adoc | 4 ++-- doc/Actions/test-decryption.adoc | 4 ++-- doc/Actions/test-signature.adoc | 4 ++-- doc/YubiKey_PIV_introduction.adoc | 11 +++++++++++ tool/cmdline.ggo | 4 ++-- tool/yubico-piv-tool.c | 7 +++++++ 12 files changed, 63 insertions(+), 17 deletions(-) diff --git a/README b/README index 5bd563b3..e14f7bf1 100644 --- a/README +++ b/README @@ -167,12 +167,12 @@ key on stdout: Generate a certificate request with public key from stdin, will print the resulting request on stdout: - $ yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify -arequest + $ yubico-piv-tool -s9a -S'/CN=foo/OU=test/O=example.com/' -averify-pin -arequest Generate a self-signed certificate with public key from stdin, will print the certificate, for later import, on stdout: - $ yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify -aselfsign + $ yubico-piv-tool -s9a -S'/CN=bar/OU=test/O=example.com/' -averify-pin -aselfsign Import a certificate from stdin: diff --git a/doc/Actions/key_generation.adoc b/doc/Actions/key_generation.adoc index abbabcd0..2aa759a2 100644 --- a/doc/Actions/key_generation.adoc +++ b/doc/Actions/key_generation.adoc @@ -32,8 +32,9 @@ verify the PIN and `-a verify-bio` for fingerprint verification. 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 | |-k, --key | X | | Management key to use, if no value is specified key will be asked for | | 010203040506070801020304050607080102030405060708 |-A, --algorithm | | X | What algorithm to use to generate the key pair | RSA1024, RSA2048, RSA3072 (Requires YubiKey 5.7 or higher), RSA4096 (Requires YubiKey 5.7 or higher), ECCP256, ECCP384, ED25519 (Requires YubiKey 5.7 or higher), X25519 (Requires YubiKey 5.7 or higher) | RSA2048 -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin. The only supported format for public key is PEM | None or file name | Stdin +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout +|-K, --key-format | | X | Format of the certificate to import. Note that the public key must be in PEM format | PEM, PKCS12, GZIP, DER | PEM |-S, --subject |X| | The subject to use for the certificate. The subject must be written as: /CN=host.example.com/OU=test/O=example.com/ | | |-P, --pin | | X | Pin/puk code for verification, if omitted pin/puk will be asked for | | |--pin-policy | | | Set pin policy applicable for the slot containing the key. Only available on YubiKey 4 or newer | never, once, always, matchonce (applicable with bio verification), matchalways (applicable for with verification) | `always` on slot 9c and `once` on slots 9a, 9d and 9e diff --git a/doc/Actions/key_import.adoc b/doc/Actions/key_import.adoc index 6d194c6b..88f9ac7a 100644 --- a/doc/Actions/key_import.adoc +++ b/doc/Actions/key_import.adoc @@ -25,7 +25,7 @@ management key before start using it.] |-s, --slot | X | | What key slot to operate on | 9a, 9c, 9d, 9e, 82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 | |-k, --key | X | | Management key to use, if no value is specified key will be asked for | | 010203040506070801020304050607080102030405060708 -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin | None or file name | Stdin |-K, --key-format | | X | Format of the key/certificate being read/written | PEM, PKCS12, GZIP, DER, SSH | PEM |-p, --password | | X | Password for decryption of private key file, if omitted password will be asked for | | |-P, --pin | | X | Pin/puk code for verification, if omitted pin/puk will be asked for | | diff --git a/doc/Actions/read_certificate.adoc b/doc/Actions/read_certificate.adoc index cdaab583..2f852a2a 100644 --- a/doc/Actions/read_certificate.adoc +++ b/doc/Actions/read_certificate.adoc @@ -11,7 +11,7 @@ Returns the certificate stored on a certain slot. |-s, --slot | X | | What key slot to operate on | 9a, 9c, 9d, 9e, 82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 | -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout |-K, --key-format | | X | Format of the key/certificate being read/written | PEM, PKCS12, GZIP, DER, SSH | PEM |=================================== diff --git a/doc/Actions/read_write_objects.adoc b/doc/Actions/read_write_objects.adoc index b409fe24..8de05928 100644 --- a/doc/Actions/read_write_objects.adoc +++ b/doc/Actions/read_write_objects.adoc @@ -58,8 +58,8 @@ footnote:[It is strongly recommended to change the Yubikey's PIN, PUK and manage |--id | X | | The ID of the object to write/read according to PIV Specifications | | |-k, --key | X | | Management key to use, if no value is specified key will be asked for | | 010203040506070801020304050607080102030405060708 -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin | None or file name | Stdin +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout |-f, --format | | X | Format of data for write/read object | hex, base64, binary | hex |=================================== diff --git a/doc/Actions/reset.adoc b/doc/Actions/reset.adoc index 8c8348cc..b2f40f68 100644 --- a/doc/Actions/reset.adoc +++ b/doc/Actions/reset.adoc @@ -3,9 +3,36 @@ === Description Erases all keys and certificates stored on the device and sets it to the default PIN, -PUK and management key. This will only affect the PIV portion of the YubiKey, so any +PUK and management key. This will only affect the PIV application on the YubiKey, so any non-PIV configuration will remain intact. Resetting the device will not erase the attestation key and certificate (slot f9) either, but they can be overwritten. To reset the device, the PIN and the PUK need to be blocked, which happens when entering the wrong PIN and PUK more than the number of their retries. + +==== Global Reset + +Some YubiKeys with firmware version 5.7.0 or higher have support for a global support option. This option will erase +all data on the YubiKey and is *not* restricted to the PIV application. It also does not require that the PIN and PUK +to be blocked. + +Note that the global reset option cannot be used if SCP11 is activated. + +|=================================== +|Parameter | Required | Description | Default value +|--global | | Reset the whole device over all applications, including the PIV application | Off +|=================================== + +=== Examples + + $ 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 + + $ yubico-piv-tool -areset --global \ No newline at end of file diff --git a/doc/Actions/signing.adoc b/doc/Actions/signing.adoc index 9a8f3945..894e888f 100644 --- a/doc/Actions/signing.adoc +++ b/doc/Actions/signing.adoc @@ -18,8 +18,8 @@ Use `-a verify-pin` to verify the PIN and `-a verify-bio` for fingerprint verifi |-A, --algorithm | | X | Signing key algorithm | RSA1024, RSA2048, RSA3072 (Requires YubiKey 5.7 or higher), RSA4096 (Requires YubiKey 5.7 or higher), ECCP256, ECCP384, ED25519 (Requires YubiKey 5.7 or higher) | RSA2048 |-H, --hash | | X | Hash to use for signatures | SHA1, SHA256, SHA384, SHA512 | SHA256 |-P, --pin | | X | Pin/puk code for verification, if omitted pin/puk will be asked for | | -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin | None or file name | Stdin +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout |=================================== === Examples diff --git a/doc/Actions/test-decryption.adoc b/doc/Actions/test-decryption.adoc index 95fc96e2..f8a15fda 100644 --- a/doc/Actions/test-decryption.adoc +++ b/doc/Actions/test-decryption.adoc @@ -20,8 +20,8 @@ done using the "read-certificate" action first. |-s, --slot | X | | What key slot to operate on | 9a, 9c, 9d, 9e, 82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 | |-P, --pin | | X | Pin/puk code for verification, if omitted pin/puk will be asked for | | -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin | None or file name | Stdin +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout |=================================== === Examples diff --git a/doc/Actions/test-signature.adoc b/doc/Actions/test-signature.adoc index 86a783b4..73943816 100644 --- a/doc/Actions/test-signature.adoc +++ b/doc/Actions/test-signature.adoc @@ -20,8 +20,8 @@ done using the "read-certificate" action first. |-s, --slot | X | | What key slot to operate on | 9a, 9c, 9d, 9e, 82, 83, 84, 85, 86, 87, 88, 89, 8a, 8b, 8c, 8d, 8e, 8f, 90, 91, 92, 93, 94, 95, f9 | |-P, --pin | | X | Pin/puk code for verification, if omitted pin/puk will be asked for | | -|-i, --input | | X | Filename to use as input | file name or "-" for stdin | - -|-o, --output | | X | Filename to use as output | file name or "-" for stdin | - +|-i, --input | | X | Filename to use as input. If left out, input will be read from Stdin | None or file name | Stdin +|-o, --output | | X | Filename to use as output. If left out, output will be printed to Stdout | None or file name | Stdout |=================================== === Examples diff --git a/doc/YubiKey_PIV_introduction.adoc b/doc/YubiKey_PIV_introduction.adoc index 1d56f48d..6f99ed3b 100644 --- a/doc/YubiKey_PIV_introduction.adoc +++ b/doc/YubiKey_PIV_introduction.adoc @@ -57,6 +57,17 @@ The PIN and PUK should be changed as well. $ yubico-piv-tool -achange-pin -P123456 -N${pin} $ yubico-piv-tool -achange-puk -P12345678 -N${puk} +=== Secure Channel Protocol 11 (SCP11) + +Some YubiKeys with firmware version 5.7.0 and higher have support for communicating over a secure channel. Yubico PIV +Tool implements the *SCP11b* protocol as specified in https://globalplatform.org/wp-content/uploads/2017/09/GPC_2.2_F_SCP11_v1.0.pdf +and can be activated by adding the `--scp11` flag in the command line tool or open a connection with `scp11` on when +using `libykpiv` during development. Once SCP11 is activated, all subsequent communication over the same session will +be encrypted. Note that the SCP11b implementation entails that the communication is encrypted but the On-Card +certificate (`CERT.SD.ECKA`) used to setup the encrypted session is not validated. The feature is used mainly to protect +sensitive communication between the host and the YubiKey against monitoring over a medium which could potentially be +eavesdropped on, such as NFC. + === Other useful commands To generate a new private key: diff --git a/tool/cmdline.ggo b/tool/cmdline.ggo index fb291c0b..9e542ea1 100644 --- a/tool/cmdline.ggo +++ b/tool/cmdline.ggo @@ -62,7 +62,7 @@ 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 "compress" - "Compress a large certificate using GZIP before import" flag off -option "global" - "Reset the whole device over all protocols" flag off +option "global" - "Reset the whole device over all applications" flag off 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 " @@ -81,4 +81,4 @@ option "stdin-input" - "Read sensitive values from stdin" flag off hidden option "attestation" - "Add attestation cross-signature" flag off option "new-key-algo" m "New management key algorithm to use for action set-mgm-key" values="TDES","AES128","AES192","AES256" enum optional default="TDES" -option "scp11" - "Use Secure Channel authentication" flag off \ No newline at end of file +option "scp11" - "Use encrypted communication as specified by Secure Channel Protocol 11 (SCP11b)" flag off \ No newline at end of file diff --git a/tool/yubico-piv-tool.c b/tool/yubico-piv-tool.c index 124d9524..0428a835 100644 --- a/tool/yubico-piv-tool.c +++ b/tool/yubico-piv-tool.c @@ -443,6 +443,8 @@ static bool reset(ykpiv_state *state, bool global) { if (rc == YKPIV_NOT_SUPPORTED) { fprintf(stderr, "Global reset not supported on this YubiKey. Please refer to reset commands for specific applications instead\n"); + } else if(rc == YKPIV_ARGUMENT_ERROR) { + fprintf(stderr, "Reset failed, is 'scp11' flag used?\n"); } else { fprintf(stderr, "Reset failed\n"); } @@ -2441,6 +2443,11 @@ int main(int argc, char *argv[]) { fprintf(stderr, "Warning, unable to reset locale\n"); } + if (argc < 2) { + fprintf(stderr, "No actions detected. Use '--help' or '-h' for command manpage\n"); + return EXIT_FAILURE; + } + if(cmdline_parser(argc, argv, &args_info) != 0) { return EXIT_FAILURE; }