-
Notifications
You must be signed in to change notification settings - Fork 149
/
gpg.texi
4804 lines (4004 loc) · 189 KB
/
gpg.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
@c 2008, 2009, 2010 Free Software Foundation, Inc.
@c This is part of the GnuPG manual.
@c For copying conditions, see the file gnupg.texi.
@include defs.inc
@node Invoking GPG
@chapter Invoking GPG
@cindex GPG command options
@cindex command options
@cindex options, GPG command
@c Begin standard stuff
@ifclear gpgtwohack
@manpage gpg.1
@ifset manverb
.B gpg
\- OpenPGP encryption and signing tool
@end ifset
@mansect synopsis
@ifset manverb
.B gpg
.RB [ \-\-homedir
.IR dir ]
.RB [ \-\-options
.IR file ]
.RI [ options ]
.I command
.RI [ args ]
@end ifset
@end ifclear
@c End standard stuff
@c Begin gpg2 hack stuff
@ifset gpgtwohack
@manpage gpg2.1
@ifset manverb
.B gpg2
\- OpenPGP encryption and signing tool
@end ifset
@mansect synopsis
@ifset manverb
.B gpg2
.RB [ \-\-homedir
.IR dir ]
.RB [ \-\-options
.IR file ]
.RI [ options ]
.I command
.RI [ args ]
@end ifset
@end ifset
@c End gpg2 hack stuff
@mansect description
@command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
is a tool to provide digital encryption and signing services using the
OpenPGP standard. @command{@gpgname} features complete key management and
all the bells and whistles you would expect from a full OpenPGP
implementation.
There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x. GnuPG
2.x supports modern encryption algorithms and thus should be preferred
over GnuPG 1.x. You only need to use GnuPG 1.x if your platform
doesn't support GnuPG 2.x, or you need support for some features that
GnuPG 2.x has deprecated, e.g., decrypting data created with PGP-2
keys.
@ifclear gpgtwohack
If you are looking for version 1 of GnuPG, you may find that version
installed under the name @command{gpg1}.
@end ifclear
@ifset gpgtwohack
In contrast to the standalone command @command{gpg} from GnuPG 1.x,
the 2.x version is commonly installed under the name
@command{@gpgname}.
@end ifset
@manpause
@xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
@mancont
@menu
* GPG Commands:: List of all commands.
* GPG Options:: List of all options.
* GPG Configuration:: Configuration files.
* GPG Examples:: Some usage examples.
Developer information:
* Unattended Usage of GPG:: Using @command{gpg} from other programs.
@end menu
@c * GPG Protocol:: The protocol the server mode uses.
@c *******************************************
@c *************** ****************
@c *************** COMMANDS ****************
@c *************** ****************
@c *******************************************
@mansect commands
@node GPG Commands
@section Commands
Commands are not distinguished from options except for the fact that
only one command is allowed. Generally speaking, irrelevant options
are silently ignored, and may not be checked for correctness.
@command{@gpgname} may be run with no commands. In this case it will
print a warning perform a reasonable action depending on the type of
file it is given as input (an encrypted message is decrypted, a
signature is verified, a file containing keys is listed, etc.).
If you run into any problems, please add the option @option{--verbose}
to the invocation to see more diagnostics.
@menu
* General GPG Commands:: Commands not specific to the functionality.
* Operational GPG Commands:: Commands to select the type of operation.
* OpenPGP Key Management:: How to manage your keys.
@end menu
@c *******************************************
@c ********** GENERAL COMMANDS *************
@c *******************************************
@node General GPG Commands
@subsection Commands not specific to the function
@table @gnupgtabopt
@item --version
@opindex version
Print the program version and licensing information. Note that you
cannot abbreviate this command.
@item --help
@itemx -h
@opindex help
Print a usage message summarizing the most useful command-line options.
Note that you cannot arbitrarily abbreviate this command
(though you can use its short form @option{-h}).
@item --warranty
@opindex warranty
Print warranty information.
@item --dump-options
@opindex dump-options
Print a list of all available options and commands. Note that you cannot
abbreviate this command.
@end table
@c *******************************************
@c ******** OPERATIONAL COMMANDS ***********
@c *******************************************
@node Operational GPG Commands
@subsection Commands to select the type of operation
@table @gnupgtabopt
@item --sign
@itemx -s
@opindex sign
Sign a message. This command may be combined with @option{--encrypt}
(to sign and encrypt a message), @option{--symmetric} (to sign and
symmetrically encrypt a message), or both @option{--encrypt} and
@option{--symmetric} (to sign and encrypt a message that can be
decrypted using a secret key or a passphrase). The signing key is
chosen by default or can be set explicitly using the
@option{--local-user} and @option{--default-key} options.
@item --clear-sign
@opindex clear-sign
@itemx --clearsign
@opindex clearsign
Make a cleartext signature. The content in a cleartext signature is
readable without any special software. OpenPGP software is only needed
to verify the signature. cleartext signatures may modify end-of-line
whitespace for platform independence and are not intended to be
reversible. The signing key is chosen by default or can be set
explicitly using the @option{--local-user} and @option{--default-key}
options.
@item --detach-sign
@itemx -b
@opindex detach-sign
Make a detached signature.
@item --encrypt
@itemx -e
@opindex encrypt
Encrypt data to one or more public keys. This command may be combined
with @option{--sign} (to sign and encrypt a message),
@option{--symmetric} (to encrypt a message that can be decrypted using a
secret key or a passphrase), or @option{--sign} and
@option{--symmetric} together (for a signed message that can be
decrypted using a secret key or a passphrase). @option{--recipient}
and related options specify which public keys to use for encryption.
@item --symmetric
@itemx -c
@opindex symmetric
Encrypt with a symmetric cipher using a passphrase. The default
symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
@option{--cipher-algo} option. This command may be combined with
@option{--sign} (for a signed and symmetrically encrypted message),
@option{--encrypt} (for a message that may be decrypted via a secret key
or a passphrase), or @option{--sign} and @option{--encrypt} together
(for a signed message that may be decrypted via a secret key or a
passphrase). @command{@gpgname} caches the passphrase used for
symmetric encryption so that a decrypt operation may not require that
the user needs to enter the passphrase. The option
@option{--no-symkey-cache} can be used to disable this feature.
@item --store
@opindex store
Store only (make a simple literal data packet).
@item --decrypt
@itemx -d
@opindex decrypt
Decrypt the file given on the command line (or STDIN if no file
is specified) and write it to STDOUT (or the file specified with
@option{--output}). If the decrypted file is signed, the signature is also
verified. This command differs from the default operation, as it never
writes to the filename which is included in the file and it rejects
files that don't begin with an encrypted message.
@item --verify
@opindex verify
Assume that the first argument is a signed file and verify it without
generating any output. With no arguments, the signature packet is
read from STDIN. If only one argument is given, the specified file is
expected to include a complete signature.
With more than one argument, the first argument should specify a file
with a detached signature and the remaining files should contain the
signed data. To read the signed data from STDIN, use @samp{-} as the
second filename. For security reasons, a detached signature will not
read the signed material from STDIN if not explicitly specified.
Note: If the option @option{--batch} is not used, @command{@gpgname}
may assume that a single argument is a file with a detached signature,
and it will try to find a matching data file by stripping certain
suffixes. Using this historical feature to verify a detached
signature is strongly discouraged; you should always specify the data file
explicitly.
Note: When verifying a cleartext signature, @command{@gpgname} verifies
only what makes up the cleartext signed data and not any extra data
outside of the cleartext signature or the header lines directly following
the dash marker line. The option @code{--output} may be used to write
out the actual signed data, but there are other pitfalls with this
format as well. It is suggested to avoid cleartext signatures in
favor of detached signatures.
Note: To check whether a file was signed by a certain key the option
@option{--assert-signer} can be used. As an alternative the
@command{gpgv} tool can be used. @command{gpgv} is designed to
compare signed data against a list of trusted keys and returns with
success only for a good signature. It has its own manual page.
@item --multifile
@opindex multifile
This modifies certain other commands to accept multiple files for
processing on the command line or read from STDIN with each filename on
a separate line. This allows for many files to be processed at
once. @option{--multifile} may currently be used along with
@option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
@option{--multifile --verify} may not be used with detached signatures.
@item --verify-files
@opindex verify-files
Identical to @option{--multifile --verify}.
@item --encrypt-files
@opindex encrypt-files
Identical to @option{--multifile --encrypt}.
@item --decrypt-files
@opindex decrypt-files
Identical to @option{--multifile --decrypt}.
@item --list-keys
@itemx -k
@itemx --list-public-keys
@opindex list-keys
List the specified keys. If no keys are specified, then all keys from
the configured public keyrings are listed.
Never use the output of this command in scripts or other programs.
The output is intended only for humans and its format is likely to
change. The @option{--with-colons} option emits the output in a
stable, machine-parseable format, which is intended for use by scripts
and other programs.
@item --list-secret-keys
@itemx -K
@opindex list-secret-keys
List the specified secret keys. If no keys are specified, then all
known secret keys are listed. A @code{#} after the initial tags
@code{sec} or @code{ssb} means that the secret key or subkey is
currently not usable. We also say that this key has been taken
offline (for example, a primary key can be taken offline by exporting
the key using the command @option{--export-secret-subkeys}). A
@code{>} after these tags indicate that the key is stored on a
smartcard. See also @option{--list-keys}.
@item --check-signatures
@opindex check-signatures
@itemx --check-sigs
@opindex check-sigs
Same as @option{--list-keys}, but the key signatures are verified and
listed too. Note that for performance reasons the revocation status
of a signing key is not shown. This command has the same effect as
using @option{--list-keys} with @option{--with-sig-check}.
The status of the verification is indicated by a flag directly
following the "sig" tag (and thus before the flags described below. A
"!" indicates that the signature has been successfully verified, a "-"
denotes a bad signature and a "%" is used if an error occurred while
checking the signature (e.g., a non supported algorithm). Signatures
where the public key is not available are not listed; to see their
keyids the command @option{--list-sigs} can be used.
For each signature listed, there are several flags in between the
signature status flag and keyid. These flags give additional
information about each key signature. From left to right, they are
the numbers 1--3 for certificate check level (see
@option{--ask-cert-level}), "L" for a local or non-exportable
signature (see @option{--lsign-key}), "R" for a nonRevocable signature
(see the @option{--edit-key} command "nrsign"), "P" for a signature
that contains a policy URL (see @option{--cert-policy-url}), "N" for a
signature that contains a notation (see @option{--cert-notation}), "X"
for an eXpired signature (see @option{--ask-cert-expire}), and the
numbers 1--9 or "T" for 10 and above to indicate trust signature levels
(see the @option{--edit-key} command "tsign").
@item --locate-keys
@itemx --locate-external-keys
@opindex locate-keys
@opindex locate-external-keys
Locate the keys given as arguments. This command basically uses the
same algorithm as used when locating keys for encryption and may thus
be used to see what keys @command{@gpgname} might use. In particular
external methods as defined by @option{--auto-key-locate} are used to
locate a key if the arguments comain valid mail addresses. Only
public keys are listed.
The variant @option{--locate-external-keys} does not consider a
locally existing key and can thus be used to force the refresh of a
key via the defined external methods. If a fingerprint is given and
and the methods defined by @option{--auto-key-locate} define LDAP
servers, the key is fetched from these resources; defined non-LDAP
keyservers are skipped.
@item --show-keys
@opindex show-keys
This commands takes OpenPGP keys as input and prints information about
them in the same way the command @option{--list-keys} does for locally
stored key. In addition the list options @code{show-unusable-uids},
@code{show-unusable-subkeys}, @code{show-notations} and
@code{show-policy-urls} are also enabled. As usual for automated
processing, this command should be combined with the option
@option{--with-colons}.
@item --fingerprint
@opindex fingerprint
List all keys (or the specified ones) along with their
fingerprints. This is the same output as @option{--list-keys} but with
the additional output of a line with the fingerprint. May also be
combined with @option{--check-signatures}. If this
command is given twice, the fingerprints of all secondary keys are
listed too. This command also forces pretty printing of fingerprints
if the keyid format has been set to "none".
@item --list-packets
@opindex list-packets
List only the sequence of packets. This command is only useful for
debugging. When used with option @option{--verbose} the actual MPI
values are dumped and not only their lengths. Note that the output of
this command may change with new releases.
@item --edit-card
@opindex edit-card
@itemx --card-edit
@opindex card-edit
Present a menu to work with a smartcard. The subcommand "help"
provides an overview on available commands. For a detailed
description, please see the Card HOWTO at
https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO . Please
note that the command "openpgp" can be used to switch to the OpenPGP
application of cards which by default are presenting another
application (e.g., PIV).
@item --card-status
@opindex card-status
Show the content of the smart card.
@item --change-pin
@opindex change-pin
Present a menu to allow changing the PIN of a smartcard. This
functionality is also available as the subcommand "passwd" with the
@option{--edit-card} command.
@item --delete-keys @var{name}
@opindex delete-keys
Remove key from the public keyring. In batch mode either @option{--yes} is
required or the key must be specified by fingerprint. This is a
safeguard against accidental deletion of multiple keys. If the
exclamation mark syntax is used with the fingerprint of a subkey only
that subkey is deleted; if the exclamation mark is used with the
fingerprint of the primary key the entire public key is deleted.
@item --delete-secret-keys @var{name}
@opindex delete-secret-keys
Remove key from the secret keyring. In batch mode the key must be
specified by fingerprint. The option @option{--yes} can be used to
advise gpg-agent not to request a confirmation. This extra
pre-caution is done because @command{@gpgname} can't be sure that the
secret key (as controlled by gpg-agent) is only used for the given
OpenPGP public key. If the exclamation mark syntax is used with the
fingerprint of a subkey only the secret part of that subkey is
deleted; if the exclamation mark is used with the fingerprint of the
primary key only the secret part of the primary key is deleted.
@item --delete-secret-and-public-key @var{name}
@opindex delete-secret-and-public-key
Same as @option{--delete-key}, but if a secret key exists, it will be
removed first. In batch mode the key must be specified by fingerprint.
The option @option{--yes} can be used to advise gpg-agent not to
request a confirmation.
@item --export
@opindex export
Either export all keys from all keyrings (default keyring and those
registered via option @option{--keyring}), or if at least one name is given,
those of the given name. The exported keys are written to STDOUT or to the
file given with option @option{--output}. Use together with
@option{--armor} to mail those keys.
@item --send-keys @var{keyIDs}
@opindex send-keys
Similar to @option{--export} but sends the keys to a keyserver.
Fingerprints may be used instead of key IDs.
Don't send your complete keyring to a keyserver --- select
only those keys which are new or changed by you. If no @var{keyIDs}
are given, @command{@gpgname} does nothing.
Take care: Keyservers are by design write only systems and thus it is
not possible to ever delete keys once they have been send to a
keyserver.
@item --export-secret-keys
@itemx --export-secret-subkeys
@opindex export-secret-keys
@opindex export-secret-subkeys
Same as @option{--export}, but exports the secret keys instead. The
exported keys are written to STDOUT or to the file given with option
@option{--output}. This command is often used along with the option
@option{--armor} to allow for easy printing of the key for paper backup;
however the external tool @command{paperkey} does a better job of
creating backups on paper. Note that exporting a secret key can be a
security risk if the exported keys are sent over an insecure channel.
The second form of the command has the special property to render the
secret part of the primary key useless; this is a GNU extension to
OpenPGP and other implementations can not be expected to successfully
import such a key. Its intended use is in generating a full key with
an additional signing subkey on a dedicated machine. This command
then exports the key without the primary key to the main machine.
GnuPG may ask you to enter the passphrase for the key. This is
required, because the internal protection method of the secret key is
different from the one specified by the OpenPGP protocol.
@item --export-ssh-key
@opindex export-ssh-key
This command is used to export a key in the OpenSSH public key format.
It requires the specification of one key by the usual means and
exports the latest valid subkey which has an authentication capability
to STDOUT or to the file given with option @option{--output}. That
output can directly be added to ssh's @file{authorized_key} file.
By specifying the key to export using a key ID or a fingerprint
suffixed with an exclamation mark (!), a specific subkey or the
primary key can be exported. This does not even require that the key
has the authentication capability flag set.
@item --import
@itemx --fast-import
@opindex import
Import/merge keys. This adds the given keys to the
keyring. The fast version is currently just a synonym.
There are a few other options which control how this command works.
Most notable here is the @option{--import-options merge-only} option
which does not insert new keys but does only the merging of new
signatures, user-IDs and subkeys.
@item --receive-keys @var{keyIDs}
@opindex receive-keys
@itemx --recv-keys @var{keyIDs}
@opindex recv-keys
Import the keys with the given @var{keyIDs} from a keyserver.
@item --refresh-keys
@opindex refresh-keys
Request updates from a keyserver for keys that already exist on the
local keyring. This is useful for updating a key with the latest
signatures, user IDs, etc. Calling this with no arguments will refresh
the entire keyring.
@item --search-keys @var{names}
@opindex search-keys
Search the keyserver for the given @var{names}. Multiple names given
here will be joined together to create the search string for the
keyserver. Note that keyservers search for @var{names} in a different
and simpler way than gpg does. The best choice is to use a mail
address. Due to data privacy reasons keyservers may even not even
allow searching by user id or mail address and thus may only return
results when being used with the @option{--recv-key} command to
search by key fingerprint or keyid.
@item --fetch-keys @var{URIs}
@opindex fetch-keys
Retrieve keys located at the specified @var{URIs}. Note that different
installations of GnuPG may support different protocols (HTTP, FTP,
LDAP, etc.). When using HTTPS the system provided root certificates
are used by this command.
@item --update-trustdb
@opindex update-trustdb
Do trust database maintenance. This command iterates over all keys and
builds the Web of Trust. This is an interactive command because it may
have to ask for the "ownertrust" values for keys. The user has to give
an estimation of how far she trusts the owner of the displayed key to
correctly certify (sign) other keys. GnuPG only asks for the ownertrust
value if it has not yet been assigned to a key. Using the
@option{--edit-key} menu, the assigned value can be changed at any time.
@item --check-trustdb
@opindex check-trustdb
Do trust database maintenance without user interaction. From time to
time the trust database must be updated so that expired keys or
signatures and the resulting changes in the Web of Trust can be
tracked. Normally, GnuPG will calculate when this is required and do it
automatically unless @option{--no-auto-check-trustdb} is set. This
command can be used to force a trust database check at any time. The
processing is identical to that of @option{--update-trustdb} but it
skips keys with a not yet defined "ownertrust".
For use with cron jobs, this command can be used together with
@option{--batch} in which case the trust database check is done only if
a check is needed. To force a run even in batch mode add the option
@option{--yes}.
@anchor{option --export-ownertrust}
@item --export-ownertrust
@opindex export-ownertrust
Send the ownertrust values to STDOUT. This is useful for backup purposes
as these values are the only ones which can't be re-created from a
corrupted trustdb. Example:
@c man:.RS
@example
@gpgname{} --export-ownertrust > otrust.txt
@end example
@c man:.RE
@item --import-ownertrust
@opindex import-ownertrust
Update the trustdb with the ownertrust values stored in @code{files} (or
STDIN if not given); existing values will be overwritten. In case of a
severely damaged trustdb and if you have a recent backup of the
ownertrust values (e.g., in the file @file{otrust.txt}), you may re-create
the trustdb using these commands:
@c man:.RS
@example
cd ~/.gnupg
rm trustdb.gpg
@gpgname{} --import-ownertrust < otrust.txt
@end example
@c man:.RE
@item --rebuild-keydb-caches
@opindex rebuild-keydb-caches
When updating from version 1.0.6 to 1.0.7 this command should be used
to create signature caches in the keyring. It might be handy in other
situations too.
@item --print-md @var{algo}
@itemx --print-mds
@opindex print-md
Print message digest of algorithm @var{algo} for all given files or STDIN.
With the second form (or a deprecated "*" for @var{algo}) digests for all
available algorithms are printed.
@item --gen-random @var{0|1|2|16|30} @var{count}
@opindex gen-random
Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
@var{count} is not given or zero, an endless sequence of random bytes
will be emitted. If used with @option{--armor} the output will be
base64 encoded. The special level 16 uses a quality level of 1 and
outputs an endless stream of hex-encoded octets. The special level
30 outputs random as 30 zBase-32 characters.
@item --gen-prime @var{mode} @var{bits}
@opindex gen-prime
Use the source, Luke :-). The output format is subject to change
with any release.
@item --enarmor
@itemx --dearmor
@opindex enarmor
@opindex dearmor
Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
This is a GnuPG extension to OpenPGP and in general not very useful.
The @option{--dearmor} command can also be used to dearmor PEM armors.
@item --unwrap
@opindex unwrap
This option modifies the command @option{--decrypt} to output the
original message with the encryption layer removed. Thus the output
will be an OpenPGP data structure which often means a signed OpenPGP
message. Note that this option may or may not remove a compression
layer which is often found beneath the encryption layer.
@item --tofu-policy @{auto|good|unknown|bad|ask@} @var{keys}
@opindex tofu-policy
Set the TOFU policy for all the bindings associated with the specified
@var{keys}. For more information about the meaning of the policies,
@pxref{trust-model-tofu}. The @var{keys} may be specified either by their
fingerprint (preferred) or their keyid.
@c @item --server
@c @opindex server
@c Run gpg in server mode. This feature is not yet ready for use and
@c thus not documented.
@end table
@c ********************************************
@c ******* KEY MANAGEMENT COMMANDS **********
@c ********************************************
@node OpenPGP Key Management
@subsection How to manage your keys
This section explains the main commands for key management.
@table @gnupgtabopt
@item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
@itemx --quick-gen-key
@opindex quick-generate-key
@opindex quick-gen-key
This is a simple command to generate a standard key with one user id.
In contrast to @option{--generate-key} the key is generated directly
without the need to answer a bunch of prompts. Unless the option
@option{--yes} is given, the key creation will be canceled if the
given user id already exists in the keyring.
If invoked directly on the console without any special options an
answer to a ``Continue?'' style confirmation prompt is required. In
case the user id already exists in the keyring a second prompt to
force the creation of the key will show up.
If @var{algo} or @var{usage} are given, only the primary key is
created and no prompts are shown. To specify an expiration date but
still create a primary and subkey use ``default'' or
``future-default'' for @var{algo} and ``default'' for @var{usage}.
For a description of these optional arguments see the command
@code{--quick-add-key}. The @var{usage} accepts also the value
``cert'' which can be used to create a certification only primary key;
the default is to a create certification and signing key.
The @var{expire} argument can be used to specify an expiration date
for the key. Several formats are supported; commonly the ISO formats
``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
expire in N seconds, N days, N weeks, N months, or N years use
``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
specifying a value, or using ``-'' results in a key expiring in a
reasonable default interval. The values ``never'', ``none'' can be
used for no expiration date.
If this command is used with @option{--batch},
@option{--pinentry-mode} has been set to @code{loopback}, and one of
the passphrase options (@option{--passphrase},
@option{--passphrase-fd}, or @option{--passphrase-file}) is used, the
supplied passphrase is used for the new key and the agent does not ask
for it. To create a key without any protection @code{--passphrase ''}
may be used.
To create an OpenPGP key from the keys available on the currently
inserted smartcard, the special string ``card'' can be used for
@var{algo}. If the card features an encryption and a signing key, gpg
will figure them out and creates an OpenPGP key consisting of the
usual primary key and one subkey. This works only with certain
smartcards. Note that the interactive @option{--full-gen-key} command
allows one to do the same but with greater flexibility in the selection of
the smartcard keys.
Note that it is possible to create a primary key and a subkey using
non-default algorithms by using ``default'' and changing the default
parameters using the option @option{--default-new-key-algo}.
@item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
@opindex quick-set-expire
With two arguments given, directly set the expiration time of the
primary key identified by @var{fpr} to @var{expire}. To remove the
expiration time @code{0} can be used. With three arguments and the
third given as an asterisk, the expiration time of all non-revoked and
not yet expired subkeys are set to @var{expire}. With more than two
arguments and a list of fingerprints given for @var{subfprs}, all
non-revoked subkeys matching these fingerprints are set to
@var{expire}.
@item --quick-add-key @var{fpr} [@var{algo} [@var{usage} [@var{expire}]]]
@opindex quick-add-key
Directly add a subkey to the key identified by the fingerprint
@var{fpr}. Without the optional arguments an encryption subkey is
added. If any of the arguments are given a more specific subkey is
added.
@var{algo} may be any of the supported algorithms or curve names
given in the format as used by key listings. To use the default
algorithm the string ``default'' or ``-'' can be used. Supported
algorithms are ``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'',
and other ECC curves. For example the string ``rsa'' adds an RSA key
with the default key length; a string ``rsa4096'' requests that the
key length is 4096 bits. The string ``future-default'' is an alias
for the algorithm which will likely be used as default algorithm in
future versions of gpg. To list the supported ECC curves the command
@code{gpg --with-colons --list-config curve} can be used.
Depending on the given @var{algo} the subkey may either be an
encryption subkey or a signing subkey. If an algorithm is capable of
signing and encryption and such a subkey is desired, a @var{usage}
string must be given. This string is either ``default'' or ``-'' to
keep the default or a comma delimited list (or space delimited list)
of keywords: ``sign'' for a signing subkey, ``auth'' for an
authentication subkey, and ``encr'' for an encryption subkey
(``encrypt'' can be used as alias for ``encr''). The valid
combinations depend on the algorithm.
The @var{expire} argument can be used to specify an expiration date
for the key. Several formats are supported; commonly the ISO formats
``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
expire in N seconds, N days, N weeks, N months, or N years use
``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
specifying a value, or using ``-'' results in a key expiring in a
reasonable default interval. The values ``never'', ``none'' can be
used for no expiration date.
@item --quick-add-adsk @var{fpr} @var{adskfpr}
@opindex quick-add-adsk
Directly add an Additional Decryption Subkey to the key identified by
the fingerprint @var{fpr}. @var{adskfpr} is the fingerprint of
another key's encryption subkey. A subkey is commonly used here
because by default a primary key has no encryption capability. Use
the option @option{--with-subkey-fingerprint} with a list command to
display the subkey fingerprints.
@item --generate-key
@opindex generate-key
@itemx --gen-key
@opindex gen-key
Generate a new key pair using the current default parameters. This is
the standard command to create a new key. In addition to the key a
revocation certificate is created and stored in the
@file{openpgp-revocs.d} directory below the GnuPG home directory.
@item --full-generate-key
@opindex full-generate-key
@itemx --full-gen-key
@opindex full-gen-key
Generate a new key pair with dialogs for all options. This is an
extended version of @option{--generate-key}.
There is also a feature which allows you to create keys in batch
mode. See the manual section ``Unattended key generation'' on how
to use this.
@item --generate-revocation @var{name}
@opindex generate-revocation
@itemx --gen-revoke @var{name}
@opindex gen-revoke
Generate a revocation certificate for the complete key. To only revoke
a subkey or a key signature, use the @option{--edit} command.
This command merely creates the revocation certificate so that it can
be used to revoke the key if that is ever needed. To actually revoke
a key the created revocation certificate needs to be merged with the
key to revoke. This is done by importing the revocation certificate
using the @option{--import} command. Then the revoked key needs to be
published, which is best done by sending the key to a keyserver
(command @option{--send-key}) and by exporting (@option{--export}) it
to a file which is then send to frequent communication partners.
@item --generate-designated-revocation @var{name}
@opindex generate-designated-revocation
@itemx --desig-revoke @var{name}
@opindex desig-revoke
Generate a designated revocation certificate for a key. This allows a
user (with the permission of the keyholder) to revoke someone else's
key.
@item --edit-key
@opindex edit-key
Present a menu which enables you to do most of the key management
related tasks. It expects the specification of a key on the command
line.
@c ******** Begin Edit-key Options **********
@table @asis
@item uid @var{n}
@opindex keyedit:uid
Toggle selection of user ID or photographic user ID with index @var{n}.
Use @code{*} to select all and @code{0} to deselect all.
@item key @var{n}
@opindex keyedit:key
Toggle selection of subkey with index @var{n} or key ID @var{n}.
Use @code{*} to select all and @code{0} to deselect all.
@item sign
@opindex keyedit:sign
Make a signature on key of user @code{name}. If the key is not yet
signed by the default user (or the users given with @option{-u}), the program
displays the information of the key again, together with its
fingerprint and asks whether it should be signed. This question is
repeated for all users specified with
@option{-u}.
@item lsign
@opindex keyedit:lsign
Same as "sign" but the signature is marked as non-exportable and will
therefore never be used by others. This may be used to make keys
valid only in the local environment.
@item nrsign
@opindex keyedit:nrsign
Same as "sign" but the signature is marked as non-revocable and can
therefore never be revoked.
@item tsign
@opindex keyedit:tsign
Make a trust signature. This is a signature that combines the notions
of certification (like a regular signature), and trust (like the
"trust" command). It is generally useful in distinct communities
or groups to implement the concept of a Trusted Introducer. For
more information please read the sections ``Trust Signature'' and
``Regular Expression'' in RFC-4880.
@end table
@c man:.RS
Note that "l" (for local / non-exportable), "nr" (for non-revocable,
and "t" (for trust) may be freely mixed and prefixed to "sign" to
create a signature of any type desired.
@c man:.RE
If the option @option{--only-sign-text-ids} is specified, then any
non-text based user ids (e.g., photo IDs) will not be selected for
signing.
@table @asis
@item delsig
@opindex keyedit:delsig
Delete a signature. Note that it is not possible to retract a signature,
once it has been send to the public (i.e., to a keyserver). In that case
you better use @code{revsig}.
@item revsig
@opindex keyedit:revsig
Revoke a signature. For every signature which has been generated by
one of the secret keys, GnuPG asks whether a revocation certificate
should be generated.
@item check
@opindex keyedit:check
Check the signatures on all selected user IDs. With the extra
option @code{selfsig} only self-signatures are shown.
@item adduid
@opindex keyedit:adduid
Create an additional user ID.
@item addphoto
@opindex keyedit:addphoto
Create a photographic user ID. This will prompt for a JPEG file that
will be embedded into the user ID. Note that a very large JPEG will make
for a very large key. Also note that some programs will display your
JPEG unchanged (GnuPG), and some programs will scale it to fit in a
dialog box (PGP).
@item showphoto
@opindex keyedit:showphoto
Display the selected photographic user ID.
@item deluid
@opindex keyedit:deluid
Delete a user ID or photographic user ID. Note that it is not
possible to retract a user id, once it has been send to the public
(i.e., to a keyserver). In that case you better use @code{revuid}.
@item revuid
@opindex keyedit:revuid
Revoke a user ID or photographic user ID.
@item primary
@opindex keyedit:primary
Flag the current user id as the primary one, removes the primary user
id flag from all other user ids and sets the timestamp of all affected
self-signatures one second ahead. Note that setting a photo user ID
as primary makes it primary over other photo user IDs, and setting a
regular user ID as primary makes it primary over other regular user
IDs.
@item keyserver
@opindex keyedit:keyserver
Set a preferred keyserver for the specified user ID(s). This allows
other users to know where you prefer they get your key from. See
@option{--keyserver-options honor-keyserver-url} for more on how this
works. Setting a value of "none" removes an existing preferred
keyserver.
@item notation
@opindex keyedit:notation
Set a name=value notation for the specified user ID(s). See
@option{--cert-notation} for more on how this works. Setting a value of
"none" removes all notations, setting a notation prefixed with a minus
sign (-) removes that notation, and setting a notation name (without the
=value) prefixed with a minus sign removes all notations with that name.
@item pref
@opindex keyedit:pref
List preferences from the selected user ID. This shows the actual
preferences, without including any implied preferences.
@item showpref
@opindex keyedit:showpref
More verbose preferences listing for the selected user ID. This shows
the preferences in effect by including the implied preferences of 3DES
(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
not already included in the preference list. In addition, the
preferred keyserver and signature notations (if any) are shown.
@item setpref @var{string}
@opindex keyedit:setpref
Set the list of user ID preferences to @var{string} for all (or just
the selected) user IDs. Calling setpref with no arguments sets the
preference list to the default (either built-in or set via
@option{--default-preference-list}), and calling setpref with "none"
as the argument sets an empty preference list. Use @command{@gpgname
--version} to get a list of available algorithms. Note that while you
can change the preferences on an attribute user ID (aka "photo ID"),
GnuPG does not select keys via attribute user IDs so these preferences
will not be used by GnuPG. Note that an unattended version of this
command is available as @option{--quick-update-pref}.
When setting preferences, you should list the algorithms in the order
which you'd like to see them used by someone else when encrypting a
message to your key. If you don't include 3DES, it will be
automatically added at the end. Note that there are many factors that
go into choosing an algorithm (for example, your key may not be the
only recipient), and so the remote OpenPGP application being used to
send to you may or may not follow your exact chosen order for a given
message. It will, however, only choose an algorithm that is present
on the preference list of every recipient key. See also the
INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
@item addkey
@opindex keyedit:addkey
Add a subkey to this key.