scd: Add new command: KEYINFO.
[gnupg.git] / 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 tool to administrate smart cards and USB tokens.  This
12 tool is an extension of the @option{--edit-key} command available with
13 @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 mot 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 detailed description of each command is printed by using @code{help
64 COMMAND}.
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 --agent-program @var{file}
109 @opindex agent-program
110 Specify the agent program to be started if none is running.  The
111 default value is determined by running @command{gpgconf} with the
112 option @option{--list-dirs}.
113
114 @item --gpg-program @var{file}
115 @opindex gpg-program
116 Specify a non-default gpg binary to be used by certain commands.
117
118 @item --gpgsm-program @var{file}
119 @opindex gpgsm-program
120 Specify a non-default gpgsm binary to be used by certain commands.
121
122 @end table
123
124 @mansect notes (OpenPGP)
125 The support for OpenPGP cards in @command{gpg-card} is not yet
126 complete.  For missing features, please continue to use @code{gpg
127 --card-edit}.
128
129 @mansect notes (PIV)
130 @noindent
131 GnuPG has support for PIV cards (``Personal Identity Verification''
132 as specified by NIST Special Publication 800-73-4).  This section
133 describes how to initialize (personalize) a fresh Yubikey token
134 featuring the PIV application (requires Yubikey-5).  We assume that
135 the credentials have not yet been changed and thus are:
136 @table @asis
137 @item Authentication key
138 This is a 24 byte key described by the hex string
139 @code{010203040506070801020304050607080102030405060708}.
140 @item PIV Application PIN
141 This is the string @code{123456}.
142 @item PIN Unblocking Key
143 This is the string @code{12345678}.
144 @end table
145 See the example section on how to change these defaults.  For
146 production use it is important to use secure values for them.  Note that
147 the Authentication Key is not queried via the usual Pinentry dialog
148 but needs to be entered manually or read from a file.  The use of a
149 dedicated machine to personalize tokens is strongly suggested.
150
151 To see what is on the card, the command @code{list} can be given.  We
152 will use the interactive mode in the following (the string
153 @emph{gpg/card>} is the prompt).  An example output for a fresh card
154 is:
155
156 @example
157 gpg/card> list
158 Reader ...........: 1050:0407:X:0
159 Card type ........: yubikey
160 Card firmware ....: 5.1.2
161 Serial number ....: D2760001240102010006090746250000
162 Application type .: OpenPGP
163 Version ..........: 2.1
164 [...]
165 @end example
166
167 It can be seen by the ``Application type'' line that GnuPG selected the
168 OpenPGP application of the Yubikey.  This is because GnuPG assigns the
169 highest priority to the OpenPGP application.  To use the PIV
170 application of the Yubikey, the OpenPGP application needs to be
171 disabled:
172
173 @example
174 gpg/card> yubikey disable all opgp
175 gpg/card> yubikey list
176 Application  USB    NFC
177 -----------------------
178 OTP          yes    yes
179 U2F          yes    yes
180 OPGP         no     no
181 PIV          yes    no
182 OATH         yes    yes
183 FIDO2        yes    yes
184 gpg/card> reset
185 @end example
186
187 The @code{reset} is required so that the GnuPG system rereads the
188 card.  Note that disabled applications keep all their data and can at
189 any time be re-enabled (see @emph{help yubikey}).  Now a @emph{list}
190 command shows this:
191
192 @example
193 gpg/card> list
194 Reader ...........: 1050:0407:X:0
195 Card type ........: yubikey
196 Card firmware ....: 5.1.2
197 Serial number ....: FF020001008A77C1
198 Application type .: PIV
199 Version ..........: 1.0
200 Displayed s/n ....: yk-9074625
201 PIN usage policy .: app-pin
202 PIN retry counter : - 3 -
203 PIV authentication: [none]
204       keyref .....: PIV.9A
205 Card authenticat. : [none]
206       keyref .....: PIV.9E
207 Digital signature : [none]
208       keyref .....: PIV.9C
209 Key management ...: [none]
210       keyref .....: PIV.9D
211 @end example
212
213 Note that the ``Displayed s/sn'' is printed on the token and also
214 shown in Pinentry prompts asking for the PIN.  The four standard key
215 slots are always shown, if other key slots are initialized they are
216 shown as well.  The @emph{PIV authentication} key (internal reference
217 @emph{PIV.9A}) is used to authenticate the card and the card holder.
218 The use of the associated private key is protected by the Application
219 PIN which needs to be provided once and the key can the be used until
220 the card is reset or removed from the reader or USB port.  GnuPG uses
221 this key with its @emph{Secure Shell} support.  The @emph{Card
222 authentication} key (@emph{PIV.9E}) is also known as the CAK and used
223 to support physical access applications.  The private key is not
224 protected by a PIN and can thus immediately be used.  The @emph{Digital
225 signature} key (@emph{PIV.9C}) is used to digitally sign documents.
226 The use of the associated private key is protected by the Application
227 PIN which needs to be provided for each signing operation.  The
228 @emph{Key management} key (@emph{PIV.9D}) is used for encryption.  The
229 use of the associated private key is protected by the Application PIN
230 which needs to be provided only once so that decryption operations can
231 then be done until the card is reset or removed from the reader or USB
232 port.
233
234 We now generate tree of the four keys.  Note that GnuPG does currently
235 not use the the @emph{Card authentication} key but because it is
236 mandatory by the specs we create it anyway.  Key generation requires
237 that we authenticate to the card.  This can be done either on the
238 command line (which would reveal the key):
239
240 @example
241 gpg/card> auth 010203040506070801020304050607080102030405060708
242 @end example
243
244 or by reading the key from a file.  That file needs to consist of one
245 LF terminated line with the hex encoded key (as above):
246
247 @example
248 gpg/card> auth < myauth.key
249 @end example
250
251 As usual @samp{help auth} gives help for this command.  An error
252 message is printed if a non-matching key is used.  The authentication
253 is valid until a reset of the card or until the card is removed from
254 the reader or the USB port.  Note that that in non-interactive mode
255 the @samp{<} needs to be quoted so that the shell does not interpret
256 it as a its own redirection symbol.
257
258 @noindent
259 Here are the actual commands to generate the keys:
260
261 @example
262 gpg/card> generate --algo=nistp384 PIV.9A
263 PIV card no. yk-9074625 detected
264 gpg/card> generate --algo=nistp256 PIV.9E
265 PIV card no. yk-9074625 detected
266 gpg/card> generate --algo=rsa2048 PIV.9C
267 PIV card no. yk-9074625 detected
268 @end example
269
270 If a key has already been created for one of the slots an error will
271 be printed; to create a new key anyway the option @samp{--force} can be
272 used.  Note that only the private and public keys have been created
273 but no certificates are stored in the key slots.  In fact, GnuPG uses
274 its own non-standard method to store just the public key in place of
275 the the certificate.  Other application will not be able to make use
276 these keys until @command{gpgsm} or another tool has been used to
277 create and store the respective certificates.   Let us see what the
278 list command now shows:
279
280 @example
281 gpg/card> list
282 Reader ...........: 1050:0407:X:0
283 Card type ........: yubikey
284 Card firmware ....: 5.1.2
285 Serial number ....: FF020001008A77C1
286 Application type .: PIV
287 Version ..........: 1.0
288 Displayed s/n ....: yk-9074625
289 PIN usage policy .: app-pin
290 PIN retry counter : - 3 -
291 PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
292       keyref .....: PIV.9A  (auth)
293       algorithm ..: nistp384
294 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
295       keyref .....: PIV.9E  (auth)
296       algorithm ..: nistp256
297 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
298       keyref .....: PIV.9C  (sign,cert)
299       algorithm ..: rsa2048
300 Key management ...: [none]
301       keyref .....: PIV.9D
302 @end example
303
304 The primary information for each key is the @emph{keygrip}, a 40 byte
305 hex-string identifying the key.  This keygrip is a unique identifier
306 for the specific parameters of a key.  It is used by
307 @command{gpg-agent} and other parts of GnuPG to associate a private
308 key to its protocol specific certificate format (X.509, OpenPGP, or
309 SecureShell).  Below the keygrip the key reference along with the key
310 usage capabilities are show.  Finally the algorithm is printed in the
311 format used by @command {gpg}.  At that point no other information is
312 shown because for these new keys gpg won't be able to find matching
313 certificates.
314
315 Although we could have created the @emph{Key management} key also with
316 the generate command, we will create that key off-card so that a
317 backup exists.  To accomplish this a key needs to be created with
318 either @command{gpg} or @command{gpgsm} or imported in one of these
319 tools.  In our example we create a self-signed X.509 certificate (exit
320 the gpg-card tool, first):
321
322 @example
323 $ gpgsm --gen-key -o encr.crt
324    (1) RSA
325    (2) Existing key
326    (3) Existing key from card
327 Your selection? 1
328 What keysize do you want? (3072) 2048
329 Requested keysize is 2048 bits
330 Possible actions for a RSA key:
331    (1) sign, encrypt
332    (2) sign
333    (3) encrypt
334 Your selection? 3
335 Enter the X.509 subject name: CN=Encryption key for yk-9074625,O=example,C=DE
336 Enter email addresses (end with an empty line):
337 > otto@@example.net
338 >
339 Enter DNS names (optional; end with an empty line):
340 >
341 Enter URIs (optional; end with an empty line):
342 >
343 Create self-signed certificate? (y/N) y
344 These parameters are used:
345     Key-Type: RSA
346     Key-Length: 2048
347     Key-Usage: encrypt
348     Serial: random
349     Name-DN: CN=Encryption key for yk-9074625,O=example,C=DE
350     Name-Email: otto@@example.net
351
352 Proceed with creation? (y/N)
353 Now creating self-signed certificate.  This may take a while ...
354 gpgsm: about to sign the certificate for key: &34798AAFE0A7565088101CC4AE31C5C8C74461CB
355 gpgsm: certificate created
356 Ready.
357 $ gpgsm --import encr.crt
358 gpgsm: certificate imported
359 gpgsm: total number processed: 1
360 gpgsm:               imported: 1
361 @end example
362
363 Note the last steps which imported the created certificate.  If you
364 you instead created a certificate signing request (CSR) instead of a
365 self-signed certificate and sent this off to a CA you would do the
366 same import step with the certificate received from the CA.  Take note
367 of the keygrip (prefixed with an ampersand) as shown during the
368 certificate creation or listed it again using @samp{gpgsm
369 --with-keygrip -k otto@@example.net}.  Now to move the key and
370 certificate to the card start @command{gpg-card} again and enter:
371
372 @example
373 gpg/card> writekey PIV.9D 34798AAFE0A7565088101CC4AE31C5C8C74461CB
374 gpg/card> writecert PIV.9D < encr.crt
375 @end example
376
377 If you entered a passphrase to protect the private key, you will be
378 asked for it via the Pinentry prompt.  On success the key and the
379 certificate has been written to the card and a @code{list} command
380 shows:
381
382 @example
383 [...]
384 Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
385       keyref .....: PIV.9D  (encr)
386       algorithm ..: rsa2048
387       used for ...: X.509
388         user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
389         user id ..: <otto@@example.net>
390 @end example
391
392 In case the same key (identified by the keygrip) has been used for
393 several certificates you will see several ``used for'' parts.  With
394 this the encryption key is now fully functional and can be used to
395 decrypt messages encrypted to this certificate.  @sc{Take care:} the
396 original key is still stored on-disk and should be moved to a backup
397 medium.  This can simply be done by copying the file
398 @file{34798AAFE0A7565088101CC4AE31C5C8C74461CB.key} from the directory
399 @file{~/.gnupg/private-keys-v1.d/} to the backup medium and deleting
400 the file at its original place.
401
402 The final example is to create a self-signed certificate for digital
403 signatures.  Leave @command{gpg-card} using @code{quit} or by pressing
404 Control-D and use gpgsm:
405
406 @example
407 $ gpgsm --learn
408 $ gpgsm --gen-key -o sign.crt
409 Please select what kind of key you want:
410    (1) RSA
411    (2) Existing key
412    (3) Existing key from card
413 Your selection? 3
414 Serial number of the card: FF020001008A77C1
415 Available keys:
416    (1) 213D1825FDE0F8240CB4E4229F01AF90AC658C2E PIV.9A nistp384
417    (2) 7A53E6CFFE7220A0E646B4632EE29E5A7104499C PIV.9E nistp256
418    (3) 32A6C6FAFCB8421878608AAB452D5470DD3223ED PIV.9C rsa2048
419    (4) 34798AAFE0A7565088101CC4AE31C5C8C74461CB PIV.9D rsa2048
420 Your selection? 3
421 Possible actions for a RSA key:
422    (1) sign, encrypt
423    (2) sign
424    (3) encrypt
425 Your selection? 2
426 Enter the X.509 subject name: CN=Signing key for yk-9074625,O=example,C=DE
427 Enter email addresses (end with an empty line):
428 > otto@@example.net
429 >
430 Enter DNS names (optional; end with an empty line):
431 >
432 Enter URIs (optional; end with an empty line):
433 >
434 Create self-signed certificate? (y/N)
435 These parameters are used:
436     Key-Type: card:PIV.9C
437     Key-Length: 1024
438     Key-Usage: sign
439     Serial: random
440     Name-DN: CN=Signing key for yk-9074625,O=example,C=DE
441     Name-Email: otto@@example.net
442
443 Proceed with creation? (y/N) y
444 Now creating self-signed certificate.  This may take a while ...
445 gpgsm: about to sign the certificate for key: &32A6C6FAFCB8421878608AAB452D5470DD3223ED
446 gpgsm: certificate created
447 Ready.
448 $ gpgsm --import sign.crt
449 gpgsm: certificate imported
450 gpgsm: total number processed: 1
451 gpgsm:               imported: 1
452 @end example
453
454 The use of @samp{gpgsm --learn} is currently necessary so that
455 gpg-agent knows what keys are available on the card.  The need for
456 this command will eventually be removed.  The remaining commands are
457 similar to the creation of an on-disk key.  However, here we select
458 the @samp{Digital signature} key.  During the creation process you
459 will be asked for the Application PIN of the card.  The final step is
460 to write the certificate to the card using @command{gpg-card}:
461
462 @example
463 gpg/card> writecert PIV.9C < sign.crt
464 @end example
465
466 By running list again we will see the fully initialized card:
467
468 @example
469 Reader ...........: 1050:0407:X:0
470 Card type ........: yubikey
471 Card firmware ....: 5.1.2
472 Serial number ....: FF020001008A77C1
473 Application type .: PIV
474 Version ..........: 1.0
475 Displayed s/n ....: yk-9074625
476 PIN usage policy .: app-pin
477 PIN retry counter : - [verified] -
478 PIV authentication: 213D1825FDE0F8240CB4E4229F01AF90AC658C2E
479       keyref .....: PIV.9A  (auth)
480       algorithm ..: nistp384
481 Card authenticat. : 7A53E6CFFE7220A0E646B4632EE29E5A7104499C
482       keyref .....: PIV.9E  (auth)
483       algorithm ..: nistp256
484 Digital signature : 32A6C6FAFCB8421878608AAB452D5470DD3223ED
485       keyref .....: PIV.9C  (sign,cert)
486       algorithm ..: rsa2048
487       used for ...: X.509
488         user id ..: CN=Signing key for yk-9074625,O=example,C=DE
489         user id ..: <otto@@example.net>
490 Key management ...: 34798AAFE0A7565088101CC4AE31C5C8C74461CB
491       keyref .....: PIV.9D  (encr)
492       algorithm ..: rsa2048
493       used for ...: X.509
494         user id ..: CN=Encryption key for yk-9074625,O=example,C=DE
495         user id ..: <otto@@example.net>
496 @end example
497
498 It is now possible to sign and to encrypt with this card using gpgsm
499 and to use the @samp{PIV authentication} key with ssh:
500
501 @example
502 $ ssh-add -l
503 384 SHA256:0qnJ0Y0ehWxKcx2frLfEljf6GCdlO55OZed5HqGHsaU cardno:yk-9074625 (ECDSA)
504 @end example
505
506 As usual use ssh-add with the uppercase @samp{-L} to list the public
507 ssh key.  To use the certificates with Thunderbird or Mozilla, please
508 consult the Scute manual for details.
509
510
511
512 @c @mansect examples
513
514 @mansect see also
515 @ifset isman
516 @command{scdaemon}(1)
517 @end ifset