@c card-tool.texi - man page for gpg-card-tool @c Copyright (C) 2019 g10 Code GmbH @c This is part of the GnuPG manual. @c For copying conditions, see the file GnuPG.texi. @include defs.inc @node Smart Card Tool @chapter Smart Card Tool GnuPG comes with a tool to administrate smart cards and USB tokens. This tool is an enhanced version of the @option{--edit-key} command available with @command{gpg}. @menu * gpg-card:: Administrate smart cards. @end menu @c @c GPG-CARD-TOOL @c @manpage gpg-card.1 @node gpg-card @section Administrate smart cards. @ifset manverb .B gpg-card \- Administrate Smart Cards @end ifset @mansect synopsis @ifset manverb .B gpg-card .RI [ options ] .br .B gpg-card .RI [ options ] .I command .RI { .B -- .I command .RI } @end ifset @mansect description The @command{gpg-card} is used to administrate smart cards and USB tokens. It provides a superset of features from @command{gpg --card-edit} an can be considered a frontend to @command{scdaemon} which is a daemon started by @command{gpg-agent} to handle smart cards. If @command{gpg-card} is invoked without commands an interactive mode is used. If @command{gpg-card} is invoked with one or more commands the same commands as available in the interactive mode are run from the command line. These commands need to be delimited with a double-dash. If a double-dash or a shell specific character is required as part of a command the entire command needs to be put in quotes. If one of those commands returns an error the remaining commands are not anymore run unless the command was prefixed with a single dash. A list of commands is available by using the command @code{help} and a detailed description of each command is printed by using @code{help COMMAND}. See the NOTES sections for instructions pertaining to specific cards or card applications. @mansect options @noindent @command{gpg-card} understands these options: @table @gnupgtabopt @item --with-colons @opindex with-colons This option has currently no effect. @item --status-fd @var{n} @opindex status-fd Write special status strings to the file descriptor @var{n}. This program returns only the status messages SUCCESS or FAILURE which are helpful when the caller uses a double fork approach and can't easily get the return code of the process. @item --verbose @opindex verbose Enable extra informational output. @item --quiet @opindex quiet Disable almost all informational output. @item --version @opindex version Print version of the program and exit. @item --help @opindex help Display a brief help page and exit. @item --no-autostart @opindex no-autostart Do not start the gpg-agent if it has not yet been started and its service is required. This option is mostly useful on machines where the connection to gpg-agent has been redirected to another machines. @item --agent-program @var{file} @opindex agent-program Specify the agent program to be started if none is running. The default value is determined by running @command{gpgconf} with the option @option{--list-dirs}. @item --gpg-program @var{file} @opindex gpg-program Specify a non-default gpg binary to be used by certain commands. @item --gpgsm-program @var{file} @opindex gpgsm-program Specify a non-default gpgsm binary to be used by certain commands. @end table @mansect notes (OpenPGP) The support for OpenPGP cards in @command{gpg-card} is not yet complete. For missing features, please continue to use @code{gpg --card-edit}. @mansect notes (PIV) @noindent GnuPG has support for PIV cards (``Personal Identity Verification'' as specified by NIST Special Publication 800-73-4). This section describes how to initialize (personalize) a fresh Yubikey token featuring the PIV application (requires Yubikey-5). We assume that the credentials have not yet been changed and thus are: @table @asis @item Authentication key This is a 24 byte key described by the hex string @* @code{010203040506070801020304050607080102030405060708}. @item PIV Application PIN This is the string @code{123456}. @item PIN Unblocking Key This is the string @code{12345678}. @end table See the example section on how to change these defaults. For production use it is important to use secure values for them. Note that the Authentication Key is not queried via the usual Pinentry dialog but needs to be entered manually or read from a file. The use of a dedicated machine to personalize tokens is strongly suggested. To see what is on the card, the command @code{list} can be given. We will use the interactive mode in the following (the string @emph{gpg/card>} is the prompt). An example output for a fresh card is: @example gpg/card> list Reader ...........: 1050:0407:X:0 Card type ........: yubikey Card firmware ....: 5.1.2 Serial number ....: D2760001240102010006090746250000 Application type .: OpenPGP Version ..........: 2.1 [...] @end example It can be seen by the ``Application type'' line that GnuPG selected the OpenPGP application of the Yubikey. This is because GnuPG assigns the highest priority to the OpenPGP application. To use the PIV application of the Yubikey several methods can be used: With a Yubikey 5 or later the OpenPGP application on the Yubikey can be disabled: @example gpg/card> yubikey disable all opgp gpg/card> yubikey list Application USB NFC ----------------------- OTP yes yes U2F yes yes OPGP no no PIV yes no OATH yes yes FIDO2 yes yes gpg/card> reset @end example The @code{reset} is required so that the GnuPG system rereads the card. Note that disabled applications keep all their data and can at any time be re-enabled (use @kbd{help yubikey}). Another option, which works for all Yubikey versions, is to disable the support for OpenPGP cards in scdaemon. This is done by adding the line @smallexample disable-application openpgp @end smallexample to @file{~/.gnupg/scdaemon.conf} and by restarting scdaemon, either by killing the process or by using @kbd{gpgconf --kill scdaemon}. Finally the default order in which card applications are tried by scdaemon can be changed. For example to prefer PIV over OpenPGP it is sufficient to add @smallexample application-priority piv @end smallexample to @file{~/.gnupg/scdaemon.conf} and to restart @command{scdaemon}. This has an effect only on tokens which support both, PIV and OpenPGP, but does not hamper the use of OpenPGP only tokens. With one of these methods employed the @code{list} command of @command{gpg-card} shows this: @example gpg/card> list Reader ...........: 1050:0407:X:0 Card type ........: yubikey Card firmware ....: 5.1.2 Serial number ....: FF020001008A77C1 Application type .: PIV Version ..........: 1.0 Displayed s/n ....: yk-9074625 PIN usage policy .: app-pin PIN retry counter : - 3 - PIV authentication: [none] keyref .....: PIV.9A Card authenticat. : [none] keyref .....: PIV.9E Digital signature : [none] keyref .....: PIV.9C Key management ...: [none] keyref .....: PIV.9D @end example In case several tokens are plugged into the computer, gpg-card will show only one. To show another token the number of the token (0, 1, 2, ...) can be given as an argument to the @code{list} command. The command @kbd{list --cards} prints a list of all inserted tokens. Note that the ``Displayed s/n'' is printed on the token and also shown in Pinentry prompts asking for the PIN. The four standard key slots are always shown, if other key slots are initialized they are shown as well. The @emph{PIV authentication} key (internal reference @emph{PIV.9A}) is used to authenticate the card and the card holder. The use of the associated private key is protected by the Application PIN which needs to be provided once and the key can the be used until the card is reset or removed from the reader or USB port. GnuPG uses this key with its @emph{Secure Shell} support. The @emph{Card authentication} key (@emph{PIV.9E}) is also known as the CAK and used to support physical access applications. The private key is not protected by a PIN and can thus immediately be used. The @emph{Digital signature} key (@emph{PIV.9C}) is used to digitally sign documents. The use of the associated private key is protected by the Application PIN which needs to be provided for each signing operation. The @emph{Key management} key (@emph{PIV.9D}) is used for encryption. The use of the associated private key is protected by the Application PIN which needs to be provided only once so that decryption operations can then be done until the card is reset or removed from the reader or USB port. We now generate three of the four keys. Note that GnuPG does currently not use the the @emph{Card authentication} key; however, that key is mandatory by the PIV standard and thus we create it too. Key generation requires that we authenticate to the card. This can be done either on the command line (which would reveal the key): @example gpg/card> auth 010203040506070801020304050607080102030405060708 @end example or by reading the key from a file. That file needs to consist of one LF terminated line with the hex encoded key (as above): @example gpg/card> auth < myauth.key @end example As usual @samp{help auth} gives help for this command. An error message is printed if a non-matching key is used. The authentication is valid until a reset of the card or until the card is removed from the reader or the USB port. Note that that in non-interactive mode the @samp{<} needs to be quoted so that the shell does not interpret it as a its own redirection symbol. @noindent Here are the actual commands to generate the keys: @example gpg/card> generate --algo=nistp384 PIV.9A PIV card no. yk-9074625 detected gpg/card> generate --algo=nistp256 PIV.9E PIV card no. yk-9074625 detected gpg/card> generate --algo=rsa2048 PIV.9C PIV card no. yk-9074625 detected @end example If a key has already been created for one of the slots an error will be printed; to create a new key anyway the option @samp{--force} can be used. Note that only the private and public keys have been created but no certificates are stored in the key slots. In fact, GnuPG uses its own non-standard method to store just the public key in place of the the certificate. Other application will not be able to make use these keys until @command{gpgsm} or another tool has been used to create and store the respective certificates. Let us see what the list command now shows: @example gpg/card> list Reader ...........: 1050:0407:X:0 Card type ........: yubikey Card firmware ....: 5.1.2 Serial number ....: FF020001008A77C1 Application type .: PIV Version ..........: 1.0 Displayed s/n ....: yk-9074625 PIN usage policy .: app-pin PIN retry counter : - 3 - PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E keyref .....: PIV.9A (auth) algorithm ..: nistp384 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C keyref .....: PIV.9E (auth) algorithm ..: nistp256 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED keyref .....: PIV.9C (sign,cert) algorithm ..: rsa2048 Key management ...: [none] keyref .....: PIV.9D @end example The primary information for each key is the @emph{keygrip}, a 40 byte hex-string identifying the key. This keygrip is a unique identifier for the specific parameters of a key. It is used by @command{gpg-agent} and other parts of GnuPG to associate a private key to its protocol specific certificate format (X.509, OpenPGP, or SecureShell). Below the keygrip the key reference along with the key usage capabilities are show. Finally the algorithm is printed in the format used by @command {gpg}. At that point no other information is shown because for these new keys gpg won't be able to find matching certificates. Although we could have created the @emph{Key management} key also with the generate command, we will create that key off-card so that a backup exists. To accomplish this a key needs to be created with either @command{gpg} or @command{gpgsm} or imported in one of these tools. In our example we create a self-signed X.509 certificate (exit the gpg-card tool, first): @example $ gpgsm --gen-key -o encr.crt (1) RSA (2) Existing key (3) Existing key from card Your selection? 1 What keysize do you want? (3072) 2048 Requested keysize is 2048 bits Possible actions for a RSA key: (1) sign, encrypt (2) sign (3) encrypt Your selection? 3 Enter the X.509 subject name: CN=Encryption key for yk-9074625,O=example,C=DE Enter email addresses (end with an empty line): > otto@@example.net > Enter DNS names (optional; end with an empty line): > Enter URIs (optional; end with an empty line): > Create self-signed certificate? (y/N) y These parameters are used: Key-Type: RSA Key-Length: 2048 Key-Usage: encrypt Serial: random Name-DN: CN=Encryption key for yk-9074625,O=example,C=DE Name-Email: otto@@example.net Proceed with creation? (y/N) Now creating self-signed certificate. This may take a while ... gpgsm: about to sign the certificate for key: &34798AAFE0A7565088101CC4AE31C5C8C74461CB gpgsm: certificate created Ready. $ gpgsm --import encr.crt gpgsm: certificate imported gpgsm: total number processed: 1 gpgsm: imported: 1 @end example Note the last step which imported the created certificate. If you you instead created a certificate signing request (CSR) instead of a self-signed certificate and sent this off to a CA you would do the same import step with the certificate received from the CA. Take note of the keygrip (prefixed with an ampersand) as shown during the certificate creation or listed it again using @samp{gpgsm --with-keygrip -k otto@@example.net}. Now to move the key and certificate to the card start @command{gpg-card} again and enter: @example gpg/card> writekey PIV.9D 34798AAFE0A7565088101CC4AE31C5C8C74461CB gpg/card> writecert PIV.9D < encr.crt @end example If you entered a passphrase to protect the private key, you will be asked for it via the Pinentry prompt. On success the key and the certificate has been written to the card and a @code{list} command shows: @example [...] Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB keyref .....: PIV.9D (encr) algorithm ..: rsa2048 used for ...: X.509 user id ..: CN=Encryption key for yk-9074625,O=example,C=DE user id ..: @end example In case the same key (identified by the keygrip) has been used for several certificates you will see several ``used for'' parts. With this the encryption key is now fully functional and can be used to decrypt messages encrypted to this certificate. @sc{Take care:} the original key is still stored on-disk and should be moved to a backup medium. This can simply be done by copying the file @file{34798AAFE0A7565088101CC4AE31C5C8C74461CB.key} from the directory @file{~/.gnupg/private-keys-v1.d/} to the backup medium and deleting the file at its original place. The final example is to create a self-signed certificate for digital signatures. Leave @command{gpg-card} using @code{quit} or by pressing Control-D and use gpgsm: @example $ gpgsm --learn $ gpgsm --gen-key -o sign.crt Please select what kind of key you want: (1) RSA (2) Existing key (3) Existing key from card Your selection? 3 Serial number of the card: FF020001008A77C1 Available keys: (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 Your selection? 3 Possible actions for a RSA key: (1) sign, encrypt (2) sign (3) encrypt Your selection? 2 Enter the X.509 subject name: CN=Signing key for yk-9074625,O=example,C=DE Enter email addresses (end with an empty line): > otto@@example.net > Enter DNS names (optional; end with an empty line): > Enter URIs (optional; end with an empty line): > Create self-signed certificate? (y/N) These parameters are used: Key-Type: card:PIV.9C Key-Length: 1024 Key-Usage: sign Serial: random Name-DN: CN=Signing key for yk-9074625,O=example,C=DE Name-Email: otto@@example.net Proceed with creation? (y/N) y Now creating self-signed certificate. This may take a while ... gpgsm: about to sign the certificate for key: &32A6C6FAFCB8421878608AAB452D5470DD3223ED gpgsm: certificate created Ready. $ gpgsm --import sign.crt gpgsm: certificate imported gpgsm: total number processed: 1 gpgsm: imported: 1 @end example The use of @samp{gpgsm --learn} is currently necessary so that gpg-agent knows what keys are available on the card. The need for this command will eventually be removed. The remaining commands are similar to the creation of an on-disk key. However, here we select the @samp{Digital signature} key. During the creation process you will be asked for the Application PIN of the card. The final step is to write the certificate to the card using @command{gpg-card}: @example gpg/card> writecert PIV.9C < sign.crt @end example By running list again we will see the fully initialized card: @example Reader ...........: 1050:0407:X:0 Card type ........: yubikey Card firmware ....: 5.1.2 Serial number ....: FF020001008A77C1 Application type .: PIV Version ..........: 1.0 Displayed s/n ....: yk-9074625 PIN usage policy .: app-pin PIN retry counter : - [verified] - PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E keyref .....: PIV.9A (auth) algorithm ..: nistp384 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C keyref .....: PIV.9E (auth) algorithm ..: nistp256 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED keyref .....: PIV.9C (sign,cert) algorithm ..: rsa2048 used for ...: X.509 user id ..: CN=Signing key for yk-9074625,O=example,C=DE user id ..: Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB keyref .....: PIV.9D (encr) algorithm ..: rsa2048 used for ...: X.509 user id ..: CN=Encryption key for yk-9074625,O=example,C=DE user id ..: @end example It is now possible to sign and to encrypt with this card using gpgsm and to use the @samp{PIV authentication} key with ssh: @example $ ssh-add -l 384 SHA256:0qnJ0Y0ehWxKcx2frLfEljf6GCdlO55OZed5HqGHsaU cardno:yk-9074625 (ECDSA) @end example As usual use ssh-add with the uppercase @samp{-L} to list the public ssh key. To use the certificates with Thunderbird or Mozilla, please consult the Scute manual for details. If you want to use the same PIV keys also for OpenPGP (for example on a Yubikey to avoid switching between OpenPGP and PIV), this is also possible: @example $ gpgsm --learn $ gpg --full-gen-key Please select what kind of key you want: (1) RSA and RSA (default) (2) DSA and Elgamal (3) DSA (sign only) (4) RSA (sign only) (14) Existing key from card Your selection? 14 Serial number of the card: FF020001008A77C1 Available keys: (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth) (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth) (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign) (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr) Your selection? 3 Please specify how long the key should be valid. 0 = key does not expire = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) Key does not expire at all Is this correct? (y/N) y GnuPG needs to construct a user ID to identify your key. Real name: Email address: otto@@example.net Comment: You selected this USER-ID: "otto@@example.net" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o gpg: key C3AFA9ED971BB365 marked as ultimately trusted gpg: revocation certificate stored as '[...]D971BB365.rev' public and secret key created and signed. Note that this key cannot be used for encryption. You may want to use the command "--edit-key" to generate a subkey for this purpose. pub rsa2048 2019-04-04 [SC] 7F899AE2FB73159DD68A1B20C3AFA9ED971BB365 uid otto@@example.net @end example Note that you will be asked two times to enter the PIN of your PIV card. If you run @command{gpg} in @option{--expert} mode you will also ge given the option to change the usage flags of the key. The next typescript shows how to add the encryption subkey: @example $ gpg --edit-key 7F899AE2FB73159DD68A1B20C3AFA9ED971BB365 Secret key is available. sec rsa2048/C3AFA9ED971BB365 created: 2019-04-04 expires: never usage: SC card-no: FF020001008A77C1 trust: ultimate validity: ultimate [ultimate] (1). otto@@example.net gpg> addkey Secret parts of primary key are stored on-card. Please select what kind of key you want: (3) DSA (sign only) (4) RSA (sign only) (5) Elgamal (encrypt only) (6) RSA (encrypt only) (14) Existing key from card Your selection? 14 Serial number of the card: FF020001008A77C1 Available keys: (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth) (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth) (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign) (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr) Your selection? 4 Please specify how long the key should be valid. 0 = key does not expire = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) Key does not expire at all Is this correct? (y/N) y Really create? (y/N) y sec rsa2048/C3AFA9ED971BB365 created: 2019-04-04 expires: never usage: SC card-no: FF020001008A77C1 trust: ultimate validity: ultimate ssb rsa2048/7067860A98FCE6E1 created: 2019-04-04 expires: never usage: E card-no: FF020001008A77C1 [ultimate] (1). otto@@example.net gpg> save @end example Now you can use your PIV card also with @command{gpg}. @c @mansect examples @mansect see also @ifset isman @command{scdaemon}(1) @end ifset