« back to all changes in this revision
Viewing changes to doc/gpg.texi
- browse files at revision 40
- compare with another revision
- download diff
- download tarball
- view history from revision 40
- Committer: Package Import Robot
- Author(s): Colin Watson
- Date: 2012-12-04 22:26:16 UTC
- mfrom: (1.1.18 sid)
- Revision ID: package-import@ubuntu.com-20121204222616-cr0fow26geq90l3y
Tags: 1.4.12-6ubuntu1
* Resynchronise with Debian. Remaining changes:
- Disable mlock() test since it fails with ulimit 0 (on buildds).
- Set gpg (or gpg2) and gpgsm to use a passphrase agent by default.
- Only suggest gnupg-curl and libldap; recommendations are pulled into
minimal, and we don't need the keyserver utilities in a minimal Ubuntu
system.
- Remove the Win32 build.
- Update config.guess/config.sub for aarch64.
* Dropped patches:
- Fix udeb build failure on powerpc, building with -O2 instead of -Os.
(No longer seems to be necessary.)
* Simplify removal of Win32 build, to make this easier to merge in future.
- Disable mlock() test since it fails with ulimit 0 (on buildds).
- Set gpg (or gpg2) and gpgsm to use a passphrase agent by default.
- Only suggest gnupg-curl and libldap; recommendations are pulled into
minimal, and we don't need the keyserver utilities in a minimal Ubuntu
system.
- Remove the Win32 build.
- Update config.guess/config.sub for aarch64.
* Dropped patches:
- Fix udeb build failure on powerpc, building with -O2 instead of -Os.
(No longer seems to be necessary.)
* Simplify removal of Win32 build, to make this easier to merge in future.
- files added:
- .pc
- .pc/685627_french_translation_update.patch
- .pc/685627_french_translation_update.patch/po
- .pc/autoconfupdate.patch
- .pc/autoconfupdate.patch/scripts
- .pc/disable_mlock_test.patch
- .pc/use_agent_default.patch
- .pc/use_agent_default.patch/g10
- bzlib
- debian/source
- tests
- files removed:
- checks/ChangeLog
- files modified:
- AUTHORS
added
removed
doc/gpg.texi
32
32
.IR dir ]
33
33
.RB [ \-\-options
34
34
.IR file ]
35
.RI [ options ]
35
.RI [ options ]
36
36
.I command
37
37
.RI [ args ]
38
38
@end ifset
57
57
.IR dir ]
58
58
.RB [ \-\-options
59
59
.IR file ]
60
.RI [ options ]
60
.RI [ options ]
61
61
.I command
62
62
.RI [ args ]
63
63
@end ifset
98
98
@mancont
99
99
100
100
@menu
101
* GPG Commands:: List of all commands.
102
* GPG Options:: List of all options.
103
* GPG Configuration:: Configuration files.
104
* GPG Examples:: Some usage examples.
101
* GPG Commands:: List of all commands.
102
* GPG Options:: List of all options.
103
* GPG Configuration:: Configuration files.
104
* GPG Examples:: Some usage examples.
105
105
106
106
Developer information:
107
@c * Unattended Usage:: Using @command{gpg} from other programs.
107
* Unattended Usage of GPG:: Using @command{gpg} from other programs.
108
@end menu
109
108
110
@c * GPG Protocol:: The protocol the server mode uses.
109
@end menu
110
111
111
112
112
113
113
@c *******************************************
303
303
@opindex list-sigs
304
304
Same as @option{--list-keys}, but the signatures are listed too.
305
305
@ifclear gpgone
306
This command has the same effect as
306
This command has the same effect as
307
307
using @option{--list-keys} with @option{--with-sig-list}.
308
308
@end ifclear
309
309
326
326
that for performance reasons the revocation status of a signing key is
327
327
not shown.
328
328
@ifclear gpgone
329
This command has the same effect as
329
This command has the same effect as
330
330
using @option{--list-keys} with @option{--with-sig-check}.
331
331
@end ifclear
332
332
551
551
@item --enarmor
552
552
@item --dearmor
553
553
@opindex enarmor
554
@opindex --enarmor
554
@opindex dearmor
555
555
Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
556
556
This is a GnuPG extension to OpenPGP and in general not very useful.
557
557
598
598
@c ******** Begin Edit-key Options **********
599
599
@table @asis
600
600
601
@item uid @code{n}
602
@opindex keyedit:uid
603
Toggle selection of user ID or photographic user ID with index @code{n}.
604
Use @code{*} to select all and @code{0} to deselect all.
605
606
@item key @code{n}
607
@opindex keyedit:key
608
Toggle selection of subkey with index @code{n}.
609
Use @code{*} to select all and @code{0} to deselect all.
610
611
@item sign
612
@opindex keyedit:sign
613
Make a signature on key of user @code{name} If the key is not yet
614
signed by the default user (or the users given with -u), the program
615
displays the information of the key again, together with its
616
fingerprint and asks whether it should be signed. This question is
617
repeated for all users specified with
618
-u.
619
620
@item lsign
621
@opindex keyedit:lsign
622
Same as "sign" but the signature is marked as non-exportable and will
623
therefore never be used by others. This may be used to make keys
624
valid only in the local environment.
625
626
@item nrsign
627
@opindex keyedit:nrsign
628
Same as "sign" but the signature is marked as non-revocable and can
629
therefore never be revoked.
630
631
@item tsign
632
@opindex keyedit:tsign
633
Make a trust signature. This is a signature that combines the notions
634
of certification (like a regular signature), and trust (like the
635
"trust" command). It is generally only useful in distinct communities
636
or groups.
601
@item uid @code{n}
602
@opindex keyedit:uid
603
Toggle selection of user ID or photographic user ID with index @code{n}.
604
Use @code{*} to select all and @code{0} to deselect all.
605
606
@item key @code{n}
607
@opindex keyedit:key
608
Toggle selection of subkey with index @code{n}.
609
Use @code{*} to select all and @code{0} to deselect all.
610
611
@item sign
612
@opindex keyedit:sign
613
Make a signature on key of user @code{name} If the key is not yet
614
signed by the default user (or the users given with -u), the program
615
displays the information of the key again, together with its
616
fingerprint and asks whether it should be signed. This question is
617
repeated for all users specified with
618
-u.
619
620
@item lsign
621
@opindex keyedit:lsign
622
Same as "sign" but the signature is marked as non-exportable and will
623
therefore never be used by others. This may be used to make keys
624
valid only in the local environment.
625
626
@item nrsign
627
@opindex keyedit:nrsign
628
Same as "sign" but the signature is marked as non-revocable and can
629
therefore never be revoked.
630
631
@item tsign
632
@opindex keyedit:tsign
633
Make a trust signature. This is a signature that combines the notions
634
of certification (like a regular signature), and trust (like the
635
"trust" command). It is generally only useful in distinct communities
636
or groups.
637
637
@end table
638
638
639
639
@c man:.RS
644
644
645
645
@table @asis
646
646
647
@item delsig
648
@opindex keyedit:delsig
649
Delete a signature. Note that it is not possible to retract a signature,
650
once it has been send to the public (i.e. to a keyserver). In that case
651
you better use @code{revsig}.
652
653
@item revsig
654
@opindex keyedit:revsig
655
Revoke a signature. For every signature which has been generated by
656
one of the secret keys, GnuPG asks whether a revocation certificate
657
should be generated.
658
659
@item check
660
@opindex keyedit:check
661
Check the signatures on all selected user IDs.
662
663
@item adduid
664
@opindex keyedit:adduid
665
Create an additional user ID.
666
667
@item addphoto
668
@opindex keyedit:addphoto
669
Create a photographic user ID. This will prompt for a JPEG file that
670
will be embedded into the user ID. Note that a very large JPEG will make
671
for a very large key. Also note that some programs will display your
672
JPEG unchanged (GnuPG), and some programs will scale it to fit in a
673
dialog box (PGP).
674
675
@item showphoto
676
@opindex keyedit:showphoto
677
Display the selected photographic user ID.
678
679
@item deluid
680
@opindex keyedit:deluid
681
Delete a user ID or photographic user ID. Note that it is not
682
possible to retract a user id, once it has been send to the public
683
(i.e. to a keyserver). In that case you better use @code{revuid}.
684
685
@item revuid
686
@opindex keyedit:revuid
687
Revoke a user ID or photographic user ID.
688
689
@item primary
690
@opindex keyedit:primary
691
Flag the current user id as the primary one, removes the primary user
692
id flag from all other user ids and sets the timestamp of all affected
693
self-signatures one second ahead. Note that setting a photo user ID
694
as primary makes it primary over other photo user IDs, and setting a
695
regular user ID as primary makes it primary over other regular user
696
IDs.
697
698
@item keyserver
699
@opindex keyedit:keyserver
700
Set a preferred keyserver for the specified user ID(s). This allows
701
other users to know where you prefer they get your key from. See
702
@option{--keyserver-options honor-keyserver-url} for more on how this
703
works. Setting a value of "none" removes an existing preferred
704
keyserver.
705
706
@item notation
707
@opindex keyedit:notation
708
Set a name=value notation for the specified user ID(s). See
709
@option{--cert-notation} for more on how this works. Setting a value of
710
"none" removes all notations, setting a notation prefixed with a minus
711
sign (-) removes that notation, and setting a notation name (without the
712
=value) prefixed with a minus sign removes all notations with that name.
713
714
@item pref
715
@opindex keyedit:pref
716
List preferences from the selected user ID. This shows the actual
717
preferences, without including any implied preferences.
718
719
@item showpref
720
@opindex keyedit:showpref
721
More verbose preferences listing for the selected user ID. This shows
722
the preferences in effect by including the implied preferences of 3DES
723
(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
724
not already included in the preference list. In addition, the
725
preferred keyserver and signature notations (if any) are shown.
726
727
@item setpref @code{string}
728
@opindex keyedit:setpref
729
Set the list of user ID preferences to @code{string} for all (or just
730
the selected) user IDs. Calling setpref with no arguments sets the
731
preference list to the default (either built-in or set via
732
@option{--default-preference-list}), and calling setpref with "none"
733
as the argument sets an empty preference list. Use @command{@gpgname
734
--version} to get a list of available algorithms. Note that while you
735
can change the preferences on an attribute user ID (aka "photo ID"),
736
GnuPG does not select keys via attribute user IDs so these preferences
737
will not be used by GnuPG.
738
739
When setting preferences, you should list the algorithms in the order
740
which you'd like to see them used by someone else when encrypting a
741
message to your key. If you don't include 3DES, it will be
742
automatically added at the end. Note that there are many factors that
743
go into choosing an algorithm (for example, your key may not be the
744
only recipient), and so the remote OpenPGP application being used to
745
send to you may or may not follow your exact chosen order for a given
746
message. It will, however, only choose an algorithm that is present
747
on the preference list of every recipient key. See also the
748
INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
749
750
@item addkey
751
@opindex keyedit:addkey
752
Add a subkey to this key.
753
754
@item addcardkey
755
@opindex keyedit:addcardkey
756
Generate a subkey on a card and add it to this key.
757
758
@item keytocard
759
@opindex keyedit:keytocard
760
Transfer the selected secret subkey (or the primary key if no subkey
761
has been selected) to a smartcard. The secret key in the keyring will
762
be replaced by a stub if the key could be stored successfully on the
763
card and you use the save command later. Only certain key types may be
764
transferred to the card. A sub menu allows you to select on what card
765
to store the key. Note that it is not possible to get that key back
766
from the card - if the card gets broken your secret key will be lost
767
unless you have a backup somewhere.
768
769
@item bkuptocard @code{file}
770
@opindex keyedit:bkuptocard
771
Restore the given file to a card. This command may be used to restore a
772
backup key (as generated during card initialization) to a new card. In
773
almost all cases this will be the encryption key. You should use this
774
command only with the corresponding public key and make sure that the
775
file given as argument is indeed the backup to restore. You should then
776
select 2 to restore as encryption key. You will first be asked to enter
777
the passphrase of the backup key and then for the Admin PIN of the card.
778
779
@item delkey
780
@opindex keyedit:delkey
781
Remove a subkey (secondart key). Note that it is not possible to retract
782
a subkey, once it has been send to the public (i.e. to a keyserver). In
783
that case you better use @code{revkey}.
784
785
@item revkey
786
@opindex keyedit:revkey
787
Revoke a subkey.
788
789
@item expire
790
@opindex keyedit:expire
791
Change the key or subkey expiration time. If a subkey is selected, the
792
expiration time of this subkey will be changed. With no selection, the
793
key expiration of the primary key is changed.
794
795
@item trust
796
@opindex keyedit:trust
797
Change the owner trust value for the key. This updates the trust-db
798
immediately and no save is required.
799
800
@item disable
801
@itemx enable
802
@opindex keyedit:disable
803
@opindex keyedit:enable
804
Disable or enable an entire key. A disabled key can not normally be
805
used for encryption.
806
807
@item addrevoker
808
@opindex keyedit:addrevoker
809
Add a designated revoker to the key. This takes one optional argument:
810
"sensitive". If a designated revoker is marked as sensitive, it will
811
not be exported by default (see export-options).
812
813
@item passwd
814
@opindex keyedit:passwd
815
Change the passphrase of the secret key.
816
817
@item toggle
818
@opindex keyedit:toggle
819
Toggle between public and secret key listing.
820
821
@item clean
822
@opindex keyedit:clean
823
Compact (by removing all signatures except the selfsig) any user ID
824
that is no longer usable (e.g. revoked, or expired). Then, remove any
825
signatures that are not usable by the trust calculations.
826
Specifically, this removes any signature that does not validate, any
827
signature that is superseded by a later signature, revoked signatures,
828
and signatures issued by keys that are not present on the keyring.
829
830
@item minimize
831
@opindex keyedit:minimize
832
Make the key as small as possible. This removes all signatures from
833
each user ID except for the most recent self-signature.
834
835
@item cross-certify
836
@opindex keyedit:cross-certify
837
Add cross-certification signatures to signing subkeys that may not
838
currently have them. Cross-certification signatures protect against a
839
subtle attack against signing subkeys. See
840
@option{--require-cross-certification}. All new keys generated have
841
this signature by default, so this option is only useful to bring
842
older keys up to date.
843
844
@item save
845
@opindex keyedit:save
846
Save all changes to the key rings and quit.
847
848
@item quit
849
@opindex keyedit:quit
850
Quit the program without updating the
851
key rings.
852
647
@item delsig
648
@opindex keyedit:delsig
649
Delete a signature. Note that it is not possible to retract a signature,
650
once it has been send to the public (i.e. to a keyserver). In that case
651
you better use @code{revsig}.
652
653
@item revsig
654
@opindex keyedit:revsig
655
Revoke a signature. For every signature which has been generated by
656
one of the secret keys, GnuPG asks whether a revocation certificate
657
should be generated.
658
659
@item check
660
@opindex keyedit:check
661
Check the signatures on all selected user IDs.
662
663
@item adduid
664
@opindex keyedit:adduid
665
Create an additional user ID.
666
667
@item addphoto
668
@opindex keyedit:addphoto
669
Create a photographic user ID. This will prompt for a JPEG file that
670
will be embedded into the user ID. Note that a very large JPEG will make
671
for a very large key. Also note that some programs will display your
672
JPEG unchanged (GnuPG), and some programs will scale it to fit in a
673
dialog box (PGP).
674
675
@item showphoto
676
@opindex keyedit:showphoto
677
Display the selected photographic user ID.
678
679
@item deluid
680
@opindex keyedit:deluid
681
Delete a user ID or photographic user ID. Note that it is not
682
possible to retract a user id, once it has been send to the public
683
(i.e. to a keyserver). In that case you better use @code{revuid}.
684
685
@item revuid
686
@opindex keyedit:revuid
687
Revoke a user ID or photographic user ID.
688
689
@item primary
690
@opindex keyedit:primary
691
Flag the current user id as the primary one, removes the primary user
692
id flag from all other user ids and sets the timestamp of all affected
693
self-signatures one second ahead. Note that setting a photo user ID
694
as primary makes it primary over other photo user IDs, and setting a
695
regular user ID as primary makes it primary over other regular user
696
IDs.
697
698
@item keyserver
699
@opindex keyedit:keyserver
700
Set a preferred keyserver for the specified user ID(s). This allows
701
other users to know where you prefer they get your key from. See
702
@option{--keyserver-options honor-keyserver-url} for more on how this
703
works. Setting a value of "none" removes an existing preferred
704
keyserver.
705
706
@item notation
707
@opindex keyedit:notation
708
Set a name=value notation for the specified user ID(s). See
709
@option{--cert-notation} for more on how this works. Setting a value of
710
"none" removes all notations, setting a notation prefixed with a minus
711
sign (-) removes that notation, and setting a notation name (without the
712
=value) prefixed with a minus sign removes all notations with that name.
713
714
@item pref
715
@opindex keyedit:pref
716
List preferences from the selected user ID. This shows the actual
717
preferences, without including any implied preferences.
718
719
@item showpref
720
@opindex keyedit:showpref
721
More verbose preferences listing for the selected user ID. This shows
722
the preferences in effect by including the implied preferences of 3DES
723
(cipher), SHA-1 (digest), and Uncompressed (compression) if they are
724
not already included in the preference list. In addition, the
725
preferred keyserver and signature notations (if any) are shown.
726
727
@item setpref @code{string}
728
@opindex keyedit:setpref
729
Set the list of user ID preferences to @code{string} for all (or just
730
the selected) user IDs. Calling setpref with no arguments sets the
731
preference list to the default (either built-in or set via
732
@option{--default-preference-list}), and calling setpref with "none"
733
as the argument sets an empty preference list. Use @command{@gpgname
734
--version} to get a list of available algorithms. Note that while you
735
can change the preferences on an attribute user ID (aka "photo ID"),
736
GnuPG does not select keys via attribute user IDs so these preferences
737
will not be used by GnuPG.
738
739
When setting preferences, you should list the algorithms in the order
740
which you'd like to see them used by someone else when encrypting a
741
message to your key. If you don't include 3DES, it will be
742
automatically added at the end. Note that there are many factors that
743
go into choosing an algorithm (for example, your key may not be the
744
only recipient), and so the remote OpenPGP application being used to
745
send to you may or may not follow your exact chosen order for a given
746
message. It will, however, only choose an algorithm that is present
747
on the preference list of every recipient key. See also the
748
INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
749
750
@item addkey
751
@opindex keyedit:addkey
752
Add a subkey to this key.
753
754
@item addcardkey
755
@opindex keyedit:addcardkey
756
Generate a subkey on a card and add it to this key.
757
758
@item keytocard
759
@opindex keyedit:keytocard
760
Transfer the selected secret subkey (or the primary key if no subkey
761
has been selected) to a smartcard. The secret key in the keyring will
762
be replaced by a stub if the key could be stored successfully on the
763
card and you use the save command later. Only certain key types may be
764
transferred to the card. A sub menu allows you to select on what card
765
to store the key. Note that it is not possible to get that key back
766
from the card - if the card gets broken your secret key will be lost
767
unless you have a backup somewhere.
768
769
@item bkuptocard @code{file}
770
@opindex keyedit:bkuptocard
771
Restore the given file to a card. This command may be used to restore a
772
backup key (as generated during card initialization) to a new card. In
773
almost all cases this will be the encryption key. You should use this
774
command only with the corresponding public key and make sure that the
775
file given as argument is indeed the backup to restore. You should then
776
select 2 to restore as encryption key. You will first be asked to enter
777
the passphrase of the backup key and then for the Admin PIN of the card.
778
779
@item delkey
780
@opindex keyedit:delkey
781
Remove a subkey (secondart key). Note that it is not possible to retract
782
a subkey, once it has been send to the public (i.e. to a keyserver). In
783
that case you better use @code{revkey}.
784
785
@item revkey
786
@opindex keyedit:revkey
787
Revoke a subkey.
788
789
@item expire
790
@opindex keyedit:expire
791
Change the key or subkey expiration time. If a subkey is selected, the
792
expiration time of this subkey will be changed. With no selection, the
793
key expiration of the primary key is changed.
794
795
@item trust
796
@opindex keyedit:trust
797
Change the owner trust value for the key. This updates the trust-db
798
immediately and no save is required.
799
800
@item disable
801
@itemx enable
802
@opindex keyedit:disable
803
@opindex keyedit:enable
804
Disable or enable an entire key. A disabled key can not normally be
805
used for encryption.
806
807
@item addrevoker
808
@opindex keyedit:addrevoker
809
Add a designated revoker to the key. This takes one optional argument:
810
"sensitive". If a designated revoker is marked as sensitive, it will
811
not be exported by default (see export-options).
812
813
@item passwd
814
@opindex keyedit:passwd
815
Change the passphrase of the secret key.
816
817
@item toggle
818
@opindex keyedit:toggle
819
Toggle between public and secret key listing.
820
821
@item clean
822
@opindex keyedit:clean
823
Compact (by removing all signatures except the selfsig) any user ID
824
that is no longer usable (e.g. revoked, or expired). Then, remove any
825
signatures that are not usable by the trust calculations.
826
Specifically, this removes any signature that does not validate, any
827
signature that is superseded by a later signature, revoked signatures,
828
and signatures issued by keys that are not present on the keyring.
829
830
@item minimize
831
@opindex keyedit:minimize
832
Make the key as small as possible. This removes all signatures from
833
each user ID except for the most recent self-signature.
834
835
@item cross-certify
836
@opindex keyedit:cross-certify
837
Add cross-certification signatures to signing subkeys that may not
838
currently have them. Cross-certification signatures protect against a
839
subtle attack against signing subkeys. See
840
@option{--require-cross-certification}. All new keys generated have
841
this signature by default, so this option is only useful to bring
842
older keys up to date.
843
844
@item save
845
@opindex keyedit:save
846
Save all changes to the key rings and quit.
847
848
@item quit
849
@opindex keyedit:quit
850
Quit the program without updating the
851
key rings.
853
852
@end table
854
853
855
854
@c man:.RS
863
862
864
863
@table @asis
865
864
866
@item -
867
No ownertrust assigned / not yet calculated.
868
869
@item e
870
Trust
871
calculation has failed; probably due to an expired key.
872
873
@item q
874
Not enough information for calculation.
875
876
@item n
877
Never trust this key.
878
879
@item m
880
Marginally trusted.
881
882
@item f
883
Fully trusted.
884
885
@item u
886
Ultimately trusted.
865
@item -
866
No ownertrust assigned / not yet calculated.
867
868
@item e
869
Trust
870
calculation has failed; probably due to an expired key.
871
872
@item q
873
Not enough information for calculation.
874
875
@item n
876
Never trust this key.
877
878
@item m
879
Marginally trusted.
880
881
@item f
882
Fully trusted.
883
884
@item u
885
Ultimately trusted.
886
887
887
@end table
888
888
@c ******** End Edit-key Options **********
889
889
1026
1026
1027
1027
@table @asis
1028
1028
1029
@item show-photos
1030
@opindex list-options:show-photos
1031
Causes @option{--list-keys}, @option{--list-sigs},
1032
@option{--list-public-keys}, and @option{--list-secret-keys} to display
1033
any photo IDs attached to the key. Defaults to no. See also
1034
@option{--photo-viewer}.
1035
1036
@item show-policy-urls
1037
@opindex list-options:show-policy-urls
1038
Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
1039
listings. Defaults to no.
1040
1041
@item show-notations
1042
@itemx show-std-notations
1043
@itemx show-user-notations
1044
@opindex list-options:show-notations
1045
@opindex list-options:show-std-notations
1046
@opindex list-options:show-user-notations
1047
Show all, IETF standard, or user-defined signature notations in the
1048
@option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
1049
1050
@item show-keyserver-urls
1051
1052
Show any preferred keyserver URL in the @option{--list-sigs} or
1053
@option{--check-sigs} listings. Defaults to no.
1054
1055
@item show-uid-validity
1056
Display the calculated validity of user IDs during key listings.
1057
Defaults to no.
1058
1059
@item show-unusable-uids
1060
Show revoked and expired user IDs in key listings. Defaults to no.
1061
1062
@item show-unusable-subkeys
1063
Show revoked and expired subkeys in key listings. Defaults to no.
1064
1065
@item show-keyring
1066
Display the keyring name at the head of key listings to show which
1067
keyring a given key resides on. Defaults to no.
1068
1069
@item show-sig-expire
1070
Show signature expiration dates (if any) during @option{--list-sigs} or
1071
@option{--check-sigs} listings. Defaults to no.
1072
1073
@item show-sig-subpackets
1074
Include signature subpackets in the key listing. This option can take an
1075
optional argument list of the subpackets to list. If no argument is
1076
passed, list all subpackets. Defaults to no. This option is only
1077
meaningful when using @option{--with-colons} along with
1078
@option{--list-sigs} or @option{--check-sigs}.
1029
@item show-photos
1030
@opindex list-options:show-photos
1031
Causes @option{--list-keys}, @option{--list-sigs},
1032
@option{--list-public-keys}, and @option{--list-secret-keys} to
1033
display any photo IDs attached to the key. Defaults to no. See also
1034
@option{--photo-viewer}. Does not work with @option{--with-colons}:
1035
see @option{--attribute-fd} for the appropriate way to get photo data
1036
for scripts and other frontends.
1037
1038
@item show-policy-urls
1039
@opindex list-options:show-policy-urls
1040
Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
1041
listings. Defaults to no.
1042
1043
@item show-notations
1044
@itemx show-std-notations
1045
@itemx show-user-notations
1046
@opindex list-options:show-notations
1047
@opindex list-options:show-std-notations
1048
@opindex list-options:show-user-notations
1049
Show all, IETF standard, or user-defined signature notations in the
1050
@option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
1051
1052
@item show-keyserver-urls
1053
@opindex list-options:show-keyserver-urls
1054
Show any preferred keyserver URL in the @option{--list-sigs} or
1055
@option{--check-sigs} listings. Defaults to no.
1056
1057
@item show-uid-validity
1058
@opindex list-options:show-uid-validity
1059
Display the calculated validity of user IDs during key listings.
1060
Defaults to no.
1061
1062
@item show-unusable-uids
1063
@opindex list-options:show-unusable-uids
1064
Show revoked and expired user IDs in key listings. Defaults to no.
1065
1066
@item show-unusable-subkeys
1067
@opindex list-options:show-unusable-subkeys
1068
Show revoked and expired subkeys in key listings. Defaults to no.
1069
1070
@item show-keyring
1071
@opindex list-options:show-keyring
1072
Display the keyring name at the head of key listings to show which
1073
keyring a given key resides on. Defaults to no.
1074
1075
@item show-sig-expire
1076
@opindex list-options:show-sig-expire
1077
Show signature expiration dates (if any) during @option{--list-sigs} or
1078
@option{--check-sigs} listings. Defaults to no.
1079
1080
@item show-sig-subpackets
1081
@opindex list-options:show-sig-subpackets
1082
Include signature subpackets in the key listing. This option can take an
1083
optional argument list of the subpackets to list. If no argument is
1084
passed, list all subpackets. Defaults to no. This option is only
1085
meaningful when using @option{--with-colons} along with
1086
@option{--list-sigs} or @option{--check-sigs}.
1087
1079
1088
@end table
1080
1089
1081
1090
@item --verify-options @code{parameters}
1091
@opindex verify-options
1082
1092
This is a space or comma delimited string that gives options used when
1083
1093
verifying signatures. Options can be prepended with a `no-' to give
1084
1094
the opposite meaning. The options are:
1085
1095
1086
1096
@table @asis
1087
1097
1088
@item show-photos
1089
Display any photo IDs present on the key that issued the signature.
1090
Defaults to no. See also @option{--photo-viewer}.
1091
1092
@item show-policy-urls
1093
Show policy URLs in the signature being verified. Defaults to no.
1094
1095
@item show-notations
1096
@itemx show-std-notations
1097
@itemx show-user-notations
1098
Show all, IETF standard, or user-defined signature notations in the
1099
signature being verified. Defaults to IETF standard.
1100
1101
@item show-keyserver-urls
1102
Show any preferred keyserver URL in the signature being verified.
1103
Defaults to no.
1104
1105
@item show-uid-validity
1106
Display the calculated validity of the user IDs on the key that issued
1107
the signature. Defaults to no.
1108
1109
@item show-unusable-uids
1110
Show revoked and expired user IDs during signature verification.
1111
Defaults to no.
1112
1113
@item show-primary-uid-only
1114
Show only the primary user ID during signature verification. That is
1115
all the AKA lines as well as photo Ids are not shown with the signature
1116
verification status.
1117
1118
@item pka-lookups
1119
Enable PKA lookups to verify sender addresses. Note that PKA is based
1120
on DNS, and so enabling this option may disclose information on when
1121
and what signatures are verified or to whom data is encrypted. This
1122
is similar to the "web bug" described for the auto-key-retrieve
1123
feature.
1124
1125
@item pka-trust-increase
1126
Raise the trust in a signature to full if the signature passes PKA
1127
validation. This option is only meaningful if pka-lookups is set.
1098
@item show-photos
1099
@opindex verify-options:show-photos
1100
Display any photo IDs present on the key that issued the signature.
1101
Defaults to no. See also @option{--photo-viewer}.
1102
1103
@item show-policy-urls
1104
@opindex verify-options:show-policy-urls
1105
Show policy URLs in the signature being verified. Defaults to no.
1106
1107
@item show-notations
1108
@itemx show-std-notations
1109
@itemx show-user-notations
1110
@opindex verify-options:show-notations
1111
@opindex verify-options:show-std-notations
1112
@opindex verify-options:show-user-notations
1113
Show all, IETF standard, or user-defined signature notations in the
1114
signature being verified. Defaults to IETF standard.
1115
1116
@item show-keyserver-urls
1117
@opindex verify-options:show-keyserver-urls
1118
Show any preferred keyserver URL in the signature being verified.
1119
Defaults to no.
1120
1121
@item show-uid-validity
1122
@opindex verify-options:show-uid-validity
1123
Display the calculated validity of the user IDs on the key that issued
1124
the signature. Defaults to no.
1125
1126
@item show-unusable-uids
1127
@opindex verify-options:show-unusable-uids
1128
Show revoked and expired user IDs during signature verification.
1129
Defaults to no.
1130
1131
@item show-primary-uid-only
1132
@opindex verify-options:show-primary-uid-only
1133
Show only the primary user ID during signature verification. That is
1134
all the AKA lines as well as photo Ids are not shown with the signature
1135
verification status.
1136
1137
@item pka-lookups
1138
@opindex verify-options:pka-lookups
1139
Enable PKA lookups to verify sender addresses. Note that PKA is based
1140
on DNS, and so enabling this option may disclose information on when
1141
and what signatures are verified or to whom data is encrypted. This
1142
is similar to the "web bug" described for the auto-key-retrieve
1143
feature.
1144
1145
@item pka-trust-increase
1146
@opindex verify-options:pka-trust-increase
1147
Raise the trust in a signature to full if the signature passes PKA
1148
validation. This option is only meaningful if pka-lookups is set.
1128
1149
@end table
1129
1150
1130
1151
@item --enable-dsa2
1131
1152
@itemx --disable-dsa2
1153
@opindex enable-dsa2
1154
@opindex disable-dsa2
1132
1155
Enable hash truncation for all DSA keys even for old DSA Keys up to
1133
1156
1024 bit. This is also the default with @option{--openpgp}. Note
1134
1157
that older versions of GnuPG also required this flag to allow the
1135
1158
generation of DSA larger than 1024 bit.
1136
1159
1137
1160
@item --photo-viewer @code{string}
1161
@opindex photo-viewer
1138
1162
This is the command line that should be run to view a photo ID. "%i"
1139
1163
will be expanded to a filename containing the photo. "%I" does the
1140
1164
same, except the file will not be deleted once the viewer exits.
1152
1176
executing it from GnuPG does not make it secure.
1153
1177
1154
1178
@item --exec-path @code{string}
1179
@opindex exec-path
1155
1180
Sets a list of directories to search for photo viewers and keyserver
1156
1181
helpers. If not provided, keyserver helpers use the compiled-in
1157
1182
default directory, and photo viewers use the $PATH environment
1160
1185
keyserver helpers.
1161
1186
1162
1187
@item --keyring @code{file}
1188
@opindex keyring
1163
1189
Add @code{file} to the current list of keyrings. If @code{file} begins
1164
1190
with a tilde and a slash, these are replaced by the $HOME directory. If
1165
1191
the filename does not contain a slash, it is assumed to be in the GnuPG
1171
1197
@option{--no-default-keyring}.
1172
1198
1173
1199
@item --secret-keyring @code{file}
1200
@opindex secret-keyring
1174
1201
Same as @option{--keyring} but for the secret keyrings.
1175
1202
1176
1203
@item --primary-keyring @code{file}
1204
@opindex primary-keyring
1177
1205
Designate @code{file} as the primary public keyring. This means that
1178
1206
newly imported keys (via @option{--import} or keyserver
1179
1207
@option{--recv-from}) will go to this keyring.
1180
1208
1181
1209
@item --trustdb-name @code{file}
1210
@opindex trustdb-name
1182
1211
Use @code{file} instead of the default trustdb. If @code{file} begins
1183
1212
with a tilde and a slash, these are replaced by the $HOME directory. If
1184
1213
the filename does not contain a slash, it is assumed to be in the GnuPG
1193
1222
1194
1223
@ifset gpgone
1195
1224
@item --pcsc-driver @code{file}
1225
@opindex pcsc-driver
1196
1226
Use @code{file} to access the smartcard reader. The current default is
1197
1227
`libpcsclite.so.1' for GLIBC based systems,
1198
1228
`/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X,
1201
1231
1202
1232
@ifset gpgone
1203
1233
@item --disable-ccid
1234
@opindex disable-ccid
1204
1235
Disable the integrated support for CCID compliant readers. This
1205
1236
allows to fall back to one of the other drivers even if the internal
1206
1237
CCID driver can handle the reader. Note, that CCID support is only
1209
1240
1210
1241
@ifset gpgone
1211
1242
@item --reader-port @code{number_or_string}
1243
@opindex reader-port
1212
1244
This option may be used to specify the port of the card terminal. A
1213
1245
value of 0 refers to the first serial device; add 32768 to access USB
1214
1246
devices. The default is 32768 (first USB device). PC/SC or CCID
1218
1250
@end ifset
1219
1251
1220
1252
@item --display-charset @code{name}
1253
@opindex display-charset
1221
1254
Set the name of the native character set. This is used to convert
1222
1255
some informational strings like user IDs to the proper UTF-8 encoding.
1223
1256
Note that this has nothing to do with the character set of data to be
1228
1261
1229
1262
@table @asis
1230
1263
1231
@item iso-8859-1
1232
This is the Latin 1 set.
1233
1234
@item iso-8859-2
1235
The Latin 2 set.
1236
1237
@item iso-8859-15
1238
This is currently an alias for
1239
the Latin 1 set.
1240
1241
@item koi8-r
1242
The usual Russian set (rfc1489).
1243
1244
@item utf-8
1245
Bypass all translations and assume
1246
that the OS uses native UTF-8 encoding.
1264
@item iso-8859-1
1265
@opindex display-charset:iso-8859-1
1266
This is the Latin 1 set.
1267
1268
@item iso-8859-2
1269
@opindex display-charset:iso-8859-2
1270
The Latin 2 set.
1271
1272
@item iso-8859-15
1273
@opindex display-charset:iso-8859-15
1274
This is currently an alias for
1275
the Latin 1 set.
1276
1277
@item koi8-r
1278
@opindex display-charset:koi8-r
1279
The usual Russian set (rfc1489).
1280
1281
@item utf-8
1282
@opindex display-charset:utf-8
1283
Bypass all translations and assume
1284
that the OS uses native UTF-8 encoding.
1247
1285
@end table
1248
1286
1249
1287
@item --utf8-strings
1250
1288
@itemx --no-utf8-strings
1289
@opindex utf8-strings
1251
1290
Assume that command line arguments are given as UTF8 strings. The
1252
1291
default (@option{--no-utf8-strings}) is to assume that arguments are
1253
1292
encoded in the character set as specified by
1258
1297
@anchor{option --options}
1259
1298
@end ifset
1260
1299
@item --options @code{file}
1300
@opindex options
1261
1301
Read options from @code{file} and do not try to read them from the
1262
1302
default options file in the homedir (see @option{--homedir}). This
1263
1303
option is ignored if used in an options file.
1264
1304
1265
1305
@item --no-options
1306
@opindex no-options
1266
1307
Shortcut for @option{--options /dev/null}. This option is detected
1267
1308
before an attempt to open an option file. Using this option will also
1268
1309
prevent the creation of a @file{~/.gnupg} homedir.
1269
1310
1270
1271
1272
1311
@item -z @code{n}
1273
1312
@itemx --compress-level @code{n}
1274
1313
@itemx --bzip2-compress-level @code{n}
1314
@opindex compress-level
1315
@opindex bzip2-compress-level
1275
1316
Set compression level to @code{n} for the ZIP and ZLIB compression
1276
1317
algorithms. The default is to use the default compression level of zlib
1277
1318
(normally 6). @option{--bzip2-compress-level} sets the compression level
1281
1322
@option{-z} sets both. A value of 0 for @code{n} disables compression.
1282
1323
1283
1324
@item --bzip2-decompress-lowmem
1325
@opindex bzip2-decompress-lowmem
1284
1326
Use a different decompression method for BZIP2 compressed files. This
1285
1327
alternate method uses a bit more than half the memory, but also runs
1286
1328
at half the speed. This is useful under extreme low memory
1300
1342
1301
1343
@item --ask-cert-level
1302
1344
@itemx --no-ask-cert-level
1345
@opindex ask-cert-level
1303
1346
When making a key signature, prompt for a certification level. If this
1304
1347
option is not specified, the certification level used is set via
1305
1348
@option{--default-cert-level}. See @option{--default-cert-level} for
1308
1351
defaults to no.
1309
1352
1310
1353
@item --default-cert-level @code{n}
1354
@opindex default-cert-level
1311
1355
The default to use for the check level when signing a key.
1312
1356
1313
1357
0 means you make no particular claim as to how carefully you verified
1337
1381
This option defaults to 0 (no particular claim).
1338
1382
1339
1383
@item --min-cert-level
1384
@opindex min-cert-level
1340
1385
When building the trust database, treat any signatures with a
1341
1386
certification level below this as invalid. Defaults to 2, which
1342
1387
disregards level 1 signatures. Note that level 0 "no particular
1343
1388
claim" signatures are always accepted.
1344
1389
1345
1390
@item --trusted-key @code{long key ID}
1391
@opindex trusted-key
1346
1392
Assume that the specified key (which must be given
1347
1393
as a full 8 byte key ID) is as trustworthy as one of
1348
1394
your own secret keys. This option is useful if you
1351
1397
recipient's or signator's key.
1352
1398
1353
1399
@item --trust-model @code{pgp|classic|direct|always|auto}
1400
@opindex trust-model
1354
1401
Set what trust model GnuPG should follow. The models are:
1355
1402
1356
1403
@table @asis
1357
1404
1358
@item pgp
1359
This is the Web of Trust combined with trust signatures as used in PGP
1360
5.x and later. This is the default trust model when creating a new
1361
trust database.
1362
1363
@item classic
1364
This is the standard Web of Trust as used in PGP 2.x and earlier.
1365
1366
@item direct
1367
Key validity is set directly by the user and not calculated via the
1368
Web of Trust.
1369
1370
@item always
1371
Skip key validation and assume that used keys are always fully
1372
trusted. You generally won't use this unless you are using some
1373
external validation scheme. This option also suppresses the
1374
"[uncertain]" tag printed with signature checks when there is no
1375
evidence that the user ID is bound to the key.
1376
1377
@item auto
1378
Select the trust model depending on whatever the internal trust
1379
database says. This is the default model if such a database already
1380
exists.
1405
@item pgp
1406
@opindex trust-mode:pgp
1407
This is the Web of Trust combined with trust signatures as used in PGP
1408
5.x and later. This is the default trust model when creating a new
1409
trust database.
1410
1411
@item classic
1412
@opindex trust-mode:classic
1413
This is the standard Web of Trust as used in PGP 2.x and earlier.
1414
1415
@item direct
1416
@opindex trust-mode:direct
1417
Key validity is set directly by the user and not calculated via the
1418
Web of Trust.
1419
1420
@item always
1421
@opindex trust-mode:always
1422
Skip key validation and assume that used keys are always fully
1423
trusted. You generally won't use this unless you are using some
1424
external validation scheme. This option also suppresses the
1425
"[uncertain]" tag printed with signature checks when there is no
1426
evidence that the user ID is bound to the key.
1427
1428
@item auto
1429
@opindex trust-mode:auto
1430
Select the trust model depending on whatever the internal trust
1431
database says. This is the default model if such a database already
1432
exists.
1381
1433
@end table
1382
1434
1383
1435
@item --auto-key-locate @code{parameters}
1384
1436
@itemx --no-auto-key-locate
1437
@opindex auto-key-locate
1385
1438
GnuPG can automatically locate and retrieve keys as needed using this
1386
1439
option. This happens when encrypting to an email address (in the
1387
1440
"user@@example.com" form), and there are no user@@example.com keys on
1390
1443
1391
1444
@table @asis
1392
1445
1393
@item cert
1394
Locate a key using DNS CERT, as specified in rfc4398.
1395
1396
@item pka
1397
Locate a key using DNS PKA.
1398
1399
@item ldap
1400
Using DNS Service Discovery, check the domain in question for any LDAP
1401
keyservers to use. If this fails, attempt to locate the key using the
1402
PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
1403
1404
@item keyserver
1405
Locate a key using whatever keyserver is defined using the
1406
@option{--keyserver} option.
1407
1408
@item keyserver-URL
1409
In addition, a keyserver URL as used in the @option{--keyserver} option
1410
may be used here to query that particular keyserver.
1411
1412
@item local
1413
Locate the key using the local keyrings. This mechanism allows to
1414
select the order a local key lookup is done. Thus using
1415
@samp{--auto-key-locate local} is identical to
1416
@option{--no-auto-key-locate}.
1417
1418
@item nodefault
1419
This flag disables the standard local key lookup, done before any of the
1420
mechanisms defined by the @option{--auto-key-locate} are tried. The
1421
position of this mechanism in the list does not matter. It is not
1422
required if @code{local} is also used.
1446
@item cert
1447
Locate a key using DNS CERT, as specified in rfc4398.
1448
1449
@item pka
1450
Locate a key using DNS PKA.
1451
1452
@item ldap
1453
Using DNS Service Discovery, check the domain in question for any LDAP
1454
keyservers to use. If this fails, attempt to locate the key using the
1455
PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
1456
1457
@item keyserver
1458
Locate a key using whatever keyserver is defined using the
1459
@option{--keyserver} option.
1460
1461
@item keyserver-URL
1462
In addition, a keyserver URL as used in the @option{--keyserver} option
1463
may be used here to query that particular keyserver.
1464
1465
@item local
1466
Locate the key using the local keyrings. This mechanism allows to
1467
select the order a local key lookup is done. Thus using
1468
@samp{--auto-key-locate local} is identical to
1469
@option{--no-auto-key-locate}.
1470
1471
@item nodefault
1472
This flag disables the standard local key lookup, done before any of the
1473
mechanisms defined by the @option{--auto-key-locate} are tried. The
1474
position of this mechanism in the list does not matter. It is not
1475
required if @code{local} is also used.
1423
1476
1424
1477
@end table
1425
1478
1426
1479
@item --keyid-format @code{short|0xshort|long|0xlong}
1480
@opindex keyid-format
1427
1481
Select how to display key IDs. "short" is the traditional 8-character
1428
1482
key ID. "long" is the more accurate (but less convenient)
1429
1483
16-character key ID. Add an "0x" to either to include an "0x" at the
1430
beginning of the key ID, as in 0x99242560.
1484
beginning of the key ID, as in 0x99242560. Note that this option is
1485
ignored if the option --with-colons is used.
1431
1486
1432
1487
@item --keyserver @code{name}
1488
@opindex keyserver
1433
1489
Use @code{name} as your keyserver. This is the server that
1434
1490
@option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
1435
1491
will communicate with to receive keys from, send keys to, and search for
1449
1505
keyserver each time you use it.
1450
1506
1451
1507
@item --keyserver-options @code{name=value1 }
1508
@opindex keyserver-options
1452
1509
This is a space or comma delimited string that gives options for the
1453
1510
keyserver. Options can be prefixed with a `no-' to give the opposite
1454
1511
meaning. Valid import-options or export-options may be used here as
1458
1515
1459
1516
@table @asis
1460
1517
1461
@item include-revoked
1462
When searching for a key with @option{--search-keys}, include keys that
1463
are marked on the keyserver as revoked. Note that not all keyservers
1464
differentiate between revoked and unrevoked keys, and for such
1465
keyservers this option is meaningless. Note also that most keyservers do
1466
not have cryptographic verification of key revocations, and so turning
1467
this option off may result in skipping keys that are incorrectly marked
1468
as revoked.
1469
1470
@item include-disabled
1471
When searching for a key with @option{--search-keys}, include keys that
1472
are marked on the keyserver as disabled. Note that this option is not
1473
used with HKP keyservers.
1474
1475
@item auto-key-retrieve
1476
This option enables the automatic retrieving of keys from a keyserver
1477
when verifying signatures made by keys that are not on the local
1478
keyring.
1479
1480
Note that this option makes a "web bug" like behavior possible.
1481
Keyserver operators can see which keys you request, so by sending you
1482
a message signed by a brand new key (which you naturally will not have
1483
on your local keyring), the operator can tell both your IP address and
1484
the time when you verified the signature.
1485
1486
@item honor-keyserver-url
1487
When using @option{--refresh-keys}, if the key in question has a preferred
1488
keyserver URL, then use that preferred keyserver to refresh the key
1489
from. In addition, if auto-key-retrieve is set, and the signature
1490
being verified has a preferred keyserver URL, then use that preferred
1491
keyserver to fetch the key from. Defaults to yes.
1492
1493
@item honor-pka-record
1494
If auto-key-retrieve is set, and the signature being verified has a
1495
PKA record, then use the PKA information to fetch the key. Defaults
1496
to yes.
1497
1498
@item include-subkeys
1499
When receiving a key, include subkeys as potential targets. Note that
1500
this option is not used with HKP keyservers, as they do not support
1501
retrieving keys by subkey id.
1502
1503
@item use-temp-files
1504
On most Unix-like platforms, GnuPG communicates with the keyserver
1505
helper program via pipes, which is the most efficient method. This
1506
option forces GnuPG to use temporary files to communicate. On some
1507
platforms (such as Win32 and RISC OS), this option is always enabled.
1508
1509
@item keep-temp-files
1510
If using `use-temp-files', do not delete the temp files after using
1511
them. This option is useful to learn the keyserver communication
1512
protocol by reading the temporary files.
1513
1514
@item verbose
1515
Tell the keyserver helper program to be more verbose. This option can
1516
be repeated multiple times to increase the verbosity level.
1517
1518
@item timeout
1519
Tell the keyserver helper program how long (in seconds) to try and
1520
perform a keyserver action before giving up. Note that performing
1521
multiple actions at the same time uses this timeout value per action.
1522
For example, when retrieving multiple keys via @option{--recv-keys}, the
1523
timeout applies separately to each key retrieval, and not to the
1524
@option{--recv-keys} command as a whole. Defaults to 30 seconds.
1525
1526
@item http-proxy=@code{value}
1527
Set the proxy to use for HTTP and HKP keyservers. This overrides the
1528
"http_proxy" environment variable, if any.
1529
1530
@item max-cert-size
1531
When retrieving a key via DNS CERT, only accept keys up to this size.
1532
Defaults to 16384 bytes.
1533
1534
@item debug
1535
Turn on debug output in the keyserver helper program. Note that the
1536
details of debug output depends on which keyserver helper program is
1537
being used, and in turn, on any libraries that the keyserver helper
1538
program uses internally (libcurl, openldap, etc).
1539
1540
@item check-cert
1541
Enable certificate checking if the keyserver presents one (for hkps or
1542
ldaps). Defaults to on.
1543
1544
@item ca-cert-file
1545
Provide a certificate store to override the system default. Only
1546
necessary if check-cert is enabled, and the keyserver is using a
1547
certificate that is not present in a system default certificate list.
1548
1549
Note that depending on the SSL library that the keyserver helper is
1550
built with, this may actually be a directory or a file.
1518
@item include-revoked
1519
When searching for a key with @option{--search-keys}, include keys that
1520
are marked on the keyserver as revoked. Note that not all keyservers
1521
differentiate between revoked and unrevoked keys, and for such
1522
keyservers this option is meaningless. Note also that most keyservers do
1523
not have cryptographic verification of key revocations, and so turning
1524
this option off may result in skipping keys that are incorrectly marked
1525
as revoked.
1526
1527
@item include-disabled
1528
When searching for a key with @option{--search-keys}, include keys that
1529
are marked on the keyserver as disabled. Note that this option is not
1530
used with HKP keyservers.
1531
1532
@item auto-key-retrieve
1533
This option enables the automatic retrieving of keys from a keyserver
1534
when verifying signatures made by keys that are not on the local
1535
keyring.
1536
1537
Note that this option makes a "web bug" like behavior possible.
1538
Keyserver operators can see which keys you request, so by sending you
1539
a message signed by a brand new key (which you naturally will not have
1540
on your local keyring), the operator can tell both your IP address and
1541
the time when you verified the signature.
1542
1543
@item honor-keyserver-url
1544
When using @option{--refresh-keys}, if the key in question has a preferred
1545
keyserver URL, then use that preferred keyserver to refresh the key
1546
from. In addition, if auto-key-retrieve is set, and the signature
1547
being verified has a preferred keyserver URL, then use that preferred
1548
keyserver to fetch the key from. Defaults to yes.
1549
1550
@item honor-pka-record
1551
If auto-key-retrieve is set, and the signature being verified has a
1552
PKA record, then use the PKA information to fetch the key. Defaults
1553
to yes.
1554
1555
@item include-subkeys
1556
When receiving a key, include subkeys as potential targets. Note that
1557
this option is not used with HKP keyservers, as they do not support
1558
retrieving keys by subkey id.
1559
1560
@item use-temp-files
1561
On most Unix-like platforms, GnuPG communicates with the keyserver
1562
helper program via pipes, which is the most efficient method. This
1563
option forces GnuPG to use temporary files to communicate. On some
1564
platforms (such as Win32 and RISC OS), this option is always enabled.
1565
1566
@item keep-temp-files
1567
If using `use-temp-files', do not delete the temp files after using
1568
them. This option is useful to learn the keyserver communication
1569
protocol by reading the temporary files.
1570
1571
@item verbose
1572
Tell the keyserver helper program to be more verbose. This option can
1573
be repeated multiple times to increase the verbosity level.
1574
1575
@item timeout
1576
Tell the keyserver helper program how long (in seconds) to try and
1577
perform a keyserver action before giving up. Note that performing
1578
multiple actions at the same time uses this timeout value per action.
1579
For example, when retrieving multiple keys via @option{--recv-keys}, the
1580
timeout applies separately to each key retrieval, and not to the
1581
@option{--recv-keys} command as a whole. Defaults to 30 seconds.
1582
1583
@item http-proxy=@code{value}
1584
Set the proxy to use for HTTP and HKP keyservers. This overrides the
1585
"http_proxy" environment variable, if any.
1586
1587
1588
@ifclear gpgtwoone
1589
@item max-cert-size
1590
When retrieving a key via DNS CERT, only accept keys up to this size.
1591
Defaults to 16384 bytes.
1592
@end ifclear
1593
1594
@item debug
1595
Turn on debug output in the keyserver helper program. Note that the
1596
details of debug output depends on which keyserver helper program is
1597
being used, and in turn, on any libraries that the keyserver helper
1598
program uses internally (libcurl, openldap, etc).
1599
1600
@item check-cert
1601
Enable certificate checking if the keyserver presents one (for hkps or
1602
ldaps). Defaults to on.
1603
1604
@item ca-cert-file
1605
Provide a certificate store to override the system default. Only
1606
necessary if check-cert is enabled, and the keyserver is using a
1607
certificate that is not present in a system default certificate list.
1608
1609
Note that depending on the SSL library that the keyserver helper is
1610
built with, this may actually be a directory or a file.
1551
1611
@end table
1552
1612
1553
1613
@item --completes-needed @code{n}
1614
@opindex compliant-needed
1554
1615
Number of completely trusted users to introduce a new
1555
1616
key signer (defaults to 1).
1556
1617
1557
1618
@item --marginals-needed @code{n}
1619
@opindex marginals-needed
1558
1620
Number of marginally trusted users to introduce a new
1559
1621
key signer (defaults to 3)
1560
1622
1561
1623
@item --max-cert-depth @code{n}
1624
@opindex max-cert-depth
1562
1625
Maximum depth of a certification chain (default is 5).
1563
1626
1564
1627
@ifclear gpgtwoone
1565
1628
@item --simple-sk-checksum
1629
@opindex simple-sk-checksum
1566
1630
Secret keys are integrity protected by using a SHA-1 checksum. This
1567
1631
method is part of the upcoming enhanced OpenPGP specification but
1568
1632
GnuPG already uses it as a countermeasure against certain attacks.
1575
1639
@end ifclear
1576
1640
1577
1641
@item --no-sig-cache
1642
@opindex no-sig-cache
1578
1643
Do not cache the verification status of key signatures.
1579
1644
Caching gives a much better performance in key listings. However, if
1580
1645
you suspect that your public keyring is not save against write
1583
1648
can be done if someone else has write access to your public keyring.
1584
1649
1585
1650
@item --no-sig-create-check
1651
@opindex no-sig-create-check
1586
1652
GnuPG normally verifies each signature right after creation to protect
1587
1653
against bugs and hardware malfunctions which could leak out bits from
1588
1654
the secret key. This extra verification needs some time (about 115%
1592
1658
1593
1659
@item --auto-check-trustdb
1594
1660
@itemx --no-auto-check-trustdb
1661
@opindex auto-check-trustdb
1595
1662
If GnuPG feels that its information about the Web of Trust has to be
1596
1663
updated, it automatically runs the @option{--check-trustdb} command
1597
1664
internally. This may be a time consuming
1599
1666
1600
1667
@item --use-agent
1601
1668
@itemx --no-use-agent
1669
@opindex use-agent
1602
1670
@ifclear gpgone
1603
1671
This is dummy option. @command{@gpgname} always requires the agent.
1604
1672
@end ifclear
1609
1677
@end ifset
1610
1678
1611
1679
@item --gpg-agent-info
1680
@opindex gpg-agent-info
1612
1681
@ifclear gpgone
1613
1682
This is dummy option. It has no effect when used with @command{gpg2}.
1614
1683
@end ifclear
1620
1689
@end ifset
1621
1690
1622
1691
@item --lock-once
1692
@opindex lock-once
1623
1693
Lock the databases the first time a lock is requested
1624
1694
and do not release the lock until the process
1625
1695
terminates.
1626
1696
1627
1697
@item --lock-multiple
1698
@opindex lock-multiple
1628
1699
Release the locks every time a lock is no longer
1629
1700
needed. Use this to override a previous @option{--lock-once}
1630
1701
from a config file.
1631
1702
1632
1703
@item --lock-never
1704
@opindex lock-never
1633
1705
Disable locking entirely. This option should be used only in very
1634
1706
special environments, where it can be assured that only one process
1635
1707
is accessing those files. A bootable floppy with a stand-alone
1637
1709
option may lead to data and key corruption.
1638
1710
1639
1711
@item --exit-on-status-write-error
1712
@opindex exit-on-status-write-error
1640
1713
This option will cause write errors on the status FD to immediately
1641
1714
terminate the process. That should in fact be the default but it never
1642
1715
worked this way and thus we need an option to enable this, so that the
1646
1719
running gpg operations.
1647
1720
1648
1721
@item --limit-card-insert-tries @code{n}
1722
@opindex limit-card-insert-tries
1649
1723
With @code{n} greater than 0 the number of prompts asking to insert a
1650
1724
smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
1651
1725
all ask to insert a card if none has been inserted at startup. This
1654
1728
inserted card.
1655
1729
1656
1730
@item --no-random-seed-file
1731
@opindex no-random-seed-file
1657
1732
GnuPG uses a file to store its internal random pool over invocations.
1658
1733
This makes random generation faster; however sometimes write operations
1659
1734
are not desired. This option can be used to achieve that with the cost of
1660
1735
slower random generation.
1661
1736
1662
1737
@item --no-greeting
1738
@opindex no-greeting
1663
1739
Suppress the initial copyright message.
1664
1740
1665
1741
@item --no-secmem-warning
1742
@opindex no-secmem-warning
1666
1743
Suppress the warning about "using insecure memory".
1667
1744
1668
1745
@item --no-permission-warning
1746
@opindex permission-warning
1669
1747
Suppress the warning about unsafe file and home directory (@option{--homedir})
1670
1748
permissions. Note that the permission checks that GnuPG performs are
1671
1749
not intended to be authoritative, but rather they simply warn about
1679
1757
suppressed on the command line.
1680
1758
1681
1759
@item --no-mdc-warning
1760
@opindex no-mdc-warning
1682
1761
Suppress the warning about missing MDC integrity protection.
1683
1762
1684
1763
@item --require-secmem
1685
1764
@itemx --no-require-secmem
1765
@opindex require-secmem
1686
1766
Refuse to run if GnuPG cannot get secure memory. Defaults to no
1687
1767
(i.e. run, but give a warning).
1688
1768
1689
1769
1690
1770
@item --require-cross-certification
1691
1771
@itemx --no-require-cross-certification
1772
@opindex require-cross-certification
1692
1773
When verifying a signature made from a subkey, ensure that the cross
1693
1774
certification "back signature" on the subkey is present and valid. This
1694
1775
protects against a subtle attack against subkeys that can sign.
1697
1778
1698
1779
@item --expert
1699
1780
@itemx --no-expert
1781
@opindex expert
1700
1782
Allow the user to do certain nonsensical or "silly" things like
1701
1783
signing an expired or revoked key, or certain potentially incompatible
1702
1784
things like generating unusual key types. This also disables certain
1705
1787
understand the implications of what it allows you to do, leave this
1706
1788
off. @option{--no-expert} disables this option.
1707
1789
1708
1709
1710
1711
1790
@end table
1712
1791
1713
1792
1736
1815
@option{--default-recipient} is given.
1737
1816
1738
1817
@item --encrypt-to @code{name}
1818
@opindex encrypt-to
1739
1819
Same as @option{--recipient} but this one is intended for use in the
1740
1820
options file and may be used with your own user-id as an
1741
1821
"encrypt-to-self". These keys are only used when there are other
1744
1824
disabled keys can be used.
1745
1825
1746
1826
@item --hidden-encrypt-to @code{name}
1827
@opindex hidden-encrypt-to
1747
1828
Same as @option{--hidden-recipient} but this one is intended for use in the
1748
1829
options file and may be used with your own user-id as a hidden
1749
1830
"encrypt-to-self". These keys are only used when there are other
1752
1833
keys can be used.
1753
1834
1754
1835
@item --no-encrypt-to
1836
@opindex no-encrypt-to
1755
1837
Disable the use of all @option{--encrypt-to} and
1756
1838
@option{--hidden-encrypt-to} keys.
1757
1839
1758
1840
@item --group @code{name=value1 }
1841
@opindex group
1759
1842
Sets up a named group, which is similar to aliases in email programs.
1760
1843
Any time the group name is a recipient (@option{-r} or
1761
1844
@option{--recipient}), it will be expanded to the values
1771
1854
arguments.
1772
1855
1773
1856
@item --ungroup @code{name}
1857
@opindex ungroup
1774
1858
Remove a given entry from the @option{--group} list.
1775
1859
1776
1860
@item --no-groups
1861
@opindex no-groups
1777
1862
Remove all entries from the @option{--group} list.
1778
1863
1779
1864
@item --local-user @var{name}
1834
1919
OpenPGP format.
1835
1920
1836
1921
@item --no-armor
1922
@opindex no-armor
1837
1923
Assume the input data is not in ASCII armored format.
1838
1924
1839
1925
@item --output @var{file}
1852
1938
stop by the OS limits. Defaults to 0, which means "no limit".
1853
1939
1854
1940
@item --import-options @code{parameters}
1941
@opindex import-options
1855
1942
This is a space or comma delimited string that gives options for
1856
1943
importing keys. Options can be prepended with a `no-' to give the
1857
1944
opposite meaning. The options are:
1858
1945
1859
1946
@table @asis
1860
1947
1861
@item import-local-sigs
1862
Allow importing key signatures marked as "local". This is not
1863
generally useful unless a shared keyring scheme is being used.
1864
Defaults to no.
1865
1866
@item repair-pks-subkey-bug
1867
During import, attempt to repair the damage caused by the PKS keyserver
1868
bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
1869
that this cannot completely repair the damaged key as some crucial data
1870
is removed by the keyserver, but it does at least give you back one
1871
subkey. Defaults to no for regular @option{--import} and to yes for
1872
keyserver @option{--recv-keys}.
1873
1874
@item merge-only
1875
During import, allow key updates to existing keys, but do not allow
1876
any new keys to be imported. Defaults to no.
1877
1878
@item import-clean
1879
After import, compact (remove all signatures except the
1880
self-signature) any user IDs from the new key that are not usable.
1881
Then, remove any signatures from the new key that are not usable.
1882
This includes signatures that were issued by keys that are not present
1883
on the keyring. This option is the same as running the @option{--edit-key}
1884
command "clean" after import. Defaults to no.
1885
1886
@item import-minimal
1887
Import the smallest key possible. This removes all signatures except
1888
the most recent self-signature on each user ID. This option is the
1889
same as running the @option{--edit-key} command "minimize" after import.
1890
Defaults to no.
1948
@item import-local-sigs
1949
Allow importing key signatures marked as "local". This is not
1950
generally useful unless a shared keyring scheme is being used.
1951
Defaults to no.
1952
1953
@item repair-pks-subkey-bug
1954
During import, attempt to repair the damage caused by the PKS keyserver
1955
bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
1956
that this cannot completely repair the damaged key as some crucial data
1957
is removed by the keyserver, but it does at least give you back one
1958
subkey. Defaults to no for regular @option{--import} and to yes for
1959
keyserver @option{--recv-keys}.
1960
1961
@item merge-only
1962
During import, allow key updates to existing keys, but do not allow
1963
any new keys to be imported. Defaults to no.
1964
1965
@item import-clean
1966
After import, compact (remove all signatures except the
1967
self-signature) any user IDs from the new key that are not usable.
1968
Then, remove any signatures from the new key that are not usable.
1969
This includes signatures that were issued by keys that are not present
1970
on the keyring. This option is the same as running the @option{--edit-key}
1971
command "clean" after import. Defaults to no.
1972
1973
@item import-minimal
1974
Import the smallest key possible. This removes all signatures except
1975
the most recent self-signature on each user ID. This option is the
1976
same as running the @option{--edit-key} command "minimize" after import.
1977
Defaults to no.
1891
1978
@end table
1892
1979
1893
1980
@item --export-options @code{parameters}
1981
@opindex export-options
1894
1982
This is a space or comma delimited string that gives options for
1895
1983
exporting keys. Options can be prepended with a `no-' to give the
1896
1984
opposite meaning. The options are:
1897
1985
1898
1986
@table @asis
1899
1987
1900
@item export-local-sigs
1901
Allow exporting key signatures marked as "local". This is not
1902
generally useful unless a shared keyring scheme is being used.
1903
Defaults to no.
1904
1905
@item export-attributes
1906
Include attribute user IDs (photo IDs) while exporting. This is
1907
useful to export keys if they are going to be used by an OpenPGP
1908
program that does not accept attribute user IDs. Defaults to yes.
1909
1910
@item export-sensitive-revkeys
1911
Include designated revoker information that was marked as
1912
"sensitive". Defaults to no.
1913
1914
@c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
1915
@c export-reset-subkey-passwd hack is not anymore justified. Such use
1916
@c cases need to be implemented using a specialized secret key export
1917
@c tool.
1988
@item export-local-sigs
1989
Allow exporting key signatures marked as "local". This is not
1990
generally useful unless a shared keyring scheme is being used.
1991
Defaults to no.
1992
1993
@item export-attributes
1994
Include attribute user IDs (photo IDs) while exporting. This is
1995
useful to export keys if they are going to be used by an OpenPGP
1996
program that does not accept attribute user IDs. Defaults to yes.
1997
1998
@item export-sensitive-revkeys
1999
Include designated revoker information that was marked as
2000
"sensitive". Defaults to no.
2001
2002
@c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
2003
@c export-reset-subkey-passwd hack is not anymore justified. Such use
2004
@c cases need to be implemented using a specialized secret key export
2005
@c tool.
1918
2006
@ifclear gpgtwoone
1919
@item export-reset-subkey-passwd
1920
When using the @option{--export-secret-subkeys} command, this option resets
1921
the passphrases for all exported subkeys to empty. This is useful
1922
when the exported subkey is to be used on an unattended machine where
1923
a passphrase doesn't necessarily make sense. Defaults to no.
2007
@item export-reset-subkey-passwd
2008
When using the @option{--export-secret-subkeys} command, this option resets
2009
the passphrases for all exported subkeys to empty. This is useful
2010
when the exported subkey is to be used on an unattended machine where
2011
a passphrase doesn't necessarily make sense. Defaults to no.
1924
2012
@end ifclear
1925
2013
1926
@item export-clean
1927
Compact (remove all signatures from) user IDs on the key being
1928
exported if the user IDs are not usable. Also, do not export any
1929
signatures that are not usable. This includes signatures that were
1930
issued by keys that are not present on the keyring. This option is
1931
the same as running the @option{--edit-key} command "clean" before export
1932
except that the local copy of the key is not modified. Defaults to
1933
no.
2014
@item export-clean
2015
Compact (remove all signatures from) user IDs on the key being
2016
exported if the user IDs are not usable. Also, do not export any
2017
signatures that are not usable. This includes signatures that were
2018
issued by keys that are not present on the keyring. This option is
2019
the same as running the @option{--edit-key} command "clean" before export
2020
except that the local copy of the key is not modified. Defaults to
2021
no.
1934
2022
1935
@item export-minimal
1936
Export the smallest key possible. This removes all signatures except the
1937
most recent self-signature on each user ID. This option is the same as
1938
running the @option{--edit-key} command "minimize" before export except
1939
that the local copy of the key is not modified. Defaults to no.
2023
@item export-minimal
2024
Export the smallest key possible. This removes all signatures except the
2025
most recent self-signature on each user ID. This option is the same as
2026
running the @option{--edit-key} command "minimize" before export except
2027
that the local copy of the key is not modified. Defaults to no.
1940
2028
@end table
1941
2029
1942
2030
@item --with-colons
1980
2068
1981
2069
@item -t, --textmode
1982
2070
@itemx --no-textmode
2071
@opindex textmode
1983
2072
Treat input files as text and store them in the OpenPGP canonical text
1984
2073
form with standard "CRLF" line endings. This also sets the necessary
1985
2074
flags to inform the recipient that the encrypted or signed data is text
1999
2088
2000
2089
@item --force-v3-sigs
2001
2090
@itemx --no-force-v3-sigs
2091
@opindex force-v3-sigs
2002
2092
OpenPGP states that an implementation should generate v4 signatures
2003
2093
but PGP versions 5 through 7 only recognize v4 signatures on key
2004
2094
material. This option forces v3 signatures for signatures on data.
2010
2100
2011
2101
@item --force-v4-certs
2012
2102
@itemx --no-force-v4-certs
2103
@opindex force-v4-certs
2013
2104
Always use v4 key signatures even on v3 keys. This option also
2014
2105
changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
2015
2106
@option{--no-force-v4-certs} disables this option.
2016
2107
2017
2108
@item --force-mdc
2109
@opindex force-mdc
2018
2110
Force the use of encryption with a modification detection code. This
2019
2111
is always used with the newer ciphers (those with a blocksize greater
2020
2112
than 64 bits), or if all of the recipient keys indicate MDC support in
2021
2113
their feature flags.
2022
2114
2023
2115
@item --disable-mdc
2116
@opindex disable-mdc
2024
2117
Disable the use of the modification detection code. Note that by
2025
2118
using this option, the encrypted message becomes vulnerable to a
2026
2119
message modification attack.
2027
2120
2028
2121
@item --personal-cipher-preferences @code{string}
2122
@opindex personal-cipher-preferences
2029
2123
Set the list of personal cipher preferences to @code{string}. Use
2030
2124
@command{@gpgname --version} to get a list of available algorithms,
2031
2125
and use @code{none} to set no preference at all. This allows the user
2035
2129
used for the @option{--symmetric} encryption command.
2036
2130
2037
2131
@item --personal-digest-preferences @code{string}
2132
@opindex personal-digest-preferences
2038
2133
Set the list of personal digest preferences to @code{string}. Use
2039
2134
@command{@gpgname --version} to get a list of available algorithms,
2040
2135
and use @code{none} to set no preference at all. This allows the user
2042
2137
preferences, as GPG will only select an algorithm that is usable by
2043
2138
all recipients. The most highly ranked digest algorithm in this list
2044
2139
is also used when signing without encryption
2045
(e.g. @option{--clearsign} or @option{--sign}). The default value is
2046
SHA-1.
2140
(e.g. @option{--clearsign} or @option{--sign}).
2047
2141
2048
2142
@item --personal-compress-preferences @code{string}
2143
@opindex personal-compress-preferences
2049
2144
Set the list of personal compression preferences to @code{string}.
2050
2145
Use @command{@gpgname --version} to get a list of available
2051
2146
algorithms, and use @code{none} to set no preference at all. This
2056
2151
to consider (e.g. @option{--symmetric}).
2057
2152
2058
2153
@item --s2k-cipher-algo @code{name}
2154
@opindex s2k-cipher-algo
2059
2155
Use @code{name} as the cipher algorithm used to protect secret keys.
2060
2156
The default cipher is CAST5. This cipher is also used for
2061
2157
conventional encryption if @option{--personal-cipher-preferences} and
2062
2158
@option{--cipher-algo} is not given.
2063
2159
2064
2160
@item --s2k-digest-algo @code{name}
2161
@opindex s2k-digest-algo
2065
2162
Use @code{name} as the digest algorithm used to mangle the passphrases.
2066
2163
The default algorithm is SHA-1.
2067
2164
2068
2165
@item --s2k-mode @code{n}
2166
@opindex s2k-mode
2069
2167
Selects how passphrases are mangled. If @code{n} is 0 a plain
2070
2168
passphrase (which is not recommended) will be used, a 1 adds a salt to
2071
2169
the passphrase and a 3 (the default) iterates the whole process a
2073
2171
this mode is also used for conventional encryption.
2074
2172
2075
2173
@item --s2k-count @code{n}
2174
@opindex s2k-count
2076
2175
Specify how many times the passphrase mangling is repeated. This
2077
value may range between 1024 and 65011712 inclusive, and the default
2078
is 65536. Note that not all values in the 1024-65011712 range are
2079
legal and if an illegal value is selected, GnuPG will round up to the
2080
nearest legal value. This option is only meaningful if
2081
@option{--s2k-mode} is 3.
2176
value may range between 1024 and 65011712 inclusive. The default is
2177
inquired from gpg-agent. Note that not all values in the
2178
1024-65011712 range are legal and if an illegal value is selected,
2179
GnuPG will round up to the nearest legal value. This option is only
2180
meaningful if @option{--s2k-mode} is 3.
2082
2181
2083
2182
2084
2183
@end table
2184
2283
Don't make any changes (this is not completely implemented).
2185
2284
2186
2285
@item --list-only
2286
@opindex list-only
2187
2287
Changes the behaviour of some commands. This is like @option{--dry-run} but
2188
2288
different in some cases. The semantic of this command may be extended in
2189
2289
the future. Currently it only skips the actual decryption pass and
2200
2300
a numeric value or by a keyword:
2201
2301
2202
2302
@table @code
2203
@item none
2204
No debugging at all. A value of less than 1 may be used instead of
2205
the keyword.
2206
@item basic
2207
Some basic debug messages. A value between 1 and 2 may be used
2208
instead of the keyword.
2209
@item advanced
2210
More verbose debug messages. A value between 3 and 5 may be used
2211
instead of the keyword.
2212
@item expert
2213
Even more detailed messages. A value between 6 and 8 may be used
2214
instead of the keyword.
2215
@item guru
2216
All of the debug messages you can get. A value greater than 8 may be
2217
used instead of the keyword. The creation of hash tracing files is
2218
only enabled if the keyword is used.
2303
@item none
2304
No debugging at all. A value of less than 1 may be used instead of
2305
the keyword.
2306
@item basic
2307
Some basic debug messages. A value between 1 and 2 may be used
2308
instead of the keyword.
2309
@item advanced
2310
More verbose debug messages. A value between 3 and 5 may be used
2311
instead of the keyword.
2312
@item expert
2313
Even more detailed messages. A value between 6 and 8 may be used
2314
instead of the keyword.
2315
@item guru
2316
All of the debug messages you can get. A value greater than 8 may be
2317
used instead of the keyword. The creation of hash tracing files is
2318
only enabled if the keyword is used.
2219
2319
@end table
2220
2320
2221
2321
How these messages are mapped to the actual debugging flags is not
2228
2328
be given in C syntax (e.g. 0x0042).
2229
2329
2230
2330
@item --debug-all
2331
@opindex debug-all
2231
2332
Set all useful debugging flags.
2232
2333
2233
2334
@ifset gpgone
2234
2335
@item --debug-ccid-driver
2336
@opindex debug-ccid-driver
2235
2337
Enable debug output from the included CCID driver for smartcards.
2236
2338
Note that this option is only available on some system.
2237
2339
@end ifset
2244
2346
(e.g. "20070924T154812").
2245
2347
2246
2348
@item --enable-progress-filter
2349
@opindex enable-progress-filter
2247
2350
Enable certain PROGRESS status outputs. This option allows frontends
2248
2351
to display a progress indicator while gpg is processing larger files.
2249
2352
There is a slight performance overhead using it.
2250
2353
2251
2354
@item --status-fd @code{n}
2355
@opindex status-fd
2252
2356
Write special status strings to the file descriptor @code{n}.
2253
2357
See the file DETAILS in the documentation for a listing of them.
2254
2358
2255
2359
@item --status-file @code{file}
2360
@opindex status-file
2256
2361
Same as @option{--status-fd}, except the status data is written to file
2257
2362
@code{file}.
2258
2363
2259
2364
@item --logger-fd @code{n}
2365
@opindex logger-fd
2260
2366
Write log output to file descriptor @code{n} and not to STDERR.
2261
2367
2262
2368
@item --log-file @code{file}
2263
2369
@itemx --logger-file @code{file}
2370
@opindex log-file
2264
2371
Same as @option{--logger-fd}, except the logger data is written to file
2265
2372
@code{file}. Note that @option{--log-file} is only implemented for
2266
2373
GnuPG-2.
2267
2374
2268
2375
@item --attribute-fd @code{n}
2376
@opindex attribute-fd
2269
2377
Write attribute subpackets to the file descriptor @code{n}. This is most
2270
2378
useful for use with @option{--status-fd}, since the status messages are
2271
2379
needed to separate out the various subpackets from the stream delivered
2272
2380
to the file descriptor.
2273
2381
2274
2382
@item --attribute-file @code{file}
2383
@opindex attribute-file
2275
2384
Same as @option{--attribute-fd}, except the attribute data is written to
2276
2385
file @code{file}.
2277
2386
2278
2387
@item --comment @code{string}
2279
2388
@itemx --no-comments
2389
@opindex comment
2280
2390
Use @code{string} as a comment string in clear text signatures and ASCII
2281
2391
armored messages or keys (see @option{--armor}). The default behavior is
2282
2392
not to use a comment string. @option{--comment} may be repeated multiple
2288
2398
2289
2399
@item --emit-version
2290
2400
@itemx --no-emit-version
2401
@opindex emit-version
2291
2402
Force inclusion of the version string in ASCII armored output.
2292
2403
@option{--no-emit-version} disables this option.
2293
2404
2294
2405
@item --sig-notation @code{name=value}
2295
2406
@itemx --cert-notation @code{name=value}
2296
2407
@itemx -N, --set-notation @code{name=value}
2408
@opindex sig-notation
2409
@opindex cert-notation
2410
@opindex set-notation
2297
2411
Put the name value pair into the signature as notation data.
2298
2412
@code{name} must consist only of printable characters or spaces, and
2299
2413
must contain a '@@' character in the form keyname@@domain.example.com
2323
2437
@item --sig-policy-url @code{string}
2324
2438
@itemx --cert-policy-url @code{string}
2325
2439
@itemx --set-policy-url @code{string}
2440
@opindex sig-policy-url
2441
@opindex cert-policy-url
2442
@opindex set-policy-url
2326
2443
Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19). If
2327
2444
you prefix it with an exclamation mark (!), the policy URL packet will
2328
2445
be flagged as critical. @option{--sig-policy-url} sets a policy url for
2332
2449
The same %-expandos used for notation data are available here as well.
2333
2450
2334
2451
@item --sig-keyserver-url @code{string}
2452
@opindex sig-keyserver-url
2335
2453
Use @code{string} as a preferred keyserver URL for data signatures. If
2336
2454
you prefix it with an exclamation mark (!), the keyserver URL packet
2337
2455
will be flagged as critical.
2339
2457
The same %-expandos used for notation data are available here as well.
2340
2458
2341
2459
@item --set-filename @code{string}
2460
@opindex set-filename
2342
2461
Use @code{string} as the filename which is stored inside messages.
2343
2462
This overrides the default, which is to use the actual filename of the
2344
2463
file being encrypted.
2345
2464
2346
2465
@item --for-your-eyes-only
2347
2466
@itemx --no-for-your-eyes-only
2467
@opindex for-your-eyes-only
2348
2468
Set the `for your eyes only' flag in the message. This causes GnuPG to
2349
2469
refuse to save the file unless the @option{--output} option is given,
2350
2470
and PGP to use a "secure viewer" with a claimed Tempest-resistant font
2353
2473
2354
2474
@item --use-embedded-filename
2355
2475
@itemx --no-use-embedded-filename
2476
@opindex use-embedded-filename
2356
2477
Try to create a file with a name as embedded in the data. This can be
2357
2478
a dangerous option as it allows to overwrite files. Defaults to no.
2358
2479
2359
2480
@item --cipher-algo @code{name}
2481
@opindex cipher-algo
2360
2482
Use @code{name} as cipher algorithm. Running the program with the
2361
2483
command @option{--version} yields a list of supported algorithms. If
2362
2484
this is not used the cipher algorithm is selected from the preferences
2366
2488
same thing.
2367
2489
2368
2490
@item --digest-algo @code{name}
2491
@opindex digest-algo
2369
2492
Use @code{name} as the message digest algorithm. Running the program
2370
2493
with the command @option{--version} yields a list of supported algorithms. In
2371
2494
general, you do not want to use this option as it allows you to
2373
2496
safe way to accomplish the same thing.
2374
2497
2375
2498
@item --compress-algo @code{name}
2499
@opindex compress-algo
2376
2500
Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
2377
2501
compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
2378
2502
"bzip2" is a more modern compression scheme that can compress some
2395
2519
safe way to accomplish the same thing.
2396
2520
2397
2521
@item --cert-digest-algo @code{name}
2522
@opindex cert-digest-algo
2398
2523
Use @code{name} as the message digest algorithm used when signing a
2399
2524
key. Running the program with the command @option{--version} yields a
2400
2525
list of supported algorithms. Be aware that if you choose an algorithm
2403
2528
possibly your entire key.
2404
2529
2405
2530
@item --disable-cipher-algo @code{name}
2531
@opindex disable-cipher-algo
2406
2532
Never allow the use of @code{name} as cipher algorithm.
2407
2533
The given name will not be checked so that a later loaded algorithm
2408
2534
will still get disabled.
2409
2535
2410
2536
@item --disable-pubkey-algo @code{name}
2537
@opindex disable-pubkey-algo
2411
2538
Never allow the use of @code{name} as public key algorithm.
2412
2539
The given name will not be checked so that a later loaded algorithm
2413
2540
will still get disabled.
2414
2541
2415
2542
@item --throw-keyids
2416
2543
@itemx --no-throw-keyids
2544
@opindex throw-keyids
2417
2545
Do not put the recipient key IDs into encrypted messages. This helps to
2418
2546
hide the receivers of the message and is a limited countermeasure
2419
2547
against traffic analysis.@footnote{Using a little social engineering
2425
2553
recipients.
2426
2554
2427
2555
@item --not-dash-escaped
2556
@opindex not-dash-escaped
2428
2557
This option changes the behavior of cleartext signatures
2429
2558
so that they can be used for patch files. You should not
2430
2559
send such an armored file via email because all spaces
2435
2564
2436
2565
@item --escape-from-lines
2437
2566
@itemx --no-escape-from-lines
2567
@opindex escape-from-lines
2438
2568
Because some mailers change lines starting with "From " to ">From " it
2439
2569
is good to handle such lines in a special way when creating cleartext
2440
2570
signatures to prevent the mail system from breaking the signature. Note
2442
2572
default. @option{--no-escape-from-lines} disables this option.
2443
2573
2444
2574
@item --passphrase-repeat @code{n}
2575
@opindex passphrase-repeat
2445
2576
Specify how many times @command{@gpgname} will request a new
2446
2577
passphrase be repeated. This is useful for helping memorize a
2447
2578
passphrase. Defaults to 1 repetition.
2448
2579
2449
2580
@item --passphrase-fd @code{n}
2581
@opindex passphrase-fd
2450
2582
Read the passphrase from file descriptor @code{n}. Only the first line
2451
2583
will be read from file descriptor @code{n}. If you use 0 for @code{n},
2452
2584
the passphrase will be read from STDIN. This can only be used if only
2457
2589
@end ifclear
2458
2590
2459
2591
@item --passphrase-file @code{file}
2592
@opindex passphrase-file
2460
2593
Read the passphrase from file @code{file}. Only the first line will
2461
2594
be read from file @code{file}. This can only be used if only one
2462
2595
passphrase is supplied. Obviously, a passphrase stored in a file is
2468
2601
@end ifclear
2469
2602
2470
2603
@item --passphrase @code{string}
2604
@opindex passphrase
2471
2605
Use @code{string} as the passphrase. This can only be used if only one
2472
2606
passphrase is supplied. Obviously, this is of very questionable
2473
2607
security on a multi-user system. Don't use this option if you can
2478
2612
@end ifclear
2479
2613
2480
2614
@item --command-fd @code{n}
2615
@opindex command-fd
2481
2616
This is a replacement for the deprecated shared-memory IPC mode.
2482
2617
If this option is enabled, user input on questions is not expected
2483
2618
from the TTY but from the given file descriptor. It should be used
2485
2620
distribution for details on how to use it.
2486
2621
2487
2622
@item --command-file @code{file}
2623
@opindex command-file
2488
2624
Same as @option{--command-fd}, except the commands are read out of file
2489
2625
@code{file}
2490
2626
2491
2627
@item --allow-non-selfsigned-uid
2492
2628
@itemx --no-allow-non-selfsigned-uid
2629
@opindex allow-non-selfsigned-uid
2493
2630
Allow the import and use of keys with user IDs which are not
2494
2631
self-signed. This is not recommended, as a non self-signed user ID is
2495
2632
trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
2496
2633
2497
2634
@item --allow-freeform-uid
2635
@opindex allow-freeform-uid
2498
2636
Disable all checks on the form of the user ID while generating a new
2499
2637
one. This option should only be used in very special environments as
2500
2638
it does not ensure the de-facto standard format of user IDs.
2501
2639
2502
2640
@item --ignore-time-conflict
2641
@opindex ignore-time-conflict
2503
2642
GnuPG normally checks that the timestamps associated with keys and
2504
2643
signatures have plausible values. However, sometimes a signature
2505
2644
seems to be older than the key due to clock problems. This option
2507
2646
timestamp issues on subkeys.
2508
2647
2509
2648
@item --ignore-valid-from
2649
@opindex ignore-valid-from
2510
2650
GnuPG normally does not select and use subkeys created in the future.
2511
2651
This option allows the use of such keys and thus exhibits the
2512
pre-1.0.7 behaviour. You should not use this option unless you there
2652
pre-1.0.7 behaviour. You should not use this option unless there
2513
2653
is some clock problem. See also @option{--ignore-time-conflict} for timestamp
2514
2654
issues with signatures.
2515
2655
2516
2656
@item --ignore-crc-error
2657
@opindex ignore-crc-error
2517
2658
The ASCII armor used by OpenPGP is protected by a CRC checksum against
2518
2659
transmission errors. Occasionally the CRC gets mangled somewhere on
2519
2660
the transmission channel but the actual content (which is protected by
2521
2662
to ignore CRC errors.
2522
2663
2523
2664
@item --ignore-mdc-error
2665
@opindex ignore-mdc-error
2524
2666
This option changes a MDC integrity protection failure into a warning.
2525
2667
This can be useful if a message is partially corrupt, but it is
2526
2668
necessary to get as much data as possible out of the corrupt message.
2528
2670
message was tampered with intentionally by an attacker.
2529
2671
2530
2672
@item --no-default-keyring
2673
@opindex no-default-keyring
2531
2674
Do not add the default keyrings to the list of keyrings. Note that
2532
2675
GnuPG will not operate without any keyrings, so if you use this option
2533
2676
and do not provide alternate keyrings via @option{--keyring} or
2535
2678
secret keyrings.
2536
2679
2537
2680
@item --skip-verify
2681
@opindex skip-verify
2538
2682
Skip the signature verification step. This may be
2539
2683
used to make the decryption faster if the signature
2540
2684
verification is not needed.
2541
2685
2542
2686
@item --with-key-data
2687
@opindex with-key-data
2543
2688
Print key listings delimited by colons (like @option{--with-colons}) and
2544
2689
print the public key data.
2545
2690
2546
2691
@item --fast-list-mode
2692
@opindex fast-list-mode
2547
2693
Changes the output of the list commands to work faster; this is achieved
2548
2694
by leaving some parts empty. Some applications don't need the user ID
2549
2695
and the trust information given in the listings. By using this options
2552
2698
use this option.
2553
2699
2554
2700
@item --no-literal
2701
@opindex no-literal
2555
2702
This is not for normal use. Use the source to see for what it might be useful.
2556
2703
2557
2704
@item --set-filesize
2705
@opindex set-filesize
2558
2706
This is not for normal use. Use the source to see for what it might be useful.
2559
2707
2560
2708
@item --show-session-key
2709
@opindex show-session-key
2561
2710
Display the session key used for one message. See
2562
2711
@option{--override-session-key} for the counterpart of this option.
2563
2712
2568
2717
FORCED TO DO SO.
2569
2718
2570
2719
@item --override-session-key @code{string}
2720
@opindex override-session-key
2571
2721
Don't use the public key but the session key @code{string}. The format
2572
2722
of this string is the same as the one printed by
2573
2723
@option{--show-session-key}. This option is normally not used but comes
2577
2727
2578
2728
@item --ask-sig-expire
2579
2729
@itemx --no-ask-sig-expire
2730
@opindex ask-sig-expire
2580
2731
When making a data signature, prompt for an expiration time. If this
2581
2732
option is not specified, the expiration time set via
2582
2733
@option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
2583
2734
disables this option.
2584
2735
2585
2736
@item --default-sig-expire
2737
@opindex default-sig-expire
2586
2738
The default expiration time to use for signature expiration. Valid
2587
2739
values are "0" for no expiration, a number followed by the letter d
2588
2740
(for days), w (for weeks), m (for months), or y (for years) (for
2591
2743
2592
2744
@item --ask-cert-expire
2593
2745
@itemx --no-ask-cert-expire
2746
@opindex ask-cert-expire
2594
2747
When making a key signature, prompt for an expiration time. If this
2595
2748
option is not specified, the expiration time set via
2596
2749
@option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
2597
2750
disables this option.
2598
2751
2599
2752
@item --default-cert-expire
2753
@opindex default-cert-expire
2600
2754
The default expiration time to use for key signature expiration.
2601
2755
Valid values are "0" for no expiration, a number followed by the
2602
2756
letter d (for days), w (for weeks), m (for months), or y (for years)
2604
2758
absolute date in the form YYYY-MM-DD. Defaults to "0".
2605
2759
2606
2760
@item --allow-secret-key-import
2761
@opindex allow-secret-key-import
2607
2762
This is an obsolete option and is not used anywhere.
2608
2763
2609
2764
@item --allow-multiple-messages
2610
2765
@item --no-allow-multiple-messages
2766
@opindex allow-multiple-messages
2611
2767
Allow processing of multiple OpenPGP messages contained in a single file
2612
2768
or stream. Some programs that call GPG are not prepared to deal with
2613
2769
multiple messages being processed together, so this option defaults to
2614
2770
no. Note that versions of GPG prior to 1.4.7 always allowed multiple
2615
messages.
2771
messages.
2616
2772
2617
2773
Warning: Do not use this option unless you need it as a temporary
2618
2774
workaround!
2619
2775
2620
2776
2621
2777
@item --enable-special-filenames
2778
@opindex enable-special-filenames
2622
2779
This options enables a mode in which filenames of the form
2623
2780
@file{-&n}, where n is a non-negative decimal number,
2624
2781
refer to the file descriptor n and not to a file with that name.
2625
2782
2626
2783
@item --no-expensive-trust-checks
2784
@opindex no-expensive-trust-checks
2627
2785
Experimental use only.
2628
2786
2629
2787
@item --preserve-permissions
2788
@opindex preserve-permissions
2630
2789
Don't change the permissions of a secret keyring back to user
2631
2790
read/write only. Use this option only if you really know what you are doing.
2632
2791
2674
2833
2675
2834
@ifset gpgone
2676
2835
@item --load-extension @code{name}
2836
@opindex load-extension
2677
2837
Load an extension module. If @code{name} does not contain a slash it is
2678
2838
searched for in the directory configured when GnuPG was built
2679
2839
(generally "/usr/local/lib/gnupg"). Extensions are not generally
2682
2842
2683
2843
@item --show-photos
2684
2844
@itemx --no-show-photos
2845
@opindex show-photos
2685
2846
Causes @option{--list-keys}, @option{--list-sigs},
2686
2847
@option{--list-public-keys}, @option{--list-secret-keys}, and verifying
2687
2848
a signature to also display the photo ID attached to the key, if
2690
2851
[no-]show-photos} instead.
2691
2852
2692
2853
@item --show-keyring
2854
@opindex show-keyring
2693
2855
Display the keyring name at the head of key listings to show which
2694
2856
keyring a given key resides on. This option is deprecated: use
2695
2857
@option{--list-options [no-]show-keyring} instead.
2696
2858
2697
2859
@ifset gpgone
2698
2860
@item --ctapi-driver @code{file}
2861
@opindex ctapi-driver
2699
2862
Use @code{file} to access the smartcard reader. The current default
2700
2863
is `libtowitoko.so'. Note that the use of this interface is
2701
2864
deprecated; it may be removed in future releases.
2702
2865
@end ifset
2703
2866
2704
2867
@item --always-trust
2868
@opindex always-trust
2705
2869
Identical to @option{--trust-model always}. This option is deprecated.
2706
2870
2707
2871
@item --show-notation
2708
2872
@itemx --no-show-notation
2873
@opindex show-notation
2709
2874
Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
2710
2875
as well as when verifying a signature with a notation in it. These
2711
2876
options are deprecated. Use @option{--list-options [no-]show-notation}
2713
2878
2714
2879
@item --show-policy-url
2715
2880
@itemx --no-show-policy-url
2881
@opindex show-policy-url
2716
2882
Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
2717
2883
listings as well as when verifying a signature with a policy URL in
2718
2884
it. These options are deprecated. Use @option{--list-options
2738
2904
2739
2905
@table @file
2740
2906
2741
@item gpg.conf
2742
@cindex gpg.conf
2743
This is the standard configuration file read by @command{@gpgname} on
2744
startup. It may contain any valid long option; the leading two dashes
2745
may not be entered and the option may not be abbreviated. This default
2746
name may be changed on the command line (@pxref{option --options}).
2747
You should backup this file.
2907
@item gpg.conf
2908
@cindex gpg.conf
2909
This is the standard configuration file read by @command{@gpgname} on
2910
startup. It may contain any valid long option; the leading two dashes
2911
may not be entered and the option may not be abbreviated. This default
2912
name may be changed on the command line (@pxref{option --options}).
2913
You should backup this file.
2748
2914
2749
2915
@end table
2750
2916
2763
2929
2764
2930
2765
2931
@table @file
2766
@item ~/.gnupg/secring.gpg
2767
The secret keyring. You should backup this file.
2768
2769
@item ~/.gnupg/secring.gpg.lock
2770
The lock file for the secret keyring.
2771
2772
@item ~/.gnupg/pubring.gpg
2773
The public keyring. You should backup this file.
2774
2775
@item ~/.gnupg/pubring.gpg.lock
2776
The lock file for the public keyring.
2777
2778
@item ~/.gnupg/trustdb.gpg
2779
The trust database. There is no need to backup this file; it is better
2780
to backup the ownertrust values (@pxref{option --export-ownertrust}).
2781
2782
@item ~/.gnupg/trustdb.gpg.lock
2783
The lock file for the trust database.
2784
2785
@item ~/.gnupg/random_seed
2786
A file used to preserve the state of the internal random pool.
2787
2788
@item /usr[/local]/share/gnupg/options.skel
2789
The skeleton options file.
2790
2791
@item /usr[/local]/lib/gnupg/
2792
Default location for extensions.
2932
@item ~/.gnupg/secring.gpg
2933
The secret keyring. You should backup this file.
2934
2935
@item ~/.gnupg/secring.gpg.lock
2936
The lock file for the secret keyring.
2937
2938
@item ~/.gnupg/pubring.gpg
2939
The public keyring. You should backup this file.
2940
2941
@item ~/.gnupg/pubring.gpg.lock
2942
The lock file for the public keyring.
2943
2944
@item ~/.gnupg/trustdb.gpg
2945
The trust database. There is no need to backup this file; it is better
2946
to backup the ownertrust values (@pxref{option --export-ownertrust}).
2947
2948
@item ~/.gnupg/trustdb.gpg.lock
2949
The lock file for the trust database.
2950
2951
@item ~/.gnupg/random_seed
2952
A file used to preserve the state of the internal random pool.
2953
2954
@item /usr[/local]/share/gnupg/options.skel
2955
The skeleton options file.
2956
2957
@item /usr[/local]/lib/gnupg/
2958
Default location for extensions.
2793
2959
2794
2960
@end table
2795
2961
2798
2964
2799
2965
@table @asis
2800
2966
2801
@item HOME
2802
Used to locate the default home directory.
2803
2804
@item GNUPGHOME
2805
If set directory used instead of "~/.gnupg".
2806
2807
@item GPG_AGENT_INFO
2808
Used to locate the gpg-agent.
2809
@ifset gpgone
2810
This is only honored when @option{--use-agent} is set.
2811
@end ifset
2812
The value consists of 3 colon delimited fields: The first is the path
2813
to the Unix Domain Socket, the second the PID of the gpg-agent and the
2814
protocol version which should be set to 1. When starting the gpg-agent
2815
as described in its documentation, this variable is set to the correct
2816
value. The option @option{--gpg-agent-info} can be used to override it.
2817
2818
@item PINENTRY_USER_DATA
2819
This value is passed via gpg-agent to pinentry. It is useful to convey
2820
extra information to a custom pinentry.
2821
2822
@item COLUMNS
2823
@itemx LINES
2824
Used to size some displays to the full size of the screen.
2825
2826
2827
@item LANGUAGE
2828
Apart from its use by GNU, it is used in the W32 version to override the
2829
language selection done through the Registry. If used and set to a
2830
valid and available language name (@var{langid}), the file with the
2831
translation is loaded from
2832
@code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}. Here @var{gpgdir} is the
2833
directory out of which the gpg binary has been loaded. If it can't be
2834
loaded the Registry is tried and as last resort the native Windows
2835
locale system is used.
2967
@item HOME
2968
Used to locate the default home directory.
2969
2970
@item GNUPGHOME
2971
If set directory used instead of "~/.gnupg".
2972
2973
@item GPG_AGENT_INFO
2974
Used to locate the gpg-agent.
2975
@ifset gpgone
2976
This is only honored when @option{--use-agent} is set.
2977
@end ifset
2978
The value consists of 3 colon delimited fields: The first is the path
2979
to the Unix Domain Socket, the second the PID of the gpg-agent and the
2980
protocol version which should be set to 1. When starting the gpg-agent
2981
as described in its documentation, this variable is set to the correct
2982
value. The option @option{--gpg-agent-info} can be used to override it.
2983
2984
@item PINENTRY_USER_DATA
2985
This value is passed via gpg-agent to pinentry. It is useful to convey
2986
extra information to a custom pinentry.
2987
2988
@item COLUMNS
2989
@itemx LINES
2990
Used to size some displays to the full size of the screen.
2991
2992
2993
@item LANGUAGE
2994
Apart from its use by GNU, it is used in the W32 version to override the
2995
language selection done through the Registry. If used and set to a
2996
valid and available language name (@var{langid}), the file with the
2997
translation is loaded from
2998
2999
@code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}. Here @var{gpgdir} is the
3000
directory out of which the gpg binary has been loaded. If it can't be
3001
loaded the Registry is tried and as last resort the native Windows
3002
locale system is used.
2836
3003
2837
3004
@end table
2838
3005
2963
3130
archives for similar problems and second check whether such a bug has
2964
3131
already been reported to our bug tracker at http://bugs.gnupg.org .
2965
3132
3133
@c *******************************************
3134
@c *************** **************
3135
@c *************** UNATTENDED **************
3136
@c *************** **************
3137
@c *******************************************
3138
@manpause
3139
@node Unattended Usage of GPG
3140
@section Unattended Usage
3141
3142
@command{gpg} is often used as a backend engine by other software. To help
3143
with this a machine interface has been defined to have an unambiguous
3144
way to do this. The options @option{--status-fd} and @option{--batch}
3145
are almost always required for this.
3146
3147
@menu
3148
* Unattended GPG key generation:: Unattended key generation
3149
@end menu
3150
3151
3152
@node Unattended GPG key generation,,,Unattended Usage of GPG
3153
@section Unattended key generation
3154
3155
The command @option{--gen-key} may be used along with the option
3156
@option{--batch} for unattended key generation. The parameters are
3157
either read from stdin or given as a file on the command line.
3158
The format of the parameter file is as follows:
3159
3160
@itemize @bullet
3161
@item Text only, line length is limited to about 1000 characters.
3162
@item UTF-8 encoding must be used to specify non-ASCII characters.
3163
@item Empty lines are ignored.
3164
@item Leading and trailing while space is ignored.
3165
@item A hash sign as the first non white space character indicates
3166
a comment line.
3167
@item Control statements are indicated by a leading percent sign, the
3168
arguments are separated by white space from the keyword.
3169
@item Parameters are specified by a keyword, followed by a colon. Arguments
3170
are separated by white space.
3171
@item
3172
The first parameter must be @samp{Key-Type}; control statements may be
3173
placed anywhere.
3174
@item
3175
The order of the parameters does not matter except for @samp{Key-Type}
3176
which must be the first parameter. The parameters are only used for
3177
the generated keyblock (primary and subkeys); parameters from previous
3178
sets are not used. Some syntactically checks may be performed.
3179
@item
3180
Key generation takes place when either the end of the parameter file
3181
is reached, the next @samp{Key-Type} parameter is encountered or at the
3182
control statement @samp{%commit} is encountered.
3183
@end itemize
3184
3185
@noindent
3186
Control statements:
3187
3188
@table @asis
3189
3190
@item %echo @var{text}
3191
Print @var{text} as diagnostic.
3192
3193
@item %dry-run
3194
Suppress actual key generation (useful for syntax checking).
3195
3196
@item %commit
3197
Perform the key generation. Note that an implicit commit is done at
3198
the next @asis{Key-Type} parameter.
3199
3200
@item %pubring @var{filename}
3201
@itemx %secring @var{filename}
3202
Do not write the key to the default or commandline given keyring but
3203
to @var{filename}. This must be given before the first commit to take
3204
place, duplicate specification of the same filename is ignored, the
3205
last filename before a commit is used. The filename is used until a
3206
new filename is used (at commit points) and all keys are written to
3207
that file. If a new filename is given, this file is created (and
3208
overwrites an existing one). For GnuPG versions prior to 2.1, both
3209
control statements must be given. For GnuPG 2.1 and later
3210
@samp{%secring} is a no-op.
3211
3212
@item %ask-passphrase
3213
@itemx %no-ask-passphrase
3214
Enable (or disable) a mode where the command @option{passphrase} is
3215
ignored and instead the usual passphrase dialog is used. This does
3216
not make sense for batch key generation; however the unattended key
3217
generation feature is also used by GUIs and this feature relinquishes
3218
the GUI from implementing its own passphrase entry code. These are
3219
global control statements and affect all future key genrations.
3220
3221
@item %no-protection
3222
Since GnuPG version 2.1 it is not anymore possible to specify a
3223
passphrase for unattended key generation. The passphrase command is
3224
simply ignored and @samp{%ask-passpharse} is thus implicitly enabled.
3225
Using this option allows the creation of keys without any passphrase
3226
protection. This option is mainly intended for regression tests.
3227
3228
@item %transient-key
3229
If given the keys are created using a faster and a somewhat less
3230
secure random number generator. This option may be used for keys
3231
which are only used for a short time and do not require full
3232
cryptographic strength. It takes only effect if used together with
3233
the control statement @samp{%no-protection}.
3234
3235
@end table
3236
3237
@noindent
3238
General Parameters:
3239
3240
@table @asis
3241
3242
@item Key-Type: @var{algo}
3243
Starts a new parameter block by giving the type of the primary
3244
key. The algorithm must be capable of signing. This is a required
3245
parameter. @var{algo} may either be an OpenPGP algorithm number or a
3246
string with the algorithm name. The special value @samp{default} may
3247
be used for @var{algo} to create the default key type; in this case a
3248
@samp{Key-Usage} shall not be given and @samp{default} also be used
3249
for @samp{Subkey-Type}.
3250
3251
@item Key-Length: @var{nbits}
3252
The requested length of the generated key in bits. The default is
3253
returned by running the command @samp{gpg2 --gpgconf-list}.
3254
3255
@item Key-Grip: @var{hexstring}
3256
This is optional and used to generate a CSR or certificate for an
3257
already existing key. Key-Length will be ignored when given.
3258
3259
@item Key-Usage: @var{usage-list}
3260
Space or comma delimited list of key usages. Allowed values are
3261
@samp{encrypt}, @samp{sign}, and @samp{auth}. This is used to
3262
generate the key flags. Please make sure that the algorithm is
3263
capable of this usage. Note that OpenPGP requires that all primary
3264
keys are capable of certification, so no matter what usage is given
3265
here, the @samp{cert} flag will be on. If no @samp{Key-Usage} is
3266
specified and the @samp{Key-Type} is not @samp{default}, all allowed
3267
usages for that particular algorithm are used; if it is not given but
3268
@samp{default} is used the usage will be @samp{sign}.
3269
3270
@item Subkey-Type: @var{algo}
3271
This generates a secondary key (subkey). Currently only one subkey
3272
can be handled. See also @samp{Key-Type} above.
3273
3274
@item Subkey-Length: @var{nbits}
3275
Length of the secondary key (subkey) in bits. The default is returned
3276
by running the command @samp{gpg2 --gpgconf-list}".
3277
3278
@item Subkey-Usage: @var{usage-list}
3279
Key usage lists for a subkey; similar to @samp{Key-Usage}.
3280
3281
@item Passphrase: @var{string}
3282
If you want to specify a passphrase for the secret key,
3283
enter it here. Default is not to use any passphrase.
3284
3285
@item Name-Real: @var{name}
3286
@itemx Name-Comment: @var{comment}
3287
@itemx Name-Email: @var{email}
3288
The three parts of a user name. Remember to use UTF-8 encoding here.
3289
If you don't give any of them, no user ID is created.
3290
3291
@item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y])
3292
Set the expiration date for the key (and the subkey). It may either
3293
be entered in ISO date format (2000-08-15) or as number of days,
3294
weeks, month or years. The special notation "seconds=N" is also
3295
allowed to directly give an Epoch value. Without a letter days are
3296
assumed. Note that there is no check done on the overflow of the type
3297
used by OpenPGP for timestamps. Thus you better make sure that the
3298
given value make sense. Although OpenPGP works with time intervals,
3299
GnuPG uses an absolute value internally and thus the last year we can
3300
represent is 2105.
3301
3302
@item Ceation-Date: @var{iso-date}
3303
Set the creation date of the key as stored in the key information and
3304
which is also part of the fingerprint calculation. Either a date like
3305
"1986-04-26" or a full timestamp like "19860426T042640" may be used.
3306
The time is considered to be UTC. If it is not given the current time
3307
is used.
3308
3309
@item Preferences: @var{string}
3310
Set the cipher, hash, and compression preference values for this key.
3311
This expects the same type of string as the sub-command @samp{setpref}
3312
in the @option{--edit-key} menu.
3313
3314
@item Revoker: @var{algo}:@var{fpr} [sensitive]
3315
Add a designated revoker to the generated key. Algo is the public key
3316
algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
3317
@var{fpr} is the fingerprint of the designated revoker. The optional
3318
@samp{sensitive} flag marks the designated revoker as sensitive
3319
information. Only v4 keys may be designated revokers.
3320
3321
@item Keyserver: @var{string}
3322
This is an optional parameter that specifies the preferred keyserver
3323
URL for the key.
3324
3325
@item Handle: @var{string}
3326
This is an optional parameter only used with the status lines
3327
KEY_CREATED and KEY_NOT_CREATED. @var{string} may be up to 100
3328
characters and should not contain spaces. It is useful for batch key
3329
generation to associate a key parameter block with a status line.
3330
3331
@end table
3332
3333
@noindent
3334
Here is an example on how to create a key:
3335
@smallexample
3336
$ cat >foo <<EOF
3337
%echo Generating a basic OpenPGP key
3338
Key-Type: DSA
3339
Key-Length: 1024
3340
Subkey-Type: ELG-E
3341
Subkey-Length: 1024
3342
Name-Real: Joe Tester
3343
Name-Comment: with stupid passphrase
3344
Name-Email: joe@@foo.bar
3345
Expire-Date: 0
3346
Passphrase: abc
3347
%pubring foo.pub
3348
%secring foo.sec
3349
# Do a commit here, so that we can later print "done" :-)
3350
%commit
3351
%echo done
3352
EOF
3353
$ gpg2 --batch --gen-key foo
3354
[...]
3355
$ gpg2 --no-default-keyring --secret-keyring ./foo.sec \
3356
--keyring ./foo.pub --list-secret-keys
3357
/home/wk/work/gnupg-stable/scratch/foo.sec
3358
------------------------------------------
3359
sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
3360
ssb 1024g/8F70E2C0 2000-03-09
3361
@end smallexample
3362
3363
3364
@noindent
3365
If you want to create a key with the default algorithms you would use
3366
these parameters:
3367
@smallexample
3368
%echo Generating a default key
3369
Key-Type: default
3370
Subkey-Type: default
3371
Name-Real: Joe Tester
3372
Name-Comment: with stupid passphrase
3373
Name-Email: joe@@foo.bar
3374
Expire-Date: 0
3375
Passphrase: abc
3376
%pubring foo.pub
3377
%secring foo.sec
3378
# Do a commit here, so that we can later print "done" :-)
3379
%commit
3380
%echo done
3381
@end smallexample
3382
3383
3384
3385
2966
3386
@mansect see also
2967
3387
@ifset isman
2968
@command{gpgv}(1),
3388
@command{gpgv}(1),
2969
3389
@ifclear gpgone
2970
@command{gpgsm}(1),
3390
@command{gpgsm}(1),
2971
3391
@command{gpg-agent}(1)
2972
3392
@end ifclear
2973
3393
@end ifset
Loggerhead is a web-based interface for Breezy
Version: 2.0.1