doc/gpg-card.texi

   1 @c card-tool.texi - man page for gpg-card-tool
   2 @c Copyright (C) 2019 g10 Code GmbH
   3 @c This is part of the GnuPG manual.
   4 @c For copying conditions, see the file GnuPG.texi.
   5
   6 @include defs.inc
   7
   8 @node Smart Card Tool
   9 @chapter Smart Card Tool
  10
  11 GnuPG comes with a tool to administrate smart cards and USB tokens.
  12 This tool is an enhanced version of the @option{--edit-key} command
  13 available with @command{gpg}.
  14
  15 @menu
  16 * gpg-card::             Administrate smart cards.
  17 @end menu
  18
  19 @c
  20 @c  GPG-CARD-TOOL
  21 @c
  22 @manpage gpg-card.1
  23 @node gpg-card
  24 @section Administrate smart cards.
  25 @ifset manverb
  26 .B gpg-card
  27 \- Administrate Smart Cards
  28 @end ifset
  29
  30 @mansect synopsis
  31 @ifset manverb
  32 .B gpg-card
  33 .RI [ options ]
  34 .br
  35 .B gpg-card
  36 .RI [ options ]
  37 .I command
  38 .RI {
  39 .B --
  40 .I command
  41 .RI }
  42 @end ifset
  43
  44 @mansect description
  45 The @command{gpg-card} is used to administrate smart cards and USB
  46 tokens.  It provides a superset of features from @command{gpg
  47 --card-edit} an can be considered a frontend to @command{scdaemon}
  48 which is a daemon started by @command{gpg-agent} to handle smart
  49 cards.
  50
  51 If @command{gpg-card} is invoked without commands an interactive
  52 mode is used.
  53
  54 If @command{gpg-card} is invoked with one or more commands the
  55 same commands as available in the interactive mode are run from the
  56 command line.  These commands need to be delimited with a double-dash.
  57 If a double-dash or a shell specific character is required as part of
  58 a command the entire command needs to be put in quotes.  If one of
  59 those commands returns an error the remaining commands are not anymore
  60 run unless the command was prefixed with a single dash.
  61
  62 A list of commands is available by using the command @code{help} and a
  63 brief description of each command is printed by using @code{help CMD}.
  64 See the section COMMANDS for a full description.
  65
  66 See the NOTES sections for instructions pertaining to specific cards
  67 or card applications.
  68
  69 @mansect options
  70 @noindent
  71 @command{gpg-card} understands these options:
  72
  73 @table @gnupgtabopt
  74
  75 @item --with-colons
  76 @opindex with-colons
  77 This option has currently no effect.
  78
  79 @item --status-fd @var{n}
  80 @opindex status-fd
  81 Write special status strings to the file descriptor @var{n}.  This
  82 program returns only the status messages SUCCESS or FAILURE which are
  83 helpful when the caller uses a double fork approach and can't easily
  84 get the return code of the process.
  85
  86 @item --verbose
  87 @opindex verbose
  88 Enable extra informational output.
  89
  90 @item --quiet
  91 @opindex quiet
  92 Disable almost all informational output.
  93
  94 @item --version
  95 @opindex version
  96 Print version of the program and exit.
  97
  98 @item --help
  99 @opindex help
 100 Display a brief help page and exit.
 101
 102 @item --no-autostart
 103 @opindex no-autostart
 104 Do not start the gpg-agent if it has not yet been started and its
 105 service is required.  This option is mostly useful on machines where
 106 the connection to gpg-agent has been redirected to another machines.
 107
 108 @item --no-history
 109 @opindex --no-history
 110 In interactive mode the command line history is usually saved and
 111 restored to and from a file below the GnuPG home directory.  This
 112 option inhibits the use of that file.
 113
 114 @item --agent-program @var{file}
 115 @opindex agent-program
 116 Specify the agent program to be started if none is running.  The
 117 default value is determined by running @command{gpgconf} with the
 118 option @option{--list-dirs}.
 119
 120 @item --gpg-program @var{file}
 121 @opindex gpg-program
 122 Specify a non-default gpg binary to be used by certain commands.
 123
 124 @item --gpgsm-program @var{file}
 125 @opindex gpgsm-program
 126 Specify a non-default gpgsm binary to be used by certain commands.
 127
 128 @item --chuid @var{uid}
 129 @opindex chuid
 130 Change the current user to @var{uid} which may either be a number or a
 131 name.  This can be used from the root account to run gpg-card for
 132 another user.  If @var{uid} is not the current UID a standard PATH is
 133 set and the envvar GNUPGHOME is unset.  To override the latter the
 134 option @option{--homedir} can be used.  This option has only an effect
 135 when used on the command line.  This option has currently no effect at
 136 all on Windows.
 137
 138 @end table
 139
 140 @mansect commands
 141 @noindent
 142 @command{gpg-card} understands the following commands, which have
 143 options of their own.  The pseudo-option @samp{--} can be used to
 144 separate command options from arguments; if this pseudo option is used
 145 on the command line the entire command with options and arguments must
 146 be quoted, so that it is not mixed up with the @samp{--} as used on
 147 the command line to separate commands.  Note that a short online help
 148 is available for all commands by prefixing them with ``help''.
 149 Command completion in the interactive mode is also supported.
 150
 151 @table @gnupgtabopt
 152
 153 @item AUTHENTICATE [--setkey] [--raw] [< @var{file}]|@var{key}]
 154 @itemx AUTH
 155 @opindex authenticate
 156 Authenticate to the card.  Perform a mutual authentication either by
 157 reading the key from @var{file} or by taking it from the command line
 158 as @var{key}.  Without the option @option{--raw} the key is expected
 159 to be hex encoded.  To install a new administration key
 160 @option{--setkey} is used; this requires a prior authentication with
 161 the old key.  This is used with PIV cards.
 162
 163
 164 @item CAFPR [--clear] N
 165 @opindex cafpr
 166 Change the CA fingerprint number N of an OpenPGP card.  N must be in the
 167 range 1 to 3.  The option @option{--clear} clears the specified
 168 CA fingerprint N or all of them if N is 0 or not given.
 169
 170 @item FACTORY-RESET
 171 @opindex factory-reset
 172 Do a complete reset of some OpenPGP and PIV cards.  This command
 173 deletes all data and keys and resets the PINs to their default.  Don't
 174 worry, you need to confirm before the command proceeds.
 175
 176 @item FETCH
 177 @opindex fetch
 178 Retrieve a key using the URL data object of an OpenPGP card or if that
 179 is missing using the stored fingerprint.
 180
 181 @item FORCESIG
 182 @opindex forcesig
 183 Toggle the forcesig flag of an OpenPGP card.
 184
 185 @item GENERATE [--force] [--algo=@var{algo}@{+@var{algo2}@}] @var{keyref}
 186 @opindex generate
 187 Create a new key on a card.  Use @option{--force} to overwrite an
 188 existing key.  Use "help" for @var{algo} to get a list of known
 189 algorithms.  For OpenPGP cards several algos may be given.  Note that
 190 the OpenPGP key generation is done interactively unless
 191 @option{--algo} or @var{keyref} are given.
 192
 193 @item KDF-SETUP
 194 @opindex kdf-setup
 195 Prepare the OpenPGP card KDF feature for this card.
 196
 197 @item LANG [--clear]
 198 @opindex lang
 199 Change the language info for the card.  This info can be used by
 200 applications for a personalized greeting.  Up to 4 two-digit language
 201 identifiers can be entered as a preference.  The option
 202 @option{--clear} removes all identifiers.  GnuPG does not use this
 203 info.
 204
 205 @item LIST [--cards] [--apps] [--info] [--no-key-lookup] [@var{n}] [@var{app}]
 206 @itemx L
 207 @opindex list
 208 This command reads all information from the current card and display
 209 them in a human readable format.  The first section shows generic
 210 information vaialable for all cards.  The next section shows
 211 information pertaining to keys which depend on the actual card and
 212 application.
 213
 214 With @var{n} given select and list the n-th card;
 215 with @var{app} also given select that application.
 216 To select an @var{app} on the current card use "-" for @var{n}.
 217 The serial number of the card may be used instead of @var{n}.
 218
 219 The option @option{--cards} lists the serial numbers of available
 220 cards.  The option @option{--apps} lists all card applications.  The
 221 option @option{--info} selects a card and prints its serial number.
 222 The option @option{--no-key-lookup} suppresses the listing of matching
 223 OpenPGP or X.509 keys.
 224
 225
 226 @item LOGIN [--clear] [< @var{file}]
 227 @opindex login
 228 Set the login data object of OpenPGP cards.  If @var{file} is given
 229 the data is is read from that file.  This allows to store binary data
 230 in the login field.  The option @option{--clear} deletes the login
 231 data object.
 232
 233 @item NAME [--clear]
 234 @opindex name
 235 Set the name field of an OpenPGP card.  With option @option{--clear}
 236 the stored name is cleared off the card.
 237
 238 @item PASSWD [--reset|--nullpin] [@var{pinref}]
 239 @opindex passwd
 240 Change or unblock the PINs.  Note that in interactive mode and without
 241 a @var{pinref} a menu is presented for certain cards."  In
 242 non-interactive mode and without a @var{pinref} a default value i used
 243 for these cards.  The option @option{--reset} is used with TCOS cards
 244 to reset the PIN using the PUK or vice versa; the option
 245 @var{--nullpin} is used for these cards to set the initial PIN.
 246
 247 @item PRIVATEDO [--clear] @var{n} [< @var{file}]
 248 @opindex privatedo
 249 Change the private data object @var{n} of an OpenPGP card.  @var{n}
 250 must be in the range 1 to 4.  If @var{file} is given the data is is
 251 read from that file.  The option @option{--clear} clears the data.
 252
 253 @item QUIT
 254 @itemx Q
 255 @opindex quit
 256 @opindex q
 257 Stop processing and terminate @command{gpg-card}.
 258
 259 @item READCERT [--openpgp] @var{certref} > @var{file}
 260 @opindex readcert
 261 Read the certificate for key @var{certref} and store it in @var{file}.
 262 With option @option{--openpgp} an OpenPGP keyblock wrapped in a
 263 dedicated CMS content type (OID=1.3.6.1.4.1.11591.2.3.1) is expected
 264 and extracted to @var{file}.  Note that for current OpenPGP cards a
 265 certificate may only be available at the @var{certref} "OPENPGP.3".
 266
 267 @item RESET
 268 @opindex reset
 269 Send a reset to the card daemon.
 270
 271 @item SALUTATION [--clear]
 272 @itemx SALUT
 273 @opindex salutation
 274 @opindex salut
 275 Change the salutation info for the card.  This info can be used by
 276 applications for a personalized greeting.  The option @option{--clear}
 277 removes this data object.  GnuPG does not use this info.
 278
 279 @item UIF @var{N} [on|off|permanent]
 280 @opindex uif
 281 Change the User Interaction Flag.  That flags tells whether the
 282 confirmation button of a token shall be used.  @var{n} must in the
 283 range 1 to 3.  "permanent" is the same as "on" but the flag can't be
 284 changed anmore.
 285
 286 @item UNBLOCK
 287 @opindex unblock
 288 Unblock a PIN using a PUK or Reset Code.  Note that OpenPGP cards
 289 prior to version 2 can't use this; instead the @command{PASSWD} can be
 290 used to set a new PIN.
 291
 292 @item URL [--clear]
 293 @opindex url
 294 Set the URL data object of an OpenPGP card.  That data object can be
 295 used by by @command{gpg}'s @option{--fetch} command to retrieve the
 296 full public key.  The option @option{--clear} deletes the content of
 297 that data object.
 298
 299 @item VERIFY [@var{chvid}]
 300 @opindex verify
 301 Verify the PIN identified by @var{chvid} or the default PIN.
 302
 303 @item WRITECERT @var{certref}  < @var{file}
 304 @itemx WRITECERT --openpgp @var{certref} [< @var{file}|@var{fpr}]
 305 @itemx WRITECERT --clear @var{certref}
 306 @opindex writecert
 307 Write a certificate to the card under the id @var{certref}.  The
 308 option @option{--clear} removes the certificate from the card.  The
 309 option @option{--openpgp} expects an OpenPGP keyblock and stores it
 310 encapsulated in a CMS container; the keyblock is taken from @var{file}
 311 or directly from the OpenPGP key identified by fingerprint @var{fpr}.
 312
 313 @item WRITEKEY [--force] @var{keyref} @var{keygrip}
 314 @opindex writekey
 315 Write a private key object identified by @var{keygrip} to the card
 316 under the id @var{keyref}.  Option @option{--force} allows overwriting
 317 an existing key.
 318
 319 @item YUBIKEY @var{cmd} @var{args}
 320 @opindex yubikey
 321 Various commands pertaining to Yubikey tokens with @var{cmd} being:
 322 @table @var
 323 @item LIST
 324 List supported and enabled Yubikey applications.
 325 @item ENABLE  usb|nfc|all [otp|u2f|opgp|piv|oath|fido2|all]
 326 @itemx DISABLE
 327 Enable or disable the specified or all applications on the
 328 given interface.
 329 @end table
 330
 331 @end table
 332
 333 @mansect notes (OpenPGP)
 334 The support for OpenPGP cards in @command{gpg-card} is not yet
 335 complete.  For missing features, please continue to use @code{gpg
 336 --card-edit}.
 337
 338 @mansect notes (PIV)
 339 @noindent
 340 GnuPG has support for PIV cards (``Personal Identity Verification''
 341 as specified by NIST Special Publication 800-73-4).  This section
 342 describes how to initialize (personalize) a fresh Yubikey token
 343 featuring the PIV application (requires Yubikey-5).  We assume that
 344 the credentials have not yet been changed and thus are:
 345 @table @asis
 346 @item Authentication key
 347 This is a 24 byte key described by the hex string @*
 348 @code{010203040506070801020304050607080102030405060708}.
 349 @item PIV Application PIN
 350 This is the string @code{123456}.
 351 @item PIN Unblocking Key
 352 This is the string @code{12345678}.
 353 @end table
 354 See the example section on how to change these defaults.  For
 355 production use it is important to use secure values for them.  Note that
 356 the Authentication Key is not queried via the usual Pinentry dialog
 357 but needs to be entered manually or read from a file.  The use of a
 358 dedicated machine to personalize tokens is strongly suggested.
 359
 360 To see what is on the card, the command @code{list} can be given.  We
 361 will use the interactive mode in the following (the string
 362 @emph{gpg/card>} is the prompt).  An example output for a fresh card
 363 is:
 364
 365 @example
 366 gpg/card> list
 367 Reader ...........: 1050:0407:X:0
 368 Card type ........: yubikey
 369 Card firmware ....: 5.1.2
 370 Serial number ....: D2760001240102010006090746250000
 371 Application type .: OpenPGP
 372 Version ..........: 2.1
 373 [...]
 374 @end example
 375
 376 It can be seen by the ``Application type'' line that GnuPG selected
 377 the OpenPGP application of the Yubikey.  This is because GnuPG assigns
 378 the highest priority to the OpenPGP application.  To use the PIV
 379 application of the Yubikey several methods can be used:
 380
 381 With a Yubikey 5 or later the OpenPGP application on the Yubikey can
 382 be disabled:
 383
 384 @example
 385 gpg/card> yubikey disable all opgp
 386 gpg/card> yubikey list
 387 Application  USB    NFC
 388 -----------------------
 389 OTP          yes    yes
 390 U2F          yes    yes
 391 OPGP         no     no
 392 PIV          yes    no
 393 OATH         yes    yes
 394 FIDO2        yes    yes
 395 gpg/card> reset
 396 @end example
 397
 398 The @code{reset} is required so that the GnuPG system rereads the
 399 card.  Note that disabled applications keep all their data and can at
 400 any time be re-enabled (use @kbd{help yubikey}).
 401
 402 Another option, which works for all Yubikey versions, is to disable
 403 the support for OpenPGP cards in scdaemon.  This is done by adding the
 404 line
 405
 406 @smallexample
 407 disable-application openpgp
 408 @end smallexample
 409
 410 to @file{~/.gnupg/scdaemon.conf} and by restarting scdaemon, either by
 411 killing the process or by using @kbd{gpgconf --kill scdaemon}.  Finally
 412 the default order in which card applications are tried by scdaemon can
 413 be changed.   For example to prefer PIV over OpenPGP it is sufficient
 414 to add
 415
 416 @smallexample
 417 application-priority piv
 418 @end smallexample
 419
 420 to @file{~/.gnupg/scdaemon.conf} and to restart @command{scdaemon}.
 421 This has an effect only on tokens which support both, PIV and OpenPGP,
 422 but does not hamper the use of OpenPGP only tokens.
 423
 424 With one of these methods employed the @code{list} command of
 425 @command{gpg-card} shows this:
 426
 427 @example
 428 gpg/card> list
 429 Reader ...........: 1050:0407:X:0
 430 Card type ........: yubikey
 431 Card firmware ....: 5.1.2
 432 Serial number ....: FF020001008A77C1
 433 Application type .: PIV
 434 Version ..........: 1.0
 435 Displayed s/n ....: yk-9074625
 436 PIN usage policy .: app-pin
 437 PIN retry counter : - 3 -
 438 PIV authentication: [none]
 439       keyref .....: PIV.9A
 440 Card authenticat. : [none]
 441       keyref .....: PIV.9E
 442 Digital signature : [none]
 443       keyref .....: PIV.9C
 444 Key management ...: [none]
 445       keyref .....: PIV.9D
 446 @end example
 447
 448 In case several tokens are plugged into the computer, gpg-card will
 449 show only one.  To show another token the number of the token (0, 1,
 450 2, ...) can be given as an argument to the @code{list} command.  The
 451 command @kbd{list --cards} prints a list of all inserted tokens.
 452
 453 Note that the ``Displayed s/n'' is printed on the token and also
 454 shown in Pinentry prompts asking for the PIN.  The four standard key
 455 slots are always shown, if other key slots are initialized they are
 456 shown as well.  The @emph{PIV authentication} key (internal reference
 457 @emph{PIV.9A}) is used to authenticate the card and the card holder.
 458 The use of the associated private key is protected by the Application
 459 PIN which needs to be provided once and the key can the be used until
 460 the card is reset or removed from the reader or USB port.  GnuPG uses
 461 this key with its @emph{Secure Shell} support.  The @emph{Card
 462 authentication} key (@emph{PIV.9E}) is also known as the CAK and used
 463 to support physical access applications.  The private key is not
 464 protected by a PIN and can thus immediately be used.  The @emph{Digital
 465 signature} key (@emph{PIV.9C}) is used to digitally sign documents.
 466 The use of the associated private key is protected by the Application
 467 PIN which needs to be provided for each signing operation.  The
 468 @emph{Key management} key (@emph{PIV.9D}) is used for encryption.  The
 469 use of the associated private key is protected by the Application PIN
 470 which needs to be provided only once so that decryption operations can
 471 then be done until the card is reset or removed from the reader or USB
 472 port.
 473
 474 We now generate three of the four keys.  Note that GnuPG does
 475 currently not use the the @emph{Card authentication} key; however,
 476 that key is mandatory by the PIV standard and thus we create it too.
 477 Key generation requires that we authenticate to the card.  This can be
 478 done either on the command line (which would reveal the key):
 479
 480 @example
 481 gpg/card> auth 010203040506070801020304050607080102030405060708
 482 @end example
 483
 484 or by reading the key from a file.  That file needs to consist of one
 485 LF terminated line with the hex encoded key (as above):
 486
 487 @example
 488 gpg/card> auth < myauth.key
 489 @end example
 490
 491 As usual @samp{help auth} gives help for this command.  An error
 492 message is printed if a non-matching key is used.  The authentication
 493 is valid until a reset of the card or until the card is removed from
 494 the reader or the USB port.  Note that that in non-interactive mode
 495 the @samp{<} needs to be quoted so that the shell does not interpret
 496 it as a its own redirection symbol.
 497
 498 @noindent
 499 Here are the actual commands to generate the keys:
 500
 501 @example
 502 gpg/card> generate --algo=nistp384 PIV.9A
 503 PIV card no. yk-9074625 detected
 504 gpg/card> generate --algo=nistp256 PIV.9E
 505 PIV card no. yk-9074625 detected
 506 gpg/card> generate --algo=rsa2048 PIV.9C
 507 PIV card no. yk-9074625 detected
 508 @end example
 509
 510 If a key has already been created for one of the slots an error will
 511 be printed; to create a new key anyway the option @samp{--force} can be
 512 used.  Note that only the private and public keys have been created
 513 but no certificates are stored in the key slots.  In fact, GnuPG uses
 514 its own non-standard method to store just the public key in place of
 515 the the certificate.  Other application will not be able to make use
 516 these keys until @command{gpgsm} or another tool has been used to
 517 create and store the respective certificates.   Let us see what the
 518 list command now shows:
 519
 520 @example
 521 gpg/card> list
 522 Reader ...........: 1050:0407:X:0
 523 Card type ........: yubikey
 524 Card firmware ....: 5.1.2
 525 Serial number ....: FF020001008A77C1
 526 Application type .: PIV
 527 Version ..........: 1.0
 528 Displayed s/n ....: yk-9074625
 529 PIN usage policy .: app-pin
 530 PIN retry counter : - 3 -
 531 PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
 532       keyref .....: PIV.9A  (auth)
 533       algorithm ..: nistp384
 534 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
 535       keyref .....: PIV.9E  (auth)
 536       algorithm ..: nistp256
 537 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
 538       keyref .....: PIV.9C  (sign,cert)
 539       algorithm ..: rsa2048
 540 Key management ...: [none]
 541       keyref .....: PIV.9D
 542 @end example
 543
 544 The primary information for each key is the @emph{keygrip}, a 40 byte
 545 hex-string identifying the key.  This keygrip is a unique identifier
 546 for the specific parameters of a key.  It is used by
 547 @command{gpg-agent} and other parts of GnuPG to associate a private
 548 key to its protocol specific certificate format (X.509, OpenPGP, or
 549 SecureShell).  Below the keygrip the key reference along with the key
 550 usage capabilities are show.  Finally the algorithm is printed in the
 551 format used by @command {gpg}.  At that point no other information is
 552 shown because for these new keys gpg won't be able to find matching
 553 certificates.
 554
 555 Although we could have created the @emph{Key management} key also with
 556 the generate command, we will create that key off-card so that a
 557 backup exists.  To accomplish this a key needs to be created with
 558 either @command{gpg} or @command{gpgsm} or imported in one of these
 559 tools.  In our example we create a self-signed X.509 certificate (exit
 560 the gpg-card tool, first):
 561
 562 @example
 563 $ gpgsm --gen-key -o encr.crt
 564    (1) RSA
 565    (2) Existing key
 566    (3) Existing key from card
 567 Your selection? 1
 568 What keysize do you want? (3072) 2048
 569 Requested keysize is 2048 bits
 570 Possible actions for a RSA key:
 571    (1) sign, encrypt
 572    (2) sign
 573    (3) encrypt
 574 Your selection? 3
 575 Enter the X.509 subject name: CN=Encryption key for yk-9074625,O=example,C=DE
 576 Enter email addresses (end with an empty line):
 577 > otto@@example.net
 578 >
 579 Enter DNS names (optional; end with an empty line):
 580 >
 581 Enter URIs (optional; end with an empty line):
 582 >
 583 Create self-signed certificate? (y/N) y
 584 These parameters are used:
 585     Key-Type: RSA
 586     Key-Length: 2048
 587     Key-Usage: encrypt
 588     Serial: random
 589     Name-DN: CN=Encryption key for yk-9074625,O=example,C=DE
 590     Name-Email: otto@@example.net
 591
 592 Proceed with creation? (y/N)
 593 Now creating self-signed certificate.  This may take a while ...
 594 gpgsm: about to sign the certificate for key: &34798AAFE0A7565088101CC4AE31C5C8C74461CB
 595 gpgsm: certificate created
 596 Ready.
 597 $ gpgsm --import encr.crt
 598 gpgsm: certificate imported
 599 gpgsm: total number processed: 1
 600 gpgsm:               imported: 1
 601 @end example
 602
 603 Note the last step which imported the created certificate.  If you
 604 you instead created a certificate signing request (CSR) instead of a
 605 self-signed certificate and sent this off to a CA you would do the
 606 same import step with the certificate received from the CA.  Take note
 607 of the keygrip (prefixed with an ampersand) as shown during the
 608 certificate creation or listed it again using @samp{gpgsm
 609 --with-keygrip -k otto@@example.net}.  Now to move the key and
 610 certificate to the card start @command{gpg-card} again and enter:
 611
 612 @example
 613 gpg/card> writekey PIV.9D 34798AAFE0A7565088101CC4AE31C5C8C74461CB
 614 gpg/card> writecert PIV.9D < encr.crt
 615 @end example
 616
 617 If you entered a passphrase to protect the private key, you will be
 618 asked for it via the Pinentry prompt.  On success the key and the
 619 certificate has been written to the card and a @code{list} command
 620 shows:
 621
 622 @example
 623 [...]
 624 Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
 625       keyref .....: PIV.9D  (encr)
 626       algorithm ..: rsa2048
 627       used for ...: X.509
 628         user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
 629         user id ..: <otto@@example.net>
 630 @end example
 631
 632 In case the same key (identified by the keygrip) has been used for
 633 several certificates you will see several ``used for'' parts.  With
 634 this the encryption key is now fully functional and can be used to
 635 decrypt messages encrypted to this certificate.  @sc{Take care:} the
 636 original key is still stored on-disk and should be moved to a backup
 637 medium.  This can simply be done by copying the file
 638 @file{34798AAFE0A7565088101CC4AE31C5C8C74461CB.key} from the directory
 639 @file{~/.gnupg/private-keys-v1.d/} to the backup medium and deleting
 640 the file at its original place.
 641
 642 The final example is to create a self-signed certificate for digital
 643 signatures.  Leave @command{gpg-card} using @code{quit} or by pressing
 644 Control-D and use gpgsm:
 645
 646 @example
 647 $ gpgsm --learn
 648 $ gpgsm --gen-key -o sign.crt
 649 Please select what kind of key you want:
 650    (1) RSA
 651    (2) Existing key
 652    (3) Existing key from card
 653 Your selection? 3
 654 Serial number of the card: FF020001008A77C1
 655 Available keys:
 656    (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384
 657    (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256
 658    (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048
 659    (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048
 660 Your selection? 3
 661 Possible actions for a RSA key:
 662    (1) sign, encrypt
 663    (2) sign
 664    (3) encrypt
 665 Your selection? 2
 666 Enter the X.509 subject name: CN=Signing key for yk-9074625,O=example,C=DE
 667 Enter email addresses (end with an empty line):
 668 > otto@@example.net
 669 >
 670 Enter DNS names (optional; end with an empty line):
 671 >
 672 Enter URIs (optional; end with an empty line):
 673 >
 674 Create self-signed certificate? (y/N)
 675 These parameters are used:
 676     Key-Type: card:PIV.9C
 677     Key-Length: 1024
 678     Key-Usage: sign
 679     Serial: random
 680     Name-DN: CN=Signing key for yk-9074625,O=example,C=DE
 681     Name-Email: otto@@example.net
 682
 683 Proceed with creation? (y/N) y
 684 Now creating self-signed certificate.  This may take a while ...
 685 gpgsm: about to sign the certificate for key: &32A6C6FAFCB8421878608AAB452D5470DD3223ED
 686 gpgsm: certificate created
 687 Ready.
 688 $ gpgsm --import sign.crt
 689 gpgsm: certificate imported
 690 gpgsm: total number processed: 1
 691 gpgsm:               imported: 1
 692 @end example
 693
 694 The use of @samp{gpgsm --learn} is currently necessary so that
 695 gpg-agent knows what keys are available on the card.  The need for
 696 this command will eventually be removed.  The remaining commands are
 697 similar to the creation of an on-disk key.  However, here we select
 698 the @samp{Digital signature} key.  During the creation process you
 699 will be asked for the Application PIN of the card.  The final step is
 700 to write the certificate to the card using @command{gpg-card}:
 701
 702 @example
 703 gpg/card> writecert PIV.9C < sign.crt
 704 @end example
 705
 706 By running list again we will see the fully initialized card:
 707
 708 @example
 709 Reader ...........: 1050:0407:X:0
 710 Card type ........: yubikey
 711 Card firmware ....: 5.1.2
 712 Serial number ....: FF020001008A77C1
 713 Application type .: PIV
 714 Version ..........: 1.0
 715 Displayed s/n ....: yk-9074625
 716 PIN usage policy .: app-pin
 717 PIN retry counter : - [verified] -
 718 PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
 719       keyref .....: PIV.9A  (auth)
 720       algorithm ..: nistp384
 721 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
 722       keyref .....: PIV.9E  (auth)
 723       algorithm ..: nistp256
 724 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
 725       keyref .....: PIV.9C  (sign,cert)
 726       algorithm ..: rsa2048
 727       used for ...: X.509
 728         user id ..: CN=Signing key for yk-9074625,O=example,C=DE
 729         user id ..: <otto@@example.net>
 730 Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
 731       keyref .....: PIV.9D  (encr)
 732       algorithm ..: rsa2048
 733       used for ...: X.509
 734         user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
 735         user id ..: <otto@@example.net>
 736 @end example
 737
 738 It is now possible to sign and to encrypt with this card using gpgsm
 739 and to use the @samp{PIV authentication} key with ssh:
 740
 741 @example
 742 $ ssh-add -l
 743 384 SHA256:0qnJ0Y0ehWxKcx2frLfEljf6GCdlO55OZed5HqGHsaU cardno:yk-9074625 (ECDSA)
 744 @end example
 745
 746 As usual use ssh-add with the uppercase @samp{-L} to list the public
 747 ssh key.  To use the certificates with Thunderbird or Mozilla, please
 748 consult the Scute manual for details.
 749
 750 If you want to use the same PIV keys also for OpenPGP (for example on
 751 a Yubikey to avoid switching between OpenPGP and PIV), this is also
 752 possible:
 753
 754 @example
 755 $ gpgsm --learn
 756 $ gpg --full-gen-key
 757 Please select what kind of key you want:
 758    (1) RSA and RSA (default)
 759    (2) DSA and Elgamal
 760    (3) DSA (sign only)
 761    (4) RSA (sign only)
 762   (14) Existing key from card
 763 Your selection? 14
 764 Serial number of the card: FF020001008A77C1
 765 Available keys:
 766    (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth)
 767    (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth)
 768    (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign)
 769    (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr)
 770 Your selection? 3
 771 Please specify how long the key should be valid.
 772          0 = key does not expire
 773       <n>  = key expires in n days
 774       <n>w = key expires in n weeks
 775       <n>m = key expires in n months
 776       <n>y = key expires in n years
 777 Key is valid for? (0)
 778 Key does not expire at all
 779 Is this correct? (y/N) y
 780
 781 GnuPG needs to construct a user ID to identify your key.
 782
 783 Real name:
 784 Email address: otto@@example.net
 785 Comment:
 786 You selected this USER-ID:
 787     "otto@@example.net"
 788
 789 Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
 790 gpg: key C3AFA9ED971BB365 marked as ultimately trusted
 791 gpg: revocation certificate stored as '[...]D971BB365.rev'
 792 public and secret key created and signed.
 793
 794 Note that this key cannot be used for encryption.  You may want to use
 795 the command "--edit-key" to generate a subkey for this purpose.
 796 pub   rsa2048 2019-04-04 [SC]
 797       7F899AE2FB73159DD68A1B20C3AFA9ED971BB365
 798 uid                      otto@@example.net
 799 @end example
 800
 801 Note that you will be asked two times to enter the PIN of your PIV
 802 card.  If you run @command{gpg} in @option{--expert} mode you will
 803 also ge given the option to change the usage flags of the key.  The next
 804 typescript shows how to add the encryption subkey:
 805
 806 @example
 807 $ gpg --edit-key 7F899AE2FB73159DD68A1B20C3AFA9ED971BB365
 808 Secret key is available.
 809
 810 sec  rsa2048/C3AFA9ED971BB365
 811      created: 2019-04-04  expires: never       usage: SC
 812      card-no: FF020001008A77C1
 813      trust: ultimate      validity: ultimate
 814 [ultimate] (1). otto@@example.net
 815 gpg> addkey
 816 Secret parts of primary key are stored on-card.
 817 Please select what kind of key you want:
 818    (3) DSA (sign only)
 819    (4) RSA (sign only)
 820    (5) Elgamal (encrypt only)
 821    (6) RSA (encrypt only)
 822   (14) Existing key from card
 823 Your selection? 14
 824 Serial number of the card: FF020001008A77C1
 825 Available keys:
 826    (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384 (auth)
 827    (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256 (auth)
 828    (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048 (cert,sign)
 829    (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048 (encr)
 830 Your selection? 4
 831 Please specify how long the key should be valid.
 832          0 = key does not expire
 833       <n>  = key expires in n days
 834       <n>w = key expires in n weeks
 835       <n>m = key expires in n months
 836       <n>y = key expires in n years
 837 Key is valid for? (0)
 838 Key does not expire at all
 839 Is this correct? (y/N) y
 840 Really create? (y/N) y
 841
 842 sec  rsa2048/C3AFA9ED971BB365
 843      created: 2019-04-04  expires: never       usage: SC
 844      card-no: FF020001008A77C1
 845      trust: ultimate      validity: ultimate
 846 ssb  rsa2048/7067860A98FCE6E1
 847      created: 2019-04-04  expires: never       usage: E
 848      card-no: FF020001008A77C1
 849 [ultimate] (1). otto@@example.net
 850
 851 gpg> save
 852 @end example
 853
 854 Now you can use your PIV card also with @command{gpg}.
 855
 856 @c @mansect examples
 857
 858 @mansect see also
 859 @ifset isman
 860 @command{scdaemon}(1)
 861 @end ifset