-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathman_gpg
2126 lines (1577 loc) · 123 KB
/
man_gpg
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
GPG(1) GNU Privacy Guard 1.4 GPG(1)
NAME
gpg - OpenPGP encryption and signing tool
SYNOPSIS
gpg [--homedir dir] [--options file] [options] command [args]
DESCRIPTION
gpg is the OpenPGP only version of the GNU Privacy Guard (GnuPG). It is a tool to provide digital encryption
and signing services using the OpenPGP standard. gpg features complete key management and all bells and whis‐
tles you can expect from a decent OpenPGP implementation.
This is the standalone version of gpg. For desktop use you should consider using gpg2 from the GnuPG-2 package
([On some platforms gpg2 is installed under the name gpg]).
RETURN VALUE
The program returns 0 if everything was fine, 1 if at least a signature was bad, and other error codes for
fatal errors.
WARNINGS
Use a *good* password for your user account and a *good* passphrase to protect your secret key. This passphrase
is the weakest part of the whole system. Programs to do dictionary attacks on your secret keyring are very easy
to write and so you should protect your "~/.gnupg/" directory very well.
Keep in mind that, if this program is used over a network (telnet), it is *very* easy to spy out your
passphrase!
If you are going to verify detached signatures, make sure that the program knows about it; either give both
filenames on the command line or use '-' to specify STDIN.
INTEROPERABILITY
GnuPG tries to be a very flexible implementation of the OpenPGP standard. In particular, GnuPG implements many
of the optional parts of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2 compression algorithms.
It is important to be aware that not all OpenPGP programs implement these optional algorithms and that by forc‐
ing their use via the --cipher-algo, --digest-algo, --cert-digest-algo, or --compress-algo options in GnuPG, it
is possible to create a perfectly valid OpenPGP message, but one that cannot be read by the intended recipient.
There are dozens of variations of OpenPGP programs available, and each supports a slightly different subset of
these optional algorithms. For example, until recently, no (unhacked) version of PGP supported the BLOWFISH
cipher algorithm. A message using BLOWFISH simply could not be read by a PGP user. By default, GnuPG uses the
standard OpenPGP preferences system that will always do the right thing and create messages that are usable by
all recipients, regardless of which OpenPGP program they use. Only override this safe default if you really
know what you are doing.
If you absolutely must override the safe default, or if the preferences on a given key are invalid for some
reason, you are far better off using the --pgp6, --pgp7, or --pgp8 options. These options are safe as they do
not force any particular algorithms in violation of OpenPGP, but rather reduce the available algorithms to a
"PGP-safe" list.
COMMANDS
Commands are not distinguished from options except for the fact that only one command is allowed.
gpg may be run with no commands, in which case it will 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).
Please remember that option as well as command parsing stops as soon as a non-option is encountered, you can
explicitly stop parsing by using the special option --.
Commands not specific to the function
--version
Print the program version and licensing information. Note that you cannot abbreviate this command.
--help
-h Print a usage message summarizing the most useful command line options. Note that you cannot abbreviate
this command.
--warranty
Print warranty information.
--dump-options
Print a list of all available options and commands. Note that you cannot abbreviate this command.
Commands to select the type of operation
--sign
-s Make a signature. This command may be combined with --encrypt (for a signed and encrypted message),
--symmetric (for a signed and symmetrically encrypted message), or --encrypt and --symmetric together
(for a signed message that may be decrypted via a secret key or a passphrase). The key to be used for
signing is chosen by default or can be set with the --local-user and --default-key options.
--clearsign
Make a clear text signature. The content in a clear text signature is readable without any special
software. OpenPGP software is only needed to verify the signature. Clear text signatures may modify
end-of-line whitespace for platform independence and are not intended to be reversible. The key to be
used for signing is chosen by default or can be set with the --local-user and --default-key options.
--detach-sign
-b Make a detached signature.
--encrypt
-e Encrypt data. This option may be combined with --sign (for a signed and encrypted message), --symmetric
(for a message that may be decrypted via a secret key or a passphrase), or --sign and --symmetric
together (for a signed message that may be decrypted via a secret key or a passphrase).
--symmetric
-c Encrypt with a symmetric cipher using a passphrase. The default symmetric cipher used is AES128, but may
be chosen with the --cipher-algo option. This option may be combined with --sign (for a signed and sym‐
metrically encrypted message), --encrypt (for a message that may be decrypted via a secret key or a
passphrase), or --sign and --encrypt together (for a signed message that may be decrypted via a secret
key or a passphrase).
--store
Store only (make a simple RFC1991 literal data packet).
--decrypt
-d 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 --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 which don't begin with an encrypted message.
--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 a one argument is given, it is expected to
be a complete signature.
With more than 1 argument, the first should be a detached signature and the remaining files ake up the
the signed data. To read the signed data from STDIN, use '-' as the second filename. For security rea‐
sons a detached signature cannot read the signed material from STDIN without denoting it in the above
way.
Note: If the option --batch is not used, gpg 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 his‐
torical feature to verify a detached signature is strongly discouraged; always specify the data file
too.
Note: When verifying a cleartext signature, gpg verifies only what makes up the cleartext signed data
and not any extra data outside of the cleartext signature or header lines following directly the dash
marker line. The option --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.
--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.
--multifile may currently be used along with --verify, --encrypt, and --decrypt. Note that --multifile
--verify may not be used with detached signatures.
--verify-files
Identical to --multifile --verify.
--encrypt-files
Identical to --multifile --encrypt.
--decrypt-files
Identical to --multifile --decrypt.
--list-keys
-k
--list-public-keys
List all keys from the public keyrings, or just the keys given on the command line.
-k is slightly different from --list-keys in that it allows only for one argument and takes the second
argument as the keyring to search. This is for command line compatibility with PGP 2 and has been
removed in gpg2.
Avoid using the output of this command in scripts or other programs as it is likely to change as GnuPG
changes. See --with-colons for a machine-parseable key listing command that is appropriate for use in
scripts and other programs.
--list-secret-keys
-K List all keys from the secret keyrings, or just the ones given on the command line. A # after the let‐
ters sec means that the secret key is not usable (for example, if it was created via --export-secret-
subkeys).
--list-sigs
Same as --list-keys, but the signatures are listed too.
For each signature listed, there are several flags in between the "sig" tag and keyid. These flags give
additional information about each signature. From left to right, they are the numbers 1-3 for certifi‐
cate check level (see --ask-cert-level), "L" for a local or non-exportable signature (see --lsign-key),
"R" for a nonRevocable signature (see the --edit-key command "nrsign"), "P" for a signature that con‐
tains a policy URL (see --cert-policy-url), "N" for a signature that contains a notation (see --cert-
notation), "X" for an eXpired signature (see --ask-cert-expire), and the numbers 1-9 or "T" for 10 and
above to indicate trust signature levels (see the --edit-key command "tsign").
--check-sigs
Same as --list-sigs, but the signatures are verified. Note that for performance reasons the revocation
status of a signing key is not shown.
The status of the verification is indicated by a flag directly following the "sig" tag (and thus before
the flags described above for --list-sigs). 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 signa‐
ture (e.g. a non supported algorithm).
--fingerprint
List all keys (or the specified ones) along with their fingerprints. This is the same output as --list-
keys but with the additional output of a line with the fingerprint. May also be combined with --list-
sigs or --check-sigs. If this command is given twice, the fingerprints of all secondary keys are listed
too.
--list-packets
List only the sequence of packets. This is mainly useful for debugging.
--card-edit
Present a menu to work with a smartcard. The subcommand "help" provides an overview on available com‐
mands. For a detailed description, please see the Card HOWTO at https://gnupg.org/documentation/how‐
tos.html#GnuPG-cardHOWTO .
--card-status
Show the content of the smart card.
--change-pin
Present a menu to allow changing the PIN of a smartcard. This functionality is also available as the
subcommand "passwd" with the --card-edit command.
--delete-key name
Remove key from the public keyring. In batch mode either --yes is required or the key must be specified
by fingerprint. This is a safeguard against accidental deletion of multiple keys.
--delete-secret-key name
Remove key from the secret keyring. In batch mode the key must be specified by fingerprint.
--delete-secret-and-public-key name
Same as --delete-key, but if a secret key exists, it will be removed first. In batch mode the key must
be specified by fingerprint.
--export
Either export all keys from all keyrings (default keyrings and those registered via 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 --output. Use together with --armor to mail those keys.
--send-keys key IDs
Similar to --export but sends the keys to a keyserver. Fingerprints may be used instead of key IDs.
Option --keyserver must be used to give the name of this keyserver. Don't send your complete keyring to
a keyserver --- select only those keys which are new or changed by you. If no key IDs are given, gpg
does nothing.
--export-secret-keys
--export-secret-subkeys
Same as --export, but exports the secret keys instead. The exported keys are written to STDOUT or to
the file given with option --output. This command is often used along with the option --armor to allow
easy printing of the key for paper backup; however the external tool paperkey does a better job for cre‐
ating backups on paper. Note that exporting a secret key can be a security risk if the exported keys
are send 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 success‐
fully import such a key. Its intended use is to generated a full key with an additional signing subkey
on a dedicated machine and then using this command to export the key without the primary key to the main
machine.
See the option --simple-sk-checksum if you want to import an exported secret key into ancient OpenPGP
implementations.
--import
--fast-import
Import/merge keys. This adds the given keys to the keyring. The fast version is currently just a syn‐
onym.
There are a few other options which control how this command works. Most notable here is the --import-
options merge-only option which does not insert new keys but does only the merging of new signatures,
user-IDs and subkeys.
--recv-keys key IDs
Import the keys with the given key IDs from a keyserver. Option --keyserver must be used to give the
name of this keyserver.
--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. Option --keyserver must be used to give the name of the keyserver for all keys that
do not have preferred keyservers set (see --keyserver-options honor-keyserver-url).
--search-keys names
Search the keyserver for the given names. Multiple names given here will be joined together to create
the search string for the keyserver. Option --keyserver must be used to give the name of this key‐
server. Keyservers that support different search methods allow using the syntax specified in "How to
specify a user ID" below. Note that different keyserver types support different search methods. Cur‐
rently only LDAP supports them all.
--fetch-keys URIs
Retrieve keys located at the specified URIs. Note that different installations of GnuPG may support dif‐
ferent protocols (HTTP, FTP, LDAP, etc.)
--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
--edit-key menu, the assigned value can be changed at any time.
--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 --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 --update-trustdb but it skips keys with a not yet defined "ownertrust".
For use with cron jobs, this command can be used together with --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 --yes.
--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:
gpg --export-ownertrust > otrust.txt
--import-ownertrust
Update the trustdb with the ownertrust values stored in 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 own‐
ertrust values (e.g. in the file ‘otrust.txt’, you may re-create the trustdb using these commands:
cd ~/.gnupg
rm trustdb.gpg
gpg --import-ownertrust < otrust.txt
--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.
--print-md algo
--print-mds
Print message digest of algorithm ALGO for all given files or STDIN. With the second form (or a depre‐
cated "*" as algo) digests for all available algorithms are printed.
--gen-random 0|1|2 count
Emit count random bytes of the given quality level 0, 1 or 2. If count is not given or zero, an endless
sequence of random bytes will be emitted. If used with --armor the output will be base64 encoded.
PLEASE, don't use this command unless you know what you are doing; it may remove precious entropy from
the system!
--gen-prime mode bits
Use the source, Luke :-). The output format is still subject to change.
--enarmor
--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.
How to manage your keys
This section explains the main commands for key management
--gen-key
Generate a new key pair using the current default parameters. This is the standard command to create a
new key.
There is also a feature which allows you to create keys in batch mode. See the the manual section
``Unattended key generation'' on how to use this.
--gen-revoke name
Generate a revocation certificate for the complete key. To revoke a subkey or a signature, use the
--edit command.
--desig-revoke name
Generate a designated revocation certificate for a key. This allows a user (with the permission of the
keyholder) to revoke someone else's key.
--edit-key
Present a menu which enables you to do most of the key management related tasks. It expects the speci‐
fication of a key on the command line.
uid n Toggle selection of user ID or photographic user ID with index n. Use * to select all and 0 to
deselect all.
key n Toggle selection of subkey with index n. Use * to select all and 0 to deselect all.
sign Make a signature on key of user name If the key is not yet signed by the default user (or the
users given with -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 speci‐
fied with -u.
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.
nrsign Same as "sign" but the signature is marked as non-revocable and can therefore never be revoked.
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 only useful in distinct
communities or groups.
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.
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 revsig.
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.
check Check the signatures on all selected user IDs.
adduid Create an additional user ID.
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).
showphoto
Display the selected photographic user ID.
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 revuid.
revuid Revoke a user ID or photographic user ID.
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.
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 --keyserver-options honor-keyserver-url for more on how this
works. Setting a value of "none" removes an existing preferred keyserver.
notation
Set a name=value notation for the specified user ID(s). See --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.
pref List preferences from the selected user ID. This shows the actual preferences, without including
any implied preferences.
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 (compres‐
sion) if they are not already included in the preference list. In addition, the preferred key‐
server and signature notations (if any) are shown.
setpref string
Set the list of user ID preferences to 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
--default-preference-list), and calling setpref with "none" as the argument sets an empty prefer‐
ence list. Use gpg --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.
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.
addkey Add a subkey to this key.
addcardkey
Generate a subkey on a card and add it to this key.
keytocard
Transfer the selected secret subkey (or the primary key if no subkey has been selected) to a
smartcard. The secret key in the keyring will be replaced by a stub if the key could be stored
successfully on the card and you use the save command later. Only certain key types may be trans‐
ferred to the card. A sub menu allows you to select on what card to store the key. Note that it
is not possible to get that key back from the card - if the card gets broken your secret key will
be lost unless you have a backup somewhere.
bkuptocard file
Restore the given file to a card. This command may be used to restore a backup key (as generated
during card initialization) to a new card. In almost all cases this will be the encryption key.
You should use this command only with the corresponding public key and make sure that the file
given as argument is indeed the backup to restore. You should then select 2 to restore as encryp‐
tion key. You will first be asked to enter the passphrase of the backup key and then for the
Admin PIN of the card.
delkey Remove a subkey (secondart key). Note that it is not possible to retract a subkey, once it has
been send to the public (i.e. to a keyserver). In that case you better use revkey.
revkey Revoke a subkey.
expire Change the key or subkey expiration time. If a subkey is selected, the expiration time of this
subkey will be changed. With no selection, the key expiration of the primary key is changed.
trust Change the owner trust value for the key. This updates the trust-db immediately and no save is
required.
disable
enable Disable or enable an entire key. A disabled key can not normally be used for encryption.
addrevoker
Add a designated revoker to the key. This takes one optional argument: "sensitive". If a desig‐
nated revoker is marked as sensitive, it will not be exported by default (see export-options).
passwd Change the passphrase of the secret key.
toggle Toggle between public and secret key listing.
clean Compact (by removing all signatures except the selfsig) any user ID that is no longer usable
(e.g. revoked, or expired). Then, remove any signatures that are not usable by the trust calcula‐
tions. Specifically, this removes any signature that does not validate, any signature that is
superseded by a later signature, revoked signatures, and signatures issued by keys that are not
present on the keyring.
minimize
Make the key as small as possible. This removes all signatures from each user ID except for the
most recent self-signature.
cross-certify
Add cross-certification signatures to signing subkeys that may not currently have them. Cross-
certification signatures protect against a subtle attack against signing subkeys. See --require-
cross-certification. All new keys generated have this signature by default, so this option is
only useful to bring older keys up to date.
save Save all changes to the key rings and quit.
quit Quit the program without updating the key rings.
The listing shows you the key with its secondary keys and all user ids. The primary user id is indi‐
cated by a dot, and selected keys or user ids are indicated by an asterisk. The trust value is dis‐
played with the primary key: the first is the assigned owner trust and the second is the calculated
trust value. Letters are used for the values:
- No ownertrust assigned / not yet calculated.
e Trust calculation has failed; probably due to an expired key.
q Not enough information for calculation.
n Never trust this key.
m Marginally trusted.
f Fully trusted.
u Ultimately trusted.
--sign-key name
Signs a public key with your secret key. This is a shortcut version of the subcommand "sign" from
--edit.
--lsign-key name
Signs a public key with your secret key but marks it as non-exportable. This is a shortcut version of
the subcommand "lsign" from --edit-key.
OPTIONS
gpg features a bunch of options to control the exact behaviour and to change the default configuration.
Long options can be put in an options file (default "~/.gnupg/gpg.conf"). Short option names will not work -
for example, "armor" is a valid option for the options file, while "a" is not. Do not write the 2 dashes, but
simply the name of the option and any required arguments. Lines with a hash ('#') as the first non-white-space
character are ignored. Commands may be put in this file too, but that is not generally useful as the command
will execute automatically with every execution of gpg.
Please remember that option parsing stops as soon as a non-option is encountered, you can explicitly stop pars‐
ing by using the special option --.
How to change the configuration
These options are used to change the configuration and are usually found in the option file.
--default-key name
Use name as the default key to sign with. If this option is not used, the default key is the first key
found in the secret keyring. Note that -u or --local-user overrides this option.
--default-recipient name
Use name as default recipient if option --recipient is not used and don't ask if this is a valid one.
name must be non-empty.
--default-recipient-self
Use the default key as default recipient if option --recipient is not used and don't ask if this is a
valid one. The default key is the first one from the secret keyring or the one set with --default-key.
--no-default-recipient
Reset --default-recipient and --default-recipient-self.
-v, --verbose
Give more information during processing. If used twice, the input data is listed in detail.
--no-verbose
Reset verbose level to 0.
-q, --quiet
Try to be as quiet as possible.
--batch
--no-batch
Use batch mode. Never ask, do not allow interactive commands. --no-batch disables this option. This
option is commonly used for unattended operations.
WARNING: Unattended operation bears a higher risk of being exposed to security attacks. In particular
any unattended use of GnuPG which involves the use of secret keys should take care not to provide an
decryption oracle. There are several standard pre-cautions against being used as an oracle. For exam‐
ple never return detailed error messages or any diagnostics printed by your software to the remote site.
Consult with an expert in case of doubt.
Note that even with a filename given on the command line, gpg might still need to read from STDIN (in
particular if gpg figures that the input is a detached signature and no data file has been specified).
Thus if you do not want to feed data via STDIN, you should connect STDIN to ‘/dev/null’.
--no-tty
Make sure that the TTY (terminal) is never used for any output. This option is needed in some cases
because GnuPG sometimes prints warnings to the TTY even if --batch is used.
--yes Assume "yes" on most questions.
--no Assume "no" on most questions.
--list-options parameters
This is a space or comma delimited string that gives options used when listing keys and signatures (that
is, --list-keys, --list-sigs, --list-public-keys, --list-secret-keys, and the --edit-key functions).
Options can be prepended with a no- (after the two dashes) to give the opposite meaning. The options
are:
show-photos
Causes --list-keys, --list-sigs, --list-public-keys, and --list-secret-keys to display any photo
IDs attached to the key. Defaults to no. See also --photo-viewer. Does not work with --with-
colons: see --attribute-fd for the appropriate way to get photo data for scripts and other fron‐
tends.
show-usage
Show usage information for keys and subkeys in the standard key listing. This is a list of let‐
ters indicating the allowed usage for a key (E=encryption, S=signing, C=certification, A=authen‐
tication). Defaults to no.
show-policy-urls
Show policy URLs in the --list-sigs or --check-sigs listings. Defaults to no.
show-notations
show-std-notations
show-user-notations
Show all, IETF standard, or user-defined signature notations in the --list-sigs or --check-sigs
listings. Defaults to no.
show-keyserver-urls
Show any preferred keyserver URL in the --list-sigs or --check-sigs listings. Defaults to no.
show-uid-validity
Display the calculated validity of user IDs during key listings. Defaults to no.
show-unusable-uids
Show revoked and expired user IDs in key listings. Defaults to no.
show-unusable-subkeys
Show revoked and expired subkeys in key listings. Defaults to no.
show-keyring
Display the keyring name at the head of key listings to show which keyring a given key resides
on. Defaults to no.
show-sig-expire
Show signature expiration dates (if any) during --list-sigs or --check-sigs listings. Defaults to
no.
show-sig-subpackets
Include signature subpackets in the key listing. This option can take an optional argument list
of the subpackets to list. If no argument is passed, list all subpackets. Defaults to no. This
option is only meaningful when using --with-colons along with --list-sigs or --check-sigs.
--verify-options parameters
This is a space or comma delimited string that gives options used when verifying signatures. Options can
be prepended with a `no-' to give the opposite meaning. The options are:
show-photos
Display any photo IDs present on the key that issued the signature. Defaults to no. See also
--photo-viewer.
show-policy-urls
Show policy URLs in the signature being verified. Defaults to no.
show-notations
show-std-notations
show-user-notations
Show all, IETF standard, or user-defined signature notations in the signature being verified.
Defaults to IETF standard.
show-keyserver-urls
Show any preferred keyserver URL in the signature being verified. Defaults to no.
show-uid-validity
Display the calculated validity of the user IDs on the key that issued the signature. Defaults to
no.
show-unusable-uids
Show revoked and expired user IDs during signature verification. Defaults to no.
show-primary-uid-only
Show only the primary user ID during signature verification. That is all the AKA lines as well
as photo Ids are not shown with the signature verification status.
pka-lookups
Enable PKA lookups to verify sender addresses. Note that PKA is based on DNS, and so enabling
this option may disclose information on when and what signatures are verified or to whom data is
encrypted. This is similar to the "web bug" described for the auto-key-retrieve feature.
pka-trust-increase
Raise the trust in a signature to full if the signature passes PKA validation. This option is
only meaningful if pka-lookups is set.
--enable-large-rsa
--disable-large-rsa
With --gen-key and --batch, enable the creation of larger RSA secret keys than is generally recommended
(up to 8192 bits). These large keys are more expensive to use, and their signatures and certifications
are also larger.
--enable-dsa2
--disable-dsa2
Enable hash truncation for all DSA keys even for old DSA Keys up to 1024 bit. This is also the default
with --openpgp. Note that older versions of GnuPG also required this flag to allow the generation of
DSA larger than 1024 bit.
--photo-viewer string
This is the command line that should be run to view a photo ID. "%i" will be expanded to a filename con‐
taining the photo. "%I" does the same, except the file will not be deleted once the viewer exits. Other
flags are "%k" for the key ID, "%K" for the long key ID, "%f" for the key fingerprint, "%t" for the
extension of the image type (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"), "%v"
for the single-character calculated validity of the image being viewed (e.g. "f"), "%V" for the calcu‐
lated validity as a string (e.g. "full"), "%U" for a base32 encoded hash of the user ID, and "%%" for
an actual percent sign. If neither %i or %I are present, then the photo will be supplied to the viewer
on standard input.
The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN". Note that if your image
viewer program is not secure, then executing it from GnuPG does not make it secure.
--exec-path string
Sets a list of directories to search for photo viewers and keyserver helpers. If not provided, keyserver
helpers use the compiled-in default directory, and photo viewers use the $PATH environment variable.
Note, that on W32 system this value is ignored when searching for keyserver helpers.
--keyring file
Add file to the current list of keyrings. If file begins with a tilde and a slash, these are replaced by
the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home
directory ("~/.gnupg" if --homedir or $GNUPGHOME is not used).
Note that this adds a keyring to the current list. If the intent is to use the specified keyring alone,
use --keyring along with --no-default-keyring.
--secret-keyring file
Same as --keyring but for the secret keyrings.
--primary-keyring file
Designate file as the primary public keyring. This means that newly imported keys (via --import or key‐
server --recv-from) will go to this keyring.
--trustdb-name file
Use file instead of the default trustdb. If file begins with a tilde and a slash, these are replaced by
the $HOME directory. If the filename does not contain a slash, it is assumed to be in the GnuPG home
directory (‘~/.gnupg’ if --homedir or $GNUPGHOME is not used).
--homedir dir
Set the name of the home directory to dir. If this option is not used, the home directory defaults to
‘~/.gnupg’. It is only recognized when given on the command line. It also overrides any home directory
stated through the environment variable ‘GNUPGHOME’ or (on Windows systems) by means of the Registry
entry HKCU\Software\GNU\GnuPG:HomeDir.
On Windows systems it is possible to install GnuPG as a portable application. In this case only this
command line option is considered, all other ways to set a home directory are ignored.
To install GnuPG as a portable application under Windows, create an empty file name ‘gpgconf.ctl’ in the
same directory as the tool ‘gpgconf.exe’. The root of the installation is than that directory; or, if
‘gpgconf.exe’ has been installed directly below a directory named ‘bin’, its parent directory. You also
need to make sure that the following directories exist and are writable: ‘ROOT/home’ for the GnuPG home
and ‘ROOT/var/cache/gnupg’ for internal cache files.
--pcsc-driver file
Use file to access the smartcard reader. The current default is `libpcsclite.so.1' for GLIBC based sys‐
tems, `/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X, `winscard.dll' for Windows and
`libpcsclite.so' for other systems.
--disable-ccid
Disable the integrated support for CCID compliant readers. This allows to fall back to one of the other
drivers even if the internal CCID driver can handle the reader. Note, that CCID support is only avail‐
able if libusb was available at build time.
--reader-port number_or_string
This option may be used to specify the port of the card terminal. A value of 0 refers to the first
serial device; add 32768 to access USB devices. The default is 32768 (first USB device). PC/SC or CCID
readers might need a string here; run the program in verbose mode to get a list of available readers.
The default is then the first reader found.
--display-charset name
Set the name of the native character set. This is used to convert some informational strings like user
IDs to the proper UTF-8 encoding. Note that this has nothing to do with the character set of data to be
encrypted or signed; GnuPG does not recode user-supplied data. If this option is not used, the default
character set is determined from the current locale. A verbosity level of 3 shows the chosen set. Valid
values for name are:
iso-8859-1
This is the Latin 1 set.
iso-8859-2
The Latin 2 set.
iso-8859-15
This is currently an alias for the Latin 1 set.
koi8-r The usual Russian set (rfc1489).
utf-8 Bypass all translations and assume that the OS uses native UTF-8 encoding.
--utf8-strings
--no-utf8-strings
Assume that command line arguments are given as UTF8 strings. The default (--no-utf8-strings) is to
assume that arguments are encoded in the character set as specified by --display-charset. These options
affect all following arguments. Both options may be used multiple times.
--options file
Read options from file and do not try to read them from the default options file in the homedir (see
--homedir). This option is ignored if used in an options file.
--no-options
Shortcut for --options /dev/null. This option is detected before an attempt to open an option file.
Using this option will also prevent the creation of a ‘~/.gnupg’ homedir.
-z n
--compress-level n
--bzip2-compress-level n
Set compression level to n for the ZIP and ZLIB compression algorithms. The default is to use the
default compression level of zlib (normally 6). --bzip2-compress-level sets the compression level for
the BZIP2 compression algorithm (defaulting to 6 as well). This is a different option from --compress-
level since BZIP2 uses a significant amount of memory for each additional compression level. -z sets
both. A value of 0 for n disables compression.
--bzip2-decompress-lowmem
Use a different decompression method for BZIP2 compressed files. This alternate method uses a bit more
than half the memory, but also runs at half the speed. This is useful under extreme low memory circum‐
stances when the file was originally compressed at a high --bzip2-compress-level.
--mangle-dos-filenames
--no-mangle-dos-filenames
Older version of Windows cannot handle filenames with more than one dot. --mangle-dos-filenames causes
GnuPG to replace (rather than add to) the extension of an output filename to avoid this problem. This
option is off by default and has no effect on non-Windows platforms.
--ask-cert-level
--no-ask-cert-level
When making a key signature, prompt for a certification level. If this option is not specified, the cer‐
tification level used is set via --default-cert-level. See --default-cert-level for information on the
specific levels and how they are used. --no-ask-cert-level disables this option. This option defaults to
no.
--default-cert-level n
The default to use for the check level when signing a key.
0 means you make no particular claim as to how carefully you verified the key.
1 means you believe the key is owned by the person who claims to own it but you could not, or did not
verify the key at all. This is useful for a "persona" verification, where you sign the key of a
pseudonymous user.
2 means you did casual verification of the key. For example, this could mean that you verified the key
fingerprint and checked the user ID on the key against a photo ID.
3 means you did extensive verification of the key. For example, this could mean that you verified the
key fingerprint with the owner of the key in person, and that you checked, by means of a hard to forge
document with a photo ID (such as a passport) that the name of the key owner matches the name in the
user ID on the key, and finally that you verified (by exchange of email) that the email address on the
key belongs to the key owner.
Note that the examples given above for levels 2 and 3 are just that: examples. In the end, it is up to
you to decide just what "casual" and "extensive" mean to you.
This option defaults to 0 (no particular claim).
--min-cert-level
When building the trust database, treat any signatures with a certification level below this as invalid.
Defaults to 2, which disregards level 1 signatures. Note that level 0 "no particular claim" signatures
are always accepted.
--trusted-key long key ID
Assume that the specified key (which must be given as a full 8 byte key ID) is as trustworthy as one of
your own secret keys. This option is useful if you don't want to keep your secret keys (or one of them)
online but still want to be able to check the validity of a given recipient's or signator's key.
--trust-model pgp|classic|direct|always|auto
Set what trust model GnuPG should follow. The models are:
pgp This is the Web of Trust combined with trust signatures as used in PGP 5.x and later. This is the
default trust model when creating a new trust database.
classic
This is the standard Web of Trust as introduced by PGP 2.
direct Key validity is set directly by the user and not calculated via the Web of Trust.
always Skip key validation and assume that used keys are always fully valid. You generally won't use
this unless you are using some external validation scheme. This option also suppresses the
"[uncertain]" tag printed with signature checks when there is no evidence that the user ID is
bound to the key. Note that this trust model still does not allow the use of expired, revoked,
or disabled keys.
auto Select the trust model depending on whatever the internal trust database says. This is the
default model if such a database already exists.
--auto-key-locate parameters
--no-auto-key-locate
GnuPG can automatically locate and retrieve keys as needed using this option. This happens when encrypt‐
ing to an email address (in the "[email protected]" form), and there are no [email protected] keys on the
local keyring. This option takes any number of the following mechanisms, in the order they are to be
tried:
cert Locate a key using DNS CERT, as specified in rfc4398.
pka Locate a key using DNS PKA.
ldap Using DNS Service Discovery, check the domain in question for any LDAP keyservers to use. If
this fails, attempt to locate the key using the PGP Universal method of checking
'ldap://keys.(thedomain)'.
keyserver
Locate a key using whatever keyserver is defined using the --keyserver option.
keyserver-URL
In addition, a keyserver URL as used in the --keyserver option may be used here to query that
particular keyserver.
local Locate the key using the local keyrings. This mechanism allows to select the order a local key
lookup is done. Thus using '--auto-key-locate local' is identical to --no-auto-key-locate.
nodefault
This flag disables the standard local key lookup, done before any of the mechanisms defined by
the --auto-key-locate are tried. The position of this mechanism in the list does not matter. It
is not required if local is also used.
clear Clear all defined mechanisms. This is useful to override mechanisms given in a config file.
--keyid-format short|0xshort|long|0xlong
Select how to display key IDs. "short" is the traditional 8-character key ID. "long" is the more accu‐
rate (but less convenient) 16-character key ID. Add an "0x" to either to include an "0x" at the begin‐
ning of the key ID, as in 0x99242560. Note that this option is ignored if the option --with-colons is
used.
--keyserver name
Use name as your keyserver. This is the server that --recv-keys, --send-keys, and --search-keys will
communicate with to receive keys from, send keys to, and search for keys on. The format of the name is a
URI: `scheme:[//]keyservername[:port]' The scheme is the type of keyserver: "hkp" for the HTTP (or com‐
patible) keyservers, "ldap" for the LDAP keyservers, or "mailto" for the Graff email keyserver. Note
that your particular installation of GnuPG may have other keyserver types available as well. Keyserver
schemes are case-insensitive. After the keyserver name, optional keyserver configuration options may be
provided. These are the same as the global --keyserver-options from below, but apply only to this par‐
ticular keyserver.
Most keyservers synchronize with each other, so there is generally no need to send keys to more than one
server. The keyserver hkp://keys.gnupg.net uses round robin DNS to give a different keyserver each time
you use it.
--keyserver-options name=value1
This is a space or comma delimited string that gives options for the keyserver. Options can be prefixed
with a `no-' to give the opposite meaning. Valid import-options or export-options may be used here as
well to apply to importing (--recv-key) or exporting (--send-key) a key from a keyserver. While not all
options are available for all keyserver types, some common options are:
include-revoked
When searching for a key with --search-keys, include keys that are marked on the keyserver as
revoked. Note that not all keyservers differentiate between revoked and unrevoked keys, and for
such keyservers this option is meaningless. Note also that most keyservers do not have crypto‐
graphic verification of key revocations, and so turning this option off may result in skipping
keys that are incorrectly marked as revoked.
include-disabled
When searching for a key with --search-keys, include keys that are marked on the keyserver as
disabled. Note that this option is not used with HKP keyservers.
auto-key-retrieve
This option enables the automatic retrieving of keys from a keyserver when verifying signatures
made by keys that are not on the local keyring.
Note that this option makes a "web bug" like behavior possible. Keyserver operators can see
which keys you request, so by sending you a message signed by a brand new key (which you natu‐
rally will not have on your local keyring), the operator can tell both your IP address and the
time when you verified the signature.
honor-keyserver-url
When using --refresh-keys, if the key in question has a preferred keyserver URL, then use that
preferred keyserver to refresh the key from. In addition, if auto-key-retrieve is set, and the
signature being verified has a preferred keyserver URL, then use that preferred keyserver to
fetch the key from. Defaults to yes.
honor-pka-record
If auto-key-retrieve is set, and the signature being verified has a PKA record, then use the PKA
information to fetch the key. Defaults to yes.
include-subkeys
When receiving a key, include subkeys as potential targets. Note that this option is not used
with HKP keyservers, as they do not support retrieving keys by subkey id.
use-temp-files