1728
1778
Flag the current user id as the primary one, removes the
1729
primary user id flag from all other user ids and sets the
1730
timestamp of all affected self-signatures one second ahead.
1731
Note that setting a photo user ID as primary makes it primary
1732
over other photo user IDs, and setting a regular user ID as
1733
primary makes it primary over other regular user IDs.
1779
primary user id flag from all other user ids and sets the
1780
timestamp of all affected self-signatures one second ahead.
1781
Note that setting a photo user ID as primary makes it
1782
primary over other photo user IDs, and setting a regular
1783
user ID as primary makes it primary over other regular user
1736
1787
Set a preferred keyserver for the specified user ID(s). This
1737
allows other users to know where you prefer they get your key
1738
from. See `--keyserver-options honor-keyserver-url' for more
1739
on how this works. Setting a value of "none" removes an
1740
existing preferred keyserver.
1788
allows other users to know where you prefer they get your
1789
key from. See `--keyserver-options honor-keyserver-url' for
1790
more on how this works. Setting a value of "none" removes
1791
an existing preferred keyserver.
1743
1794
Set a name=value notation for the specified user ID(s). See
1744
1795
`--cert-notation' for more on how this works. Setting a value
1745
of "none" removes all notations, setting a notation prefixed
1746
with a minus sign (-) removes that notation, and setting a
1747
notation name (without the =value) prefixed with a minus sign
1748
removes all notations with that name.
1796
of "none" removes all notations, setting a notation
1797
prefixed with a minus sign (-) removes that notation, and
1798
setting a notation name (without the =value) prefixed with
1799
a minus sign removes all notations with that name.
1751
1802
List preferences from the selected user ID. This shows the
1752
actual preferences, without including any implied preferences.
1803
actual preferences, without including any implied
1755
1807
More verbose preferences listing for the selected user ID.
1756
This shows the preferences in effect by including the implied
1757
preferences of 3DES (cipher), SHA-1 (digest), and
1758
Uncompressed (compression) if they are not already included
1759
in the preference list. In addition, the preferred keyserver
1760
and signature notations (if any) are shown.
1808
This shows the preferences in effect by including the
1809
implied preferences of 3DES (cipher), SHA-1 (digest), and
1810
Uncompressed (compression) if they are not already included
1811
in the preference list. In addition, the preferred
1812
keyserver and signature notations (if any) are shown.
1762
1814
setpref `string'
1763
1815
Set the list of user ID preferences to `string' for all (or
1764
just the selected) user IDs. Calling setpref with no
1765
arguments sets the preference list to the default (either
1766
built-in or set via `--default-preference-list'), and calling
1767
setpref with "none" as the argument sets an empty preference
1768
list. Use `gpg2 --version' to get a list of available
1769
algorithms. Note that while you can change the preferences on
1770
an attribute user ID (aka "photo ID"), GnuPG does not select
1771
keys via attribute user IDs so these preferences will not be
1816
just the selected) user IDs. Calling setpref with no
1817
arguments sets the preference list to the default (either
1818
built-in or set via `--default-preference-list'), and
1819
calling setpref with "none" as the argument sets an empty
1820
preference list. Use `gpg2 --version' to get a list of
1821
available algorithms. Note that while you can change the
1822
preferences on an attribute user ID (aka "photo ID"), GnuPG
1823
does not select keys via attribute user IDs so these
1824
preferences will not be used by GnuPG.
1774
1826
When setting preferences, you should list the algorithms in
1775
the order which you'd like to see them used by someone else
1776
when encrypting a message to your key. If you don't include
1777
3DES, it will be automatically added at the end. Note that
1778
there are many factors that go into choosing an algorithm
1779
(for example, your key may not be the only recipient), and so
1780
the remote OpenPGP application being used to send to you may
1781
or may not follow your exact chosen order for a given
1782
message. It will, however, only choose an algorithm that is
1783
present on the preference list of every recipient key. See
1784
also the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section
1827
the order which you'd like to see them used by someone else
1828
when encrypting a message to your key. If you don't
1829
include 3DES, it will be automatically added at the end.
1830
Note that there are many factors that go into choosing an
1831
algorithm (for example, your key may not be the only
1832
recipient), and so the remote OpenPGP application being used
1833
to send to you may or may not follow your exact chosen
1834
order for a given message. It will, however, only choose
1835
an algorithm that is present on the preference list of
1836
every recipient key. See also the INTEROPERABILITY WITH
1837
OTHER OPENPGP PROGRAMS section below.
1788
1840
Add a subkey to this key.
1794
1846
Transfer the selected secret subkey (or the primary key if no
1795
subkey has been selected) to a smartcard. The secret key in
1796
the keyring will be replaced by a stub if the key could be
1797
stored successfully on the card and you use the save command
1798
later. Only certain key types may be transferred to the card.
1799
A sub menu allows you to select on what card to store the
1800
key. Note that it is not possible to get that key back from
1801
the card - if the card gets broken your secret key will be
1802
lost unless you have a backup somewhere.
1847
subkey has been selected) to a smartcard. The secret key in
1848
the keyring will be replaced by a stub if the key could be
1849
stored successfully on the card and you use the save
1850
command later. Only certain key types may be transferred to
1851
the card. A sub menu allows you to select on what card to
1852
store the key. Note that it is not possible to get that key
1853
back from the card - if the card gets broken your secret
1854
key will be lost unless you have a backup somewhere.
1804
1856
bkuptocard `file'
1805
1857
Restore the given file to a card. This command may be used to
1806
restore a backup key (as generated during card
1807
initialization) to a new card. In almost all cases this will
1808
be the encryption key. You should use this command only with
1809
the corresponding public key and make sure that the file
1810
given as argument is indeed the backup to restore. You should
1811
then select 2 to restore as encryption key. You will first
1812
be asked to enter the passphrase of the backup key and then
1813
for the Admin PIN of the card.
1858
restore a backup key (as generated during card
1859
initialization) to a new card. In almost all cases this
1860
will be the encryption key. You should use this command
1861
only with the corresponding public key and make sure that the
1862
file given as argument is indeed the backup to restore. You
1863
should then select 2 to restore as encryption key. You
1864
will first be asked to enter the passphrase of the backup
1865
key and then for the Admin PIN of the card.
1816
1868
Remove a subkey (secondart key). Note that it is not possible
1817
to retract a subkey, once it has been send to the public
1818
(i.e. to a keyserver). In that case you better use `revkey'.
1869
to retract a subkey, once it has been send to the public
1870
(i.e. to a keyserver). In that case you better use
1821
1874
Revoke a subkey.
1824
1877
Change the key or subkey expiration time. If a subkey is
1825
selected, the expiration time of this subkey will be changed.
1826
With no selection, the key expiration of the primary key is
1878
selected, the expiration time of this subkey will be
1879
changed. With no selection, the key expiration of the
1880
primary key is changed.
1830
1883
Change the owner trust value for the key. This updates the
1831
trust-db immediately and no save is required.
1884
trust-db immediately and no save is required.
1835
1888
Disable or enable an entire key. A disabled key can not
1836
normally be used for encryption.
1889
normally be used for encryption.
1839
1892
Add a designated revoker to the key. This takes one optional
1840
argument: "sensitive". If a designated revoker is marked as
1841
sensitive, it will not be exported by default (see
1893
argument: "sensitive". If a designated revoker is marked as
1894
sensitive, it will not be exported by default (see
1842
1895
export-options).
1851
1904
Compact (by removing all signatures except the selfsig) any
1852
user ID that is no longer usable (e.g. revoked, or expired).
1853
Then, remove any signatures that are not usable by the trust
1854
calculations. Specifically, this removes any signature that
1855
does not validate, any signature that is superseded by a
1856
later signature, revoked signatures, and signatures issued by
1857
keys that are not present on the keyring.
1905
user ID that is no longer usable (e.g. revoked, or
1906
expired). Then, remove any signatures that are not usable
1907
by the trust calculations. Specifically, this removes any
1908
signature that does not validate, any signature that is
1909
superseded by a later signature, revoked signatures, and
1910
signatures issued by keys that are not present on the keyring.
1860
1913
Make the key as small as possible. This removes all
1861
signatures from each user ID except for the most recent
1914
signatures from each user ID except for the most recent
1862
1915
self-signature.
1865
1918
Add cross-certification signatures to signing subkeys that
1866
may not currently have them. Cross-certification signatures
1867
protect against a subtle attack against signing subkeys. See
1868
`--require-cross-certification'. All new keys generated have
1869
this signature by default, so this option is only useful to
1870
bring older keys up to date.
1919
may not currently have them. Cross-certification signatures
1920
protect against a subtle attack against signing subkeys. See
1921
`--require-cross-certification'. All new keys generated have
1922
this signature by default, so this option is only useful to
1923
bring older keys up to date.
1873
1926
Save all changes to the key rings and quit.
1876
Quit the program without updating the key rings.
1929
Quit the program without updating the key rings.
1879
1931
The listing shows you the key with its secondary keys and all user
1880
1932
ids. The primary user id is indicated by a dot, and selected keys
2405
2462
include-revoked
2406
2463
When searching for a key with `--search-keys', include keys
2407
that are marked on the keyserver as revoked. Note that not
2408
all keyservers differentiate between revoked and unrevoked
2409
keys, and for such keyservers this option is meaningless.
2410
Note also that most keyservers do not have cryptographic
2411
verification of key revocations, and so turning this option
2464
that are marked on the keyserver as revoked. Note that not
2465
all keyservers differentiate between revoked and unrevoked
2466
keys, and for such keyservers this option is meaningless.
2467
Note also that most keyservers do not have cryptographic
2468
verification of key revocations, and so turning this option
2412
2469
off may result in skipping keys that are incorrectly marked
2415
2472
include-disabled
2416
2473
When searching for a key with `--search-keys', include keys
2417
that are marked on the keyserver as disabled. Note that this
2418
option is not used with HKP keyservers.
2474
that are marked on the keyserver as disabled. Note that
2475
this option is not used with HKP keyservers.
2420
2477
auto-key-retrieve
2421
2478
This option enables the automatic retrieving of keys from a
2422
keyserver when verifying signatures made by keys that are not
2423
on the local keyring.
2479
keyserver when verifying signatures made by keys that are
2480
not on the local keyring.
2425
2482
Note that this option makes a "web bug" like behavior
2426
possible. Keyserver operators can see which keys you
2427
request, so by sending you a message signed by a brand new
2428
key (which you naturally will not have on your local
2429
keyring), the operator can tell both your IP address and the
2430
time when you verified the signature.
2483
possible. Keyserver operators can see which keys you
2484
request, so by sending you a message signed by a brand new
2485
key (which you naturally will not have on your local
2486
keyring), the operator can tell both your IP address and
2487
the time when you verified the signature.
2432
2489
honor-keyserver-url
2433
2490
When using `--refresh-keys', if the key in question has a
2434
preferred keyserver URL, then use that preferred keyserver to
2435
refresh the key from. In addition, if auto-key-retrieve is
2436
set, and the signature being verified has a preferred
2437
keyserver URL, then use that preferred keyserver to fetch the
2438
key from. Defaults to yes.
2491
preferred keyserver URL, then use that preferred keyserver
2492
to refresh the key from. In addition, if auto-key-retrieve
2493
is set, and the signature being verified has a preferred
2494
keyserver URL, then use that preferred keyserver to fetch
2495
the key from. Defaults to yes.
2440
2497
honor-pka-record
2441
2498
If auto-key-retrieve is set, and the signature being verified
2442
has a PKA record, then use the PKA information to fetch the
2443
key. Defaults to yes.
2499
has a PKA record, then use the PKA information to fetch the
2500
key. Defaults to yes.
2445
2502
include-subkeys
2446
2503
When receiving a key, include subkeys as potential targets.
2447
Note that this option is not used with HKP keyservers, as
2448
they do not support retrieving keys by subkey id.
2504
Note that this option is not used with HKP keyservers, as
2505
they do not support retrieving keys by subkey id.
2451
2508
On most Unix-like platforms, GnuPG communicates with the
2452
keyserver helper program via pipes, which is the most
2453
efficient method. This option forces GnuPG to use temporary
2454
files to communicate. On some platforms (such as Win32 and
2509
keyserver helper program via pipes, which is the most
2510
efficient method. This option forces GnuPG to use temporary
2511
files to communicate. On some platforms (such as Win32 and
2455
2512
RISC OS), this option is always enabled.
2457
2514
keep-temp-files
2458
2515
If using `use-temp-files', do not delete the temp files after
2459
using them. This option is useful to learn the keyserver
2460
communication protocol by reading the temporary files.
2516
using them. This option is useful to learn the keyserver
2517
communication protocol by reading the temporary files.
2463
2520
Tell the keyserver helper program to be more verbose. This
2464
option can be repeated multiple times to increase the
2521
option can be repeated multiple times to increase the
2465
2522
verbosity level.
2468
2525
Tell the keyserver helper program how long (in seconds) to
2469
try and perform a keyserver action before giving up. Note
2470
that performing multiple actions at the same time uses this
2471
timeout value per action. For example, when retrieving
2472
multiple keys via `--recv-keys', the timeout applies
2526
try and perform a keyserver action before giving up. Note
2527
that performing multiple actions at the same time uses this
2528
timeout value per action. For example, when retrieving
2529
multiple keys via `--recv-keys', the timeout applies
2473
2530
separately to each key retrieval, and not to the
2474
2531
`--recv-keys' command as a whole. Defaults to 30 seconds.
2476
2533
http-proxy=`value'
2477
2534
Set the proxy to use for HTTP and HKP keyservers. This
2478
overrides the "http_proxy" environment variable, if any.
2535
overrides the "http_proxy" environment variable, if any.
2481
2538
When retrieving a key via DNS CERT, only accept keys up to
2482
this size. Defaults to 16384 bytes.
2539
this size. Defaults to 16384 bytes.
2485
2542
Turn on debug output in the keyserver helper program. Note
2486
that the details of debug output depends on which keyserver
2487
helper program is being used, and in turn, on any libraries
2488
that the keyserver helper program uses internally (libcurl,
2543
that the details of debug output depends on which keyserver
2544
helper program is being used, and in turn, on any libraries
2545
that the keyserver helper program uses internally (libcurl,
2489
2546
openldap, etc).
2492
2549
Enable certificate checking if the keyserver presents one
2493
(for hkps or ldaps). Defaults to on.
2550
(for hkps or ldaps). Defaults to on.
2496
2553
Provide a certificate store to override the system default.
2497
Only necessary if check-cert is enabled, and the keyserver is
2498
using a certificate that is not present in a system default
2554
Only necessary if check-cert is enabled, and the keyserver
2555
is using a certificate that is not present in a system
2556
default certificate list.
2501
2558
Note that depending on the SSL library that the keyserver
2502
helper is built with, this may actually be a directory or a
2559
helper is built with, this may actually be a directory or a
2505
2562
`--completes-needed `n''
2760
2817
import-local-sigs
2761
2818
Allow importing key signatures marked as "local". This is not
2762
generally useful unless a shared keyring scheme is being used.
2819
generally useful unless a shared keyring scheme is being
2820
used. Defaults to no.
2765
2822
repair-pks-subkey-bug
2766
2823
During import, attempt to repair the damage caused by the PKS
2767
keyserver bug (pre version 0.9.6) that mangles keys with
2768
multiple subkeys. Note that this cannot completely repair the
2769
damaged key as some crucial data is removed by the keyserver,
2770
but it does at least give you back one subkey. Defaults to no
2771
for regular `--import' and to yes for keyserver `--recv-keys'.
2824
keyserver bug (pre version 0.9.6) that mangles keys with
2825
multiple subkeys. Note that this cannot completely repair
2826
the damaged key as some crucial data is removed by the
2827
keyserver, but it does at least give you back one subkey.
2828
Defaults to no for regular `--import' and to yes for
2829
keyserver `--recv-keys'.
2774
2832
During import, allow key updates to existing keys, but do not
2775
allow any new keys to be imported. Defaults to no.
2833
allow any new keys to be imported. Defaults to no.
2778
2836
After import, compact (remove all signatures except the
2779
2837
self-signature) any user IDs from the new key that are not
2780
usable. Then, remove any signatures from the new key that
2781
are not usable. This includes signatures that were issued by
2782
keys that are not present on the keyring. This option is the
2783
same as running the `--edit-key' command "clean" after
2838
usable. Then, remove any signatures from the new key that
2839
are not usable. This includes signatures that were issued
2840
by keys that are not present on the keyring. This option is
2841
the same as running the `--edit-key' command "clean" after
2784
2842
import. Defaults to no.
2787
2845
Import the smallest key possible. This removes all signatures
2788
except the most recent self-signature on each user ID. This
2789
option is the same as running the `--edit-key' command
2790
"minimize" after import. Defaults to no.
2846
except the most recent self-signature on each user ID. This
2847
option is the same as running the `--edit-key' command
2848
"minimize" after import. Defaults to no.
2792
2850
`--export-options `parameters''
2793
2851
This is a space or comma delimited string that gives options for
3746
3805
already been reported to our bug tracker at http://bugs.gnupg.org .
3808
File: gnupg.info, Node: Unattended Usage of GPG, Prev: GPG Examples, Up: Invoking GPG
3810
3.5 Unattended Usage
3811
====================
3813
`gpg' is often used as a backend engine by other software. To help
3814
with this a machine interface has been defined to have an unambiguous
3815
way to do this. The options `--status-fd' and `--batch' are almost
3816
always required for this.
3820
* Unattended GPG key generation:: Unattended key generation
3823
File: gnupg.info, Node: Unattended GPG key generation, Up: Unattended Usage of GPG
3825
3.6 Unattended key generation
3826
=============================
3828
The command `--gen-key' may be used along with the option `--batch' for
3829
unattended key generation. The parameters are either read from stdin
3830
or given as a file on the command line. The format of the parameter
3833
* Text only, line length is limited to about 1000 characters.
3835
* UTF-8 encoding must be used to specify non-ASCII characters.
3837
* Empty lines are ignored.
3839
* Leading and trailing while space is ignored.
3841
* A hash sign as the first non white space character indicates a
3844
* Control statements are indicated by a leading percent sign, the
3845
arguments are separated by white space from the keyword.
3847
* Parameters are specified by a keyword, followed by a colon.
3848
Arguments are separated by white space.
3850
* The first parameter must be `Key-Type'; control statements may be
3853
* The order of the parameters does not matter except for `Key-Type'
3854
which must be the first parameter. The parameters are only used
3855
for the generated keyblock (primary and subkeys); parameters
3856
from previous sets are not used. Some syntactically checks may
3859
* Key generation takes place when either the end of the parameter
3860
file is reached, the next `Key-Type' parameter is encountered or
3861
at the control statement `%commit' is encountered.
3866
Print TEXT as diagnostic.
3869
Suppress actual key generation (useful for syntax checking).
3872
Perform the key generation. Note that an implicit commit is done
3873
at the next Key-Type parameter.
3877
Do not write the key to the default or commandline given keyring
3878
but to FILENAME. This must be given before the first commit to
3879
take place, duplicate specification of the same filename is
3880
ignored, the last filename before a commit is used. The filename
3881
is used until a new filename is used (at commit points) and all
3882
keys are written to that file. If a new filename is given, this
3883
file is created (and overwrites an existing one). For GnuPG
3884
versions prior to 2.1, both control statements must be given. For
3885
GnuPG 2.1 and later `%secring' is a no-op.
3889
Enable (or disable) a mode where the command `passphrase' is
3890
ignored and instead the usual passphrase dialog is used. This does
3891
not make sense for batch key generation; however the unattended key
3892
generation feature is also used by GUIs and this feature
3893
relinquishes the GUI from implementing its own passphrase entry
3894
code. These are global control statements and affect all future
3898
Since GnuPG version 2.1 it is not anymore possible to specify a
3899
passphrase for unattended key generation. The passphrase command
3900
is simply ignored and `%ask-passpharse' is thus implicitly enabled.
3901
Using this option allows the creation of keys without any
3902
passphrase protection. This option is mainly intended for
3906
If given the keys are created using a faster and a somewhat less
3907
secure random number generator. This option may be used for keys
3908
which are only used for a short time and do not require full
3909
cryptographic strength. It takes only effect if used together with
3910
the control statement `%no-protection'.
3916
Starts a new parameter block by giving the type of the primary
3917
key. The algorithm must be capable of signing. This is a required
3918
parameter. ALGO may either be an OpenPGP algorithm number or a
3919
string with the algorithm name. The special value `default' may
3920
be used for ALGO to create the default key type; in this case a
3921
`Key-Usage' shall not be given and `default' also be used for
3925
The requested length of the generated key in bits. The default is
3926
returned by running the command `gpg2 --gpgconf-list'.
3929
This is optional and used to generate a CSR or certificate for an
3930
already existing key. Key-Length will be ignored when given.
3932
Key-Usage: USAGE-LIST
3933
Space or comma delimited list of key usages. Allowed values are
3934
`encrypt', `sign', and `auth'. This is used to generate the key
3935
flags. Please make sure that the algorithm is capable of this
3936
usage. Note that OpenPGP requires that all primary keys are
3937
capable of certification, so no matter what usage is given here,
3938
the `cert' flag will be on. If no `Key-Usage' is specified and
3939
the `Key-Type' is not `default', all allowed usages for that
3940
particular algorithm are used; if it is not given but `default' is
3941
used the usage will be `sign'.
3944
This generates a secondary key (subkey). Currently only one subkey
3945
can be handled. See also `Key-Type' above.
3947
Subkey-Length: NBITS
3948
Length of the secondary key (subkey) in bits. The default is
3949
returned by running the command `gpg2 --gpgconf-list'".
3951
Subkey-Usage: USAGE-LIST
3952
Key usage lists for a subkey; similar to `Key-Usage'.
3955
If you want to specify a passphrase for the secret key, enter it
3956
here. Default is not to use any passphrase.
3959
Name-Comment: COMMENT
3961
The three parts of a user name. Remember to use UTF-8 encoding
3962
here. If you don't give any of them, no user ID is created.
3964
Expire-Date: ISO-DATE|(NUMBER[d|w|m|y])
3965
Set the expiration date for the key (and the subkey). It may
3966
either be entered in ISO date format (2000-08-15) or as number of
3967
days, weeks, month or years. The special notation "seconds=N" is
3968
also allowed to directly give an Epoch value. Without a letter
3969
days are assumed. Note that there is no check done on the
3970
overflow of the type used by OpenPGP for timestamps. Thus you
3971
better make sure that the given value make sense. Although
3972
OpenPGP works with time intervals, GnuPG uses an absolute value
3973
internally and thus the last year we can represent is 2105.
3975
Ceation-Date: ISO-DATE
3976
Set the creation date of the key as stored in the key information
3977
and which is also part of the fingerprint calculation. Either a
3978
date like "1986-04-26" or a full timestamp like "19860426T042640"
3979
may be used. The time is considered to be UTC. If it is not
3980
given the current time is used.
3983
Set the cipher, hash, and compression preference values for this
3984
key. This expects the same type of string as the sub-command
3985
`setpref' in the `--edit-key' menu.
3987
Revoker: ALGO:FPR [sensitive]
3988
Add a designated revoker to the generated key. Algo is the public
3989
key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
3990
FPR is the fingerprint of the designated revoker. The optional
3991
`sensitive' flag marks the designated revoker as sensitive
3992
information. Only v4 keys may be designated revokers.
3995
This is an optional parameter that specifies the preferred
3996
keyserver URL for the key.
3999
This is an optional parameter only used with the status lines
4000
KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100
4001
characters and should not contain spaces. It is useful for batch
4002
key generation to associate a key parameter block with a status
4006
Here is an example on how to create a key:
4008
%echo Generating a basic OpenPGP key
4013
Name-Real: Joe Tester
4014
Name-Comment: with stupid passphrase
4015
Name-Email: joe@foo.bar
4020
# Do a commit here, so that we can later print "done" :-)
4024
$ gpg2 --batch --gen-key foo
4026
$ gpg2 --no-default-keyring --secret-keyring ./foo.sec \
4027
--keyring ./foo.pub --list-secret-keys
4028
/home/wk/work/gnupg-stable/scratch/foo.sec
4029
------------------------------------------
4030
sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
4031
ssb 1024g/8F70E2C0 2000-03-09
4033
If you want to create a key with the default algorithms you would use
4035
%echo Generating a default key
4037
Subkey-Type: default
4038
Name-Real: Joe Tester
4039
Name-Comment: with stupid passphrase
4040
Name-Email: joe@foo.bar
4045
# Do a commit here, so that we can later print "done" :-)
3749
4050
File: gnupg.info, Node: Invoking GPGSM, Next: Invoking SCDAEMON, Prev: Invoking GPG, Up: Top
3751
4052
4 Invoking GPGSM
4526
4830
``GOODSIG', `VALIDSIG' `TRUST_NEVER''
4528
4832
Error verifying a signature
4529
For some reason the signature could not be verified, i.e. it can't
4530
be decided whether the signature is valid or invalid. A common
4531
reason for this is a missing certificate.
4833
For some reason the signature could not be verified, i.e. it
4834
cannot be decided whether the signature is valid or invalid. A
4835
common reason for this is a missing certificate.
4839
File: gnupg.info, Node: CSR and certificate creation, Up: Unattended Usage
4841
4.7 CSR and certificate creation
4842
================================
4844
*Please notice*: The immediate creation of certificates is only
4845
supported by GnuPG version 2.1 or later. With a 2.0 version you may
4848
The command `--gen-key' may be used along with the option `--batch' to
4849
either create a certificate signing request (CSR) or an X.509
4850
certificate. The is controlled by a parameter file; the format of this
4853
* Text only, line length is limited to about 1000 characters.
4855
* UTF-8 encoding must be used to specify non-ASCII characters.
4857
* Empty lines are ignored.
4859
* Leading and trailing while space is ignored.
4861
* A hash sign as the first non white space character indicates a
4864
* Control statements are indicated by a leading percent sign, the
4865
arguments are separated by white space from the keyword.
4867
* Parameters are specified by a keyword, followed by a colon.
4868
Arguments are separated by white space.
4870
* The first parameter must be `Key-Type', control statements may be
4873
* The order of the parameters does not matter except for `Key-Type'
4874
which must be the first parameter. The parameters are only used
4875
for the generated CSR/certificate; parameters from previous sets
4876
are not used. Some syntactically checks may be performed.
4878
* Key generation takes place when either the end of the parameter
4879
file is reached, the next `Key-Type' parameter is encountered or
4880
at the control statement `%commit' is encountered.
4885
Print TEXT as diagnostic.
4888
Suppress actual key generation (useful for syntax checking).
4891
Perform the key generation. Note that an implicit commit is done
4892
at the next Key-Type parameter.
4898
Starts a new parameter block by giving the type of the primary
4899
key. The algorithm must be capable of signing. This is a required
4900
parameter. The only supported value for ALGO is `rsa'.
4903
The requested length of a generated key in bits. Defaults to 2048.
4906
This is optional and used to generate a CSR or certificatet for an
4907
already existing key. Key-Length will be ignored when given.
4909
Key-Usage: USAGE-LIST
4910
Space or comma delimited list of key usage, allowed values are
4911
`encrypt', `sign' and `cert'. This is used to generate the
4912
keyUsage extension. Please make sure that the algorithm is
4913
capable of this usage. Default is to allow encrypt and sign.
4915
Name-DN: SUBJECT-NAME
4916
This is the Distinguished Name (DN) of the subject in RFC-2253
4920
This is an email address for the altSubjectName. This parameter is
4921
optional but may occur several times to add several email
4922
addresses to a certificate.
4925
The is an DNS name for the altSubjectName. This parameter is
4926
optional but may occur several times to add several DNS names to a
4930
This is an URI for the altSubjectName. This parameter is optional
4931
but may occur several times to add several URIs to a certificate.
4933
Additional parameters used to create a certificate (in contrast to a
4934
certificate signing request):
4937
If this parameter is given an X.509 certificate will be generated.
4938
SN is expected to be a hex string representing an unsigned integer
4939
of arbitary length. The special value `random' can be used to
4940
create a 64 bit random serial number.
4942
Issuer-DN: ISSUER-NAME
4943
This is the DN name of the issuer in rfc2253 format. If it is not
4944
set it will default to the subject DN and a special GnuPG
4945
extension will be included in the certificate to mark it as a
4946
standalone certificate.
4948
Creation-Date: ISO-DATE
4949
Not-Before: ISO-DATE
4950
Set the notBefore date of the certificate. Either a date like
4951
`1986-04-26' or `1986-04-26 12:00' or a standard ISO timestamp
4952
like `19860426T042640' may be used. The time is considered to be
4953
UTC. If it is not given the current date is used.
4955
Expire-Date: ISO-DATE
4957
Set the notAfter date of the certificate. Either a date like
4958
`2063-04-05' or `2063-04-05 17:00' or a standard ISO timestamp
4959
like `20630405T170000' may be used. The time is considered to be
4960
UTC. If it is not given a default value in the not too far future
4963
Signing-Key: KEYGRIP
4964
This gives the keygrip of the key used to sign the certificate.
4965
If it is not given a self-signed certificate will be created. For
4966
compatibility with future versions, it is suggested to prefix the
4969
Hash-Algo: HASH-ALGO
4970
Use HASH-ALGO for this CSR or certificate. The supported hash
4971
algorithms are: `sha1', `sha256', `sha384' and `sha512'; they may
4972
also be specified with uppercase letters. The default is `sha1'.
4535
4976
File: gnupg.info, Node: GPGSM Protocol, Prev: Unattended Usage, Up: Invoking GPGSM
4537
4.7 The Protocol the Server Mode Uses.
4978
4.8 The Protocol the Server Mode Uses.
4538
4979
======================================
4540
4981
Description of the protocol used to access `GPGSM'. `GPGSM' does
7270
7750
delete the file then. You may export the file again at any time as long
7271
7751
as it is available in GnuPG's private key database.
7274
File: gnupg.info, Node: System Notes, Next: Debugging, Prev: Howtos, Up: Top
7276
9 Notes pertaining to certain OSes.
7277
***********************************
7279
GnuPG has been developed on GNU/Linux systems and is know to work on
7280
almost all Free OSes. All modern POSIX systems should be supported
7281
right now, however there are probably a lot of smaller glitches we need
7282
to fix first. The major problem areas are:
7284
* For logging to sockets and other internal operations the
7285
`fopencookie' function (`funopen' under *BSD) is used. This is a
7286
very convenient function which makes it possible to create outputs
7287
in a structures and easy maintainable way. The drawback however
7288
is that most proprietary OSes don't support this function. At
7289
g10 Code we have looked into several ways on how to overcome this
7290
limitation but no sufficiently easy and maintainable way has been
7291
found. Porting _glibc_ to a general POSIX system is of course an
7292
option and would make writing portable software much easier; this
7293
it has not yet been done and the system administrator would need
7294
to cope with the GNU specific admin things in addition to the
7295
generic ones of his system.
7297
We have now settled to use explicit stdio wrappers with a
7298
functionality similar to funopen. Although the code for this has
7299
already been written (_libestream_), we have not yet changed GnuPG
7302
This means that on systems not supporting either `funopen' or
7303
`fopencookie', logging to a socket won't work, prompts are not
7304
formatted as pretty as they should be and `gpgsm''s `LISTKEYS'
7305
Assuan command does not work.
7307
* We are planning to use file descriptor passing for interprocess
7308
communication. This will allow us save a lot of resources and
7309
improve performance of certain operations a lot. Systems not
7310
supporting this won't gain these benefits but we try to keep them
7311
working the standard way as it is done today.
7313
* We require more or less full POSIX compatibility. This has been
7314
around for 15 years now and thus we don't believe it makes sense to
7315
support non POSIX systems anymore. Well, we of course the usual
7316
workarounds for near POSIX systems well be applied.
7318
There is one exception of this rule: Systems based the Microsoft
7319
Windows API (called here _W32_) will be supported to some extend.
7324
* W32 Notes:: Microsoft Windows Notes
7327
File: gnupg.info, Node: W32 Notes, Up: System Notes
7329
9.1 Microsoft Windows Notes
7330
===========================
7332
Current limitations are:
7334
* `gpgconf' does not create backup files, so in case of trouble your
7335
configuration file might get lost.
7337
* `watchgnupg' is not available. Logging to sockets is not possible.
7339
* The periodical smartcard status checking done by `scdaemon' is not
7344
File: gnupg.info, Node: Debugging, Next: Copying, Prev: System Notes, Up: Top
7346
10 How to solve problems
7347
************************
7349
Everyone knows that software often does not do what it should do and
7350
thus there is a need to track down problems. We call this debugging in
7351
a reminiscent to the moth jamming a relay in a Mark II box back in 1947.
7353
Most of the problems a merely configuration and user problems but
7354
nevertheless there are the most annoying ones and responsible for many
7355
gray hairs. We try to give some guidelines here on how to identify and
7356
solve the problem at hand.
7360
* Debugging Tools:: Description of some useful tools.
7361
* Debugging Hints:: Various hints on debugging.
7362
* Common Problems:: Commonly seen problems.
7363
* Architecture Details:: How the whole thing works internally.
7366
File: gnupg.info, Node: Debugging Tools, Next: Debugging Hints, Up: Debugging
7368
10.1 Debugging Tools
7369
====================
7371
The GnuPG distribution comes with a couple of tools, useful to help find
7372
and solving problems.
7376
* kbxutil:: Scrutinizing a keybox file.
7379
File: gnupg.info, Node: kbxutil, Up: Debugging Tools
7381
10.1.1 Scrutinizing a keybox file
7382
---------------------------------
7384
A keybox is a file format used to store public keys along with meta
7385
information and indices. The commonly used one is the file
7386
`pubring.kbx' in the `.gnupg' directory. It contains all X.509
7387
certificates as well as OpenPGP keys(1) .
7389
When called the standard way, e.g.:
7391
`kbxutil ~/.gnupg/pubring.kbx'
7393
it lists all records (called blobs) with there meta-information in a
7394
human readable format.
7396
To see statistics on the keybox in question, run it using
7398
`kbxutil --stats ~/.gnupg/pubring.kbx'
7400
and you get an output like:
7402
Total number of blobs: 99
7409
ephemeral flagged: 17
7411
In this example you see that the keybox does not have any OpenPGP
7412
keys but contains 98 X.509 certificates and a total of 17 keys or
7413
certificates are flagged as ephemeral, meaning that they are only
7414
temporary stored (cached) in the keybox and won't get listed using the
7415
usual commands provided by `gpgsm' or `gpg'. 81 certificates are stored
7416
in a standard way and directly available from `gpgsm'.
7418
To find duplicated certificates and keyblocks in a keybox file (this
7419
should not occur but sometimes things go wrong), run it using
7421
`kbxutil --find-dups ~/.gnupg/pubring.kbx'
7423
---------- Footnotes ----------
7425
(1) Well, OpenPGP keys are not implemented, `gpg' still used the
7426
keyring file `pubring.gpg'
7429
File: gnupg.info, Node: Debugging Hints, Next: Common Problems, Prev: Debugging Tools, Up: Debugging
7431
10.2 Various hints on debugging.
7432
================================
7434
* How to find the IP address of a keyserver
7436
If a round robin URL of is used for a keyserver (e.g.
7437
subkeys.gnupg.org); it is not easy to see what server is actually
7438
used. Using the keyserver debug option as in
7440
gpg --keyserver-options debug=1 -v --refresh-key 1E42B367
7442
is thus often helpful. Note that the actual output depends on the
7443
backend and may change from release to release.
7447
File: gnupg.info, Node: Common Problems, Next: Architecture Details, Prev: Debugging Hints, Up: Debugging
7449
10.3 Commonly Seen Problems
7450
===========================
7452
* Error code `Not supported' from Dirmngr
7454
Most likely the option `enable-ocsp' is active for gpgsm but
7455
Dirmngr's OCSP feature has not been enabled using `allow-ocsp' in
7458
* The Curses based Pinentry does not work
7460
The far most common reason for this is that the environment
7461
variable `GPG_TTY' has not been set correctly. Make sure that it
7462
has been set to a real tty devce and not just to `/dev/tty'; i.e.
7463
`GPG_TTY=tty' is plainly wrong; what you want is `GPG_TTY=`tty`'
7464
-- note the back ticks. Also make sure that this environment
7465
variable gets exported, that is you should follow up the setting
7466
with an `export GPG_TTY' (assuming a Bourne style shell). Even for
7467
GUI based Pinentries; you should have set `GPG_TTY'. See the
7468
section on installing the `gpg-agent' on how to do it.
7470
* SSH hangs while a popping up pinentry was expected
7472
SSH has no way to tell the gpg-agent what terminal or X display it
7473
is running on. So when remotely logging into a box where a
7474
gpg-agent with SSH support is running, the pinentry will get
7475
popped up on whatever display the gpg-agent has been started. To
7476
solve this problem you may issue the command
7478
echo UPDATESTARTUPTTY | gpg-connect-agent
7480
and the next pinentry will pop up on your display or screen.
7481
However, you need to kill the running pinentry first because only
7482
one pinentry may be running at once. If you plan to use ssh on a
7483
new display you should issue the above command before invoking ssh
7484
or any other service making use of ssh.
7486
* Exporting a secret key without a certificate
7488
I may happen that you have created a certificate request using
7489
`gpgsm' but not yet received and imported the certificate from the
7490
CA. However, you want to export the secret key to another machine
7491
right now to import the certificate over there then. You can do
7492
this with a little trick but it requires that you know the
7493
approximate time you created the signing request. By running the
7496
ls -ltr ~/.gnupg/private-keys-v1.d
7498
you get a listing of all private keys under control of `gpg-agent'.
7499
Pick the key which best matches the creation time and run the
7502
/usr/local/libexec/gpg-protect-tool --p12-export ~/.gnupg/private-keys-v1.d/FOO >FOO.p12
7504
(Please adjust the path to `gpg-protect-tool' to the appropriate
7505
location). FOO is the name of the key file you picked (it should
7506
have the suffix `.key'). A Pinentry box will pop up and ask you
7507
for the current passphrase of the key and a new passphrase to
7508
protect it in the pkcs#12 file.
7510
To import the created file on the machine you use this command:
7512
/usr/local/libexec/gpg-protect-tool --p12-import --store FOO.p12
7514
You will be asked for the pkcs#12 passphrase and a new passphrase
7515
to protect the imported private key at its new location.
7517
Note that there is no easy way to match existing certificates with
7518
stored private keys because some private keys are used for Secure
7519
Shell or other purposes and don't have a corresponding certificate.
7521
* A root certificate does not verify
7523
A common problem is that the root certificate misses the required
7524
basicConstraints attribute and thus `gpgsm' rejects this
7525
certificate. An error message indicating "no value" is a sign for
7526
such a certificate. You may use the `relax' flag in
7527
`trustlist.txt' to accept the certificate anyway. Note that the
7528
fingerprint and this flag may only be added manually to
7531
* Error message: "digest algorithm N has not been enabled"
7533
The signature is broken. You may try the option
7534
`--extra-digest-algo SHA256' to workaround the problem. The
7535
number N is the internal algorithm identifier; for example 8
7538
* The Windows version does not work under Wine
7540
When running the W32 version of `gpg' under Wine you may get an
7541
error messages like:
7543
gpg: fatal: WriteConsole failed: Access denied
7545
The solution is to use the command `wineconsole'.
7547
Some operations like gen-key really want to talk to the console
7548
directly for increased security (for example to prevent the
7549
passphrase from appearing on the screen). So, you should use
7550
`wineconsole' instead of `wine', which will launch a windows
7551
console that implements those additional features.
7553
* Why does GPG's -search-key list weird keys?
7555
For performance reasons the keyservers do not check the keys the
7556
same way `gpg' does. It may happen that the listing of keys
7557
available on the keyservers shows keys with wrong user IDs or with
7558
user Ids from other keys. If you try to import this key, the bad
7559
keys or bad user ids won't get imported, though. This is a bit
7560
unfortunate but we can't do anything about it without actually
7561
downloading the keys.
7565
File: gnupg.info, Node: Architecture Details, Prev: Common Problems, Up: Debugging
7567
10.4 How the whole thing works internally.
7568
==========================================
7572
* GnuPG-1 and GnuPG-2:: Relationship between the two branches.
7575
File: gnupg.info, Node: GnuPG-1 and GnuPG-2, Up: Architecture Details
7577
10.4.1 Relationship between the two branches.
7578
---------------------------------------------
7580
Here is a little picture showing how the components work together: