Page MenuHome GnuPG

No OneTemporary

This file is larger than 256 KB, so syntax highlighting was skipped.
diff --git a/doc/DETAILS b/doc/DETAILS
index 8ead6a8f5..3c089b278 100644
--- a/doc/DETAILS
+++ b/doc/DETAILS
@@ -1,1543 +1,1545 @@
# doc/DETAILS -*- org -*-
#+TITLE: GnuPG Details
# Globally disable superscripts and subscripts:
#+OPTIONS: ^:{}
#
# Note: This file uses org-mode; it should be easy to read as plain
# text but be aware of some markup peculiarities: Verbatim code is
# enclosed in #+begin-example, #+end-example blocks or marked by a
# colon as the first non-white-space character, words bracketed with
# equal signs indicate a monospace font, and the usual /italics/,
# *bold*, and _underline_ conventions are recognized.
This is the DETAILS file for GnuPG which specifies some internals and
parts of the external API for GPG and GPGSM.
* Format of the colon listings
The format is a based on colon separated record, each recods starts
with a tag string and extends to the end of the line. Here is an
example:
#+begin_example
$ gpg --with-colons --list-keys \
--with-fingerprint --with-fingerprint wk@gnupg.org
pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC:
fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013:
uid:f::::::::Werner Koch <wk@g10code.com>:
uid:f::::::::Werner Koch <wk@gnupg.org>:
sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e:
fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1:
sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc:
fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4:
#+end_example
Note that new version of GnuPG or the use of certain options may add
new fields to the output. Parsers should not assume a limit on the
number of fields per line. Some fields are not yet used or only used
with certain record types; parsers should ignore fields they are not
aware of. New versions of GnuPG or the use of certain options may add
new types of records as well. Parsers should ignore any record whose
type they do not recognize for forward-compatibility.
The double =--with-fingerprint= prints the fingerprint for the subkeys
too. Old versions of gpg used a slightly different format and required
the use of the option =--fixed-list-mode= to conform to the format
described here.
** Description of the fields
*** Field 1 - Type of record
- pub :: Public key
- crt :: X.509 certificate
- crs :: X.509 certificate and private key available
- sub :: Subkey (secondary key)
- sec :: Secret key
- ssb :: Secret subkey (secondary key)
- uid :: User id
- uat :: User attribute (same as user id except for field 10).
- sig :: Signature
- rev :: Revocation signature
- fpr :: Fingerprint (fingerprint is in field 10)
- pkd :: Public key data [*]
- grp :: Keygrip
- rvk :: Revocation key
- tfs :: TOFU statistics [*]
- tru :: Trust database information [*]
- spk :: Signature subpacket [*]
- cfg :: Configuration data [*]
Records marked with an asterisk are described at [[*Special%20field%20formats][*Special fields]].
*** Field 2 - Validity
This is a letter describing the computed validity of a key.
Currently this is a single letter, but be prepared that additional
information may follow in some future versions. Note that GnuPG <
2.1 does not set this field for secret key listings.
- o :: Unknown (this key is new to the system)
- i :: The key is invalid (e.g. due to a missing self-signature)
- d :: The key has been disabled
(deprecated - use the 'D' in field 12 instead)
- r :: The key has been revoked
- e :: The key has expired
- - :: Unknown validity (i.e. no value assigned)
- q :: Undefined validity. '-' and 'q' may safely be treated as
the same value for most purposes
- n :: The key is not valid
- m :: The key is marginal valid.
- f :: The key is fully valid
- u :: The key is ultimately valid. This often means that the
secret key is available, but any key may be marked as
ultimately valid.
- w :: The key has a well known private part.
- s :: The key has special validity. This means that it might be
self-signed and expected to be used in the STEED system.
If the validity information is given for a UID or UAT record, it
describes the validity calculated based on this user ID. If given
for a key record it describes the validity taken from the best
rated user ID.
For X.509 certificates a 'u' is used for a trusted root
certificate (i.e. for the trust anchor) and an 'f' for all other
valid certificates.
*** Field 3 - Key length
The length of key in bits.
*** Field 4 - Public key algorithm
The values here are those from the OpenPGP specs or if they are
greather than 255 the algorithm ids as used by Libgcrypt.
*** Field 5 - KeyID
This is the 64 bit keyid as specified by OpenPGP and the last 64
bit of the SHA-1 fingerprint of an X.509 certifciate.
*** Field 6 - Creation date
The creation date of the key is given in UTC. For UID and UAT
records, this is used for the self-signature date. Note that the
date is usually printed in seconds since epoch, however, we are
migrating to an ISO 8601 format (e.g. "19660205T091500"). This is
currently only relevant for X.509. A simple way to detect the new
format is to scan for the 'T'. Note that old versions of gpg
without using the =--fixed-list-mode= option used a "yyyy-mm-tt"
format.
*** Field 7 - Expiration date
Key or UID/UAT expiration date or empty if it does not expire.
*** Field 8 - Certificate S/N, UID hash, trust signature info
Used for serial number in crt records. For UID and UAT records,
this is a hash of the user ID contents used to represent that
exact user ID. For trust signatures, this is the trust depth
separated by the trust value by a space.
*** Field 9 - Ownertrust
This is only used on primary keys. This is a single letter, but
be prepared that additional information may follow in future
versions. For trust signatures with a regular expression, this is
the regular expression value, quoted as in field 10.
*** Field 10 - User-ID
The value is quoted like a C string to avoid control characters
(the colon is quoted =\x3a=). For a "pub" record this field is
not used on --fixed-list-mode. A UAT record puts the attribute
subpacket count here, a space, and then the total attribute
subpacket size. In gpgsm the issuer name comes here. A FPR
record stores the fingerprint here. The fingerprint of a
revocation key is stored here.
*** Field 11 - Signature class
Signature class as per RFC-4880. This is a 2 digit hexnumber
followed by either the letter 'x' for an exportable signature or
the letter 'l' for a local-only signature. The class byte of an
revocation key is also given here, 'x' and 'l' is used the same
way. This field if not used for X.509.
*** Field 12 - Key capabilities
The defined capabilities are:
- e :: Encrypt
- s :: Sign
- c :: Certify
- a :: Authentication
- ? :: Unknown capability
A key may have any combination of them in any order. In addition
to these letters, the primary key has uppercase versions of the
letters to denote the _usable_ capabilities of the entire key, and
a potential letter 'D' to indicate a disabled key.
*** Field 13 - Issuer certificate fingerprint or other info
Used in FPR records for S/MIME keys to store the fingerprint of
the issuer certificate. This is useful to build the certificate
path based on certificates stored in the local key database it is
only filled if the issuer certificate is available. The root has
been reached if this is the same string as the fingerprint. The
advantage of using this value is that it is guaranteed to have
been built by the same lookup algorithm as gpgsm uses.
For "uid" records this field lists the preferences in the same way
gpg's --edit-key menu does.
For "sig" records, this is the fingerprint of the key that issued
the signature. Note that this is only filled in if the signature
verified correctly. Note also that for various technical reasons,
this fingerprint is only available if --no-sig-cache is used.
*** Field 14 - Flag field
Flag field used in the --edit menu output
*** Field 15 - S/N of a token
Used in sec/ssb to print the serial number of a token (internal
protect mode 1002) or a '#' if that key is a simple stub (internal
protect mode 1001). If the option --with-secret is used and a
secret key is available for the public key, a '+' indicates this.
*** Field 16 - Hash algorithm
For sig records, this is the used hash algorithm. For example:
2 = SHA-1, 8 = SHA-256.
*** Field 17 - Curve name
For pub, sub, sec, and ssb records this field is used for the ECC
curve name.
*** Field 18 - Compliance flags
Space separated list of asserted compliance modes and
screening result for this key.
Valid values are:
- 8 :: The key is compliant with RFC4880bis
- 23 :: The key is compliant with compliance mode "de-vs".
- 6001 :: Screening hit on the ROCA vulnerability.
*** Field 19 - Last update
The timestamp of the last update of a key or user ID. The update
time of a key is defined a lookup of the key via its unique
identifier (fingerprint); the field is empty if not known. The
update time of a user ID is defined by a lookup of the key using a
trusted mapping from mail address to key.
*** Field 20 - Origin
The origin of the key or the user ID. This is an integer
optionally followed by a space and an URL. This goes along with
the previous field. The URL is quoted in C style.
** Special fields
*** PKD - Public key data
If field 1 has the tag "pkd", a listing looks like this:
#+begin_example
pkd:0:1024:B665B1435F4C2 .... FF26ABB:
! ! !-- the value
! !------ for information number of bits in the value
!--------- index (eg. DSA goes from 0 to 3: p,q,g,y)
#+end_example
*** TFS - TOFU statistics
This field may follows a UID record to convey information about
the TOFU database. The information is similar to a TOFU_STATS
status line.
- Field 2 :: tfs record version (must be 1)
- Field 3 :: validity - A number with validity code.
- Field 4 :: signcount - The number of signatures seen.
- Field 5 :: encrcount - The number of encryptions done.
- Field 6 :: policy - A string with the policy
- Field 7 :: signture-first-seen - a timestamp or 0 if not known.
- Field 8 :: signature-most-recent-seen - a timestamp or 0 if not known.
- Field 9 :: encryption-first-done - a timestamp or 0 if not known.
- Field 10 :: encryption-most-recent-done - a timestamp or 0 if not known.
*** TRU - Trust database information
Example for a "tru" trust base record:
#+begin_example
tru:o:0:1166697654:1:3:1:5
#+end_example
- Field 2 :: Reason for staleness of trust. If this field is
empty, then the trustdb is not stale. This field may
have multiple flags in it:
- o :: Trustdb is old
- t :: Trustdb was built with a different trust model
than the one we are using now.
- Field 3 :: Trust model
- 0 :: Classic trust model, as used in PGP 2.x.
- 1 :: PGP trust model, as used in PGP 6 and later.
This is the same as the classic trust model,
except for the addition of trust signatures.
GnuPG before version 1.4 used the classic trust model
by default. GnuPG 1.4 and later uses the PGP trust
model by default.
- Field 4 :: Date trustdb was created in seconds since Epoch.
- Field 5 :: Date trustdb will expire in seconds since Epoch.
- Field 6 :: Number of marginally trusted users to introduce a new
key signer (gpg's option --marginals-needed).
- Field 7 :: Number of completely trusted users to introduce a new
key signer. (gpg's option --completes-needed)
- Field 8 :: Maximum depth of a certification chain. (gpg's option
--max-cert-depth)
*** SPK - Signature subpacket records
- Field 2 :: Subpacket number as per RFC-4880 and later.
- Field 3 :: Flags in hex. Currently the only two bits assigned
are 1, to indicate that the subpacket came from the
hashed part of the signature, and 2, to indicate the
subpacket was marked critical.
- Field 4 :: Length of the subpacket. Note that this is the
length of the subpacket, and not the length of field
5 below. Due to the need for %-encoding, the length
of field 5 may be up to 3x this value.
- Field 5 :: The subpacket data. Printable ASCII is shown as
ASCII, but other values are rendered as %XX where XX
is the hex value for the byte.
*** CFG - Configuration data
--list-config outputs information about the GnuPG configuration
for the benefit of frontends or other programs that call GnuPG.
There are several list-config items, all colon delimited like the
rest of the --with-colons output. The first field is always "cfg"
to indicate configuration information. The second field is one of
(with examples):
- version :: The third field contains the version of GnuPG.
: cfg:version:1.3.5
- pubkey :: The third field contains the public key algorithms
this version of GnuPG supports, separated by
semicolons. The algorithm numbers are as specified in
RFC-4880. Note that in contrast to the --status-fd
interface these are _not_ the Libgcrypt identifiers.
Using =pubkeyname= prints names instead of numbers.
: cfg:pubkey:1;2;3;16;17
- cipher :: The third field contains the symmetric ciphers this
version of GnuPG supports, separated by semicolons.
The cipher numbers are as specified in RFC-4880.
Using =ciphername= prints names instead of numbers.
: cfg:cipher:2;3;4;7;8;9;10
- digest :: The third field contains the digest (hash) algorithms
this version of GnuPG supports, separated by
semicolons. The digest numbers are as specified in
RFC-4880. Using =digestname= prints names instead of
numbers.
: cfg:digest:1;2;3;8;9;10
- compress :: The third field contains the compression algorithms
this version of GnuPG supports, separated by
semicolons. The algorithm numbers are as specified
in RFC-4880.
: cfg:compress:0;1;2;3
- group :: The third field contains the name of the group, and the
fourth field contains the values that the group expands
to, separated by semicolons.
For example, a group of:
: group mynames = paige 0x12345678 joe patti
would result in:
: cfg:group:mynames:patti;joe;0x12345678;paige
- curve :: The third field contains the curve names this version
of GnuPG supports, separated by semicolons. Using
=curveoid= prints OIDs instead of numbers.
: cfg:curve:ed25519;nistp256;nistp384;nistp521
* Format of the --status-fd output
Every line is prefixed with "[GNUPG:] ", followed by a keyword with
the type of the status line and some arguments depending on the type
(maybe none); an application should always be willing to ignore
unknown keywords that may be emitted by future versions of GnuPG.
Also, new versions of GnuPG may add arguments to existing keywords.
Any additional arguments should be ignored for forward-compatibility.
** General status codes
*** NEWSIG [<signers_uid>]
Is issued right before a signature verification starts. This is
useful to define a context for parsing ERROR status messages.
- arguments are currently defined. If SIGNERS_UID is given and is
- not "-" this is the percent escape value of the OpenPGP Signer's
- User ID signature sub-packet.
+ If SIGNERS_UID is given and is not "-" this is the percent-escaped
+ value of the OpenPGP Signer's User ID signature sub-packet.
*** GOODSIG <long_keyid_or_fpr> <username>
The signature with the keyid is good. For each signature only one
of the codes GOODSIG, BADSIG, EXPSIG, EXPKEYSIG, REVKEYSIG or
ERRSIG will be emitted. In the past they were used as a marker
for a new signature; new code should use the NEWSIG status
instead. The username is the primary one encoded in UTF-8 and %XX
escaped. The fingerprint may be used instead of the long keyid if
it is available. This is the case with CMS and might eventually
also be available for OpenPGP.
*** EXPSIG <long_keyid_or_fpr> <username>
The signature with the keyid is good, but the signature is
expired. The username is the primary one encoded in UTF-8 and %XX
escaped. The fingerprint may be used instead of the long keyid if
it is available. This is the case with CMS and might eventually
also be available for OpenPGP.
*** EXPKEYSIG <long_keyid_or_fpr> <username>
The signature with the keyid is good, but the signature was made
by an expired key. The username is the primary one encoded in
UTF-8 and %XX escaped. The fingerprint may be used instead of the
long keyid if it is available. This is the case with CMS and
might eventually also be available for OpenPGP.
*** REVKEYSIG <long_keyid_or_fpr> <username>
The signature with the keyid is good, but the signature was made
by a revoked key. The username is the primary one encoded in UTF-8
and %XX escaped. The fingerprint may be used instead of the long
keyid if it is available. This is the case with CMS and might
eventually also beñ available for OpenPGP.
*** BADSIG <long_keyid_or_fpr> <username>
The signature with the keyid has not been verified okay. The
username is the primary one encoded in UTF-8 and %XX escaped. The
fingerprint may be used instead of the long keyid if it is
available. This is the case with CMS and might eventually also be
available for OpenPGP.
*** ERRSIG <keyid> <pkalgo> <hashalgo> <sig_class> <time> <rc>
It was not possible to check the signature. This may be caused by
a missing public key or an unsupported algorithm. A RC of 4
indicates unknown algorithm, a 9 indicates a missing public
key. The other fields give more information about this signature.
sig_class is a 2 byte hex-value. The fingerprint may be used
instead of the keyid if it is available. This is the case with
gpgsm and might eventually also be available for OpenPGP.
Note, that TIME may either be the number of seconds since Epoch or
an ISO 8601 string. The latter can be detected by the presence of
the letter 'T'.
*** VALIDSIG <args>
The args are:
- <fingerprint_in_hex>
- <sig_creation_date>
- <sig-timestamp>
- <expire-timestamp>
- <sig-version>
- <reserved>
- <pubkey-algo>
- <hash-algo>
- <sig-class>
- [ <primary-key-fpr> ]
This status indicates that the signature is cryptographically
valid. This is similar to GOODSIG, EXPSIG, EXPKEYSIG, or REVKEYSIG
(depending on the date and the state of the signature and signing
key) but has the fingerprint as the argument. Multiple status
lines (VALIDSIG and the other appropriate *SIG status) are emitted
for a valid signature. All arguments here are on one long line.
sig-timestamp is the signature creation time in seconds after the
epoch. expire-timestamp is the signature expiration time in
seconds after the epoch (zero means "does not
expire"). sig-version, pubkey-algo, hash-algo, and sig-class (a
2-byte hex value) are all straight from the signature packet.
PRIMARY-KEY-FPR is the fingerprint of the primary key or identical
to the first argument. This is useful to get back to the primary
key without running gpg again for this purpose.
The primary-key-fpr parameter is used for OpenPGP and not
available for CMS signatures. The sig-version as well as the sig
class is not defined for CMS and currently set to 0 and 00.
Note, that *-TIMESTAMP may either be a number of seconds since
Epoch or an ISO 8601 string which can be detected by the presence
of the letter 'T'.
*** SIG_ID <radix64_string> <sig_creation_date> <sig-timestamp>
This is emitted only for signatures of class 0 or 1 which have
been verified okay. The string is a signature id and may be used
in applications to detect replay attacks of signed messages. Note
that only DLP algorithms give unique ids - others may yield
duplicated ones when they have been created in the same second.
Note, that SIG-TIMESTAMP may either be a number of seconds since
Epoch or an ISO 8601 string which can be detected by the presence
of the letter 'T'.
*** ENC_TO <long_keyid> <keytype> <keylength>
The message is encrypted to this LONG_KEYID. KEYTYPE is the
numerical value of the public key algorithm or 0 if it is not
known, KEYLENGTH is the length of the key or 0 if it is not known
(which is currently always the case). Gpg prints this line
always; Gpgsm only if it knows the certificate.
*** BEGIN_DECRYPTION
Mark the start of the actual decryption process. This is also
emitted when in --list-only mode.
*** END_DECRYPTION
Mark the end of the actual decryption process. This are also
emitted when in --list-only mode.
*** DECRYPTION_KEY <fpr> <fpr2> <otrust>
This line is emitted when a public key decryption succeeded in
providing a session key. <fpr> is the hexified fingerprint of the
actual key used for descryption. <fpr2> is the fingerprint of the
primary key. <otrust> is the letter with the ownertrust; this is
in general a 'u' which stands for ultimately trusted.
*** DECRYPTION_INFO <mdc_method> <sym_algo>
Print information about the symmetric encryption algorithm and the
MDC method. This will be emitted even if the decryption fails.
*** DECRYPTION_FAILED
The symmetric decryption failed - one reason could be a wrong
passphrase for a symmetrical encrypted message.
*** DECRYPTION_OKAY
The decryption process succeeded. This means, that either the
correct secret key has been used or the correct passphrase for a
symmetric encrypted message was given. The program itself may
return an errorcode because it may not be possible to verify a
signature for some reasons.
*** SESSION_KEY <algo>:<hexdigits>
The session key used to decrypt the message. This message will
only be emitted if the option --show-session-key is used. The
format is suitable to be passed as value for the option
--override-session-key. It is not an indication that the
decryption will or has succeeded.
*** BEGIN_ENCRYPTION <mdc_method> <sym_algo>
Mark the start of the actual encryption process.
*** END_ENCRYPTION
Mark the end of the actual encryption process.
*** FILE_START <what> <filename>
Start processing a file <filename>. <what> indicates the performed
operation:
- 1 :: verify
- 2 :: encrypt
- 3 :: decrypt
*** FILE_DONE
Marks the end of a file processing which has been started
by FILE_START.
*** BEGIN_SIGNING
Mark the start of the actual signing process. This may be used as
an indication that all requested secret keys are ready for use.
*** ALREADY_SIGNED <long-keyid>
Warning: This is experimental and might be removed at any time.
*** SIG_CREATED <type> <pk_algo> <hash_algo> <class> <timestamp> <keyfpr>
A signature has been created using these parameters.
Values for type <type> are:
- D :: detached
- C :: cleartext
- S :: standard
(only the first character should be checked)
<class> are 2 hex digits with the OpenPGP signature class.
Note, that TIMESTAMP may either be a number of seconds since Epoch
or an ISO 8601 string which can be detected by the presence of the
letter 'T'.
*** NOTATION_
There are actually three related status codes to convey notation
data:
- NOTATION_NAME <name>
- NOTATION_FLAGS <critical> <human_readable>
- NOTATION_DATA <string>
<name> and <string> are %XX escaped. The data may be split among
several NOTATION_DATA lines. NOTATION_FLAGS is emitted after
NOTATION_NAME and gives the critical and human readable flags;
the flag values are either 0 or 1.
*** POLICY_URL <string>
Note that URL in <string> is %XX escaped.
*** PLAINTEXT <format> <timestamp> <filename>
This indicates the format of the plaintext that is about to be
written. The format is a 1 byte hex code that shows the format of
the plaintext: 62 ('b') is binary data, 74 ('t') is text data with
no character set specified, and 75 ('u') is text data encoded in
the UTF-8 character set. The timestamp is in seconds since the
epoch. If a filename is available it gets printed as the third
argument, percent-escaped as usual.
*** PLAINTEXT_LENGTH <length>
This indicates the length of the plaintext that is about to be
written. Note that if the plaintext packet has partial length
encoding it is not possible to know the length ahead of time. In
that case, this status tag does not appear.
*** ATTRIBUTE <arguments>
The list or arguments are:
- <fpr>
- <octets>
- <type>
- <index>
- <count>
- <timestamp>
- <expiredate>
- <flags>
This is one long line issued for each attribute subpacket when an
attribute packet is seen during key listing. <fpr> is the
fingerprint of the key. <octets> is the length of the attribute
subpacket. <type> is the attribute type (e.g. 1 for an image).
<index> and <count> indicate that this is the N-th indexed
subpacket of count total subpackets in this attribute packet.
<timestamp> and <expiredate> are from the self-signature on the
attribute packet. If the attribute packet does not have a valid
self-signature, then the timestamp is 0. <flags> are a bitwise OR
of:
- 0x01 :: this attribute packet is a primary uid
- 0x02 :: this attribute packet is revoked
- 0x04 :: this attribute packet is expired
*** SIG_SUBPACKET <type> <flags> <len> <data>
This indicates that a signature subpacket was seen. The format is
the same as the "spk" record above.
*** ENCRYPTION_COMPLIANCE_MODE <flags>
Indicates that the current encryption operation was in compliance
with the given set of modes for all recipients. "flags" is a
space separated list of numerical flags, see "Field 18 -
Compliance flags" above.
*** DECRYPTION_COMPLIANCE_MODE <flags>
Indicates that the current decryption operation is in compliance
with the given set of modes. "flags" is a space separated list of
numerical flags, see "Field 18 - Compliance flags" above.
*** VERIFICATION_COMPLIANCE_MODE <flags>
Indicates that the current signature verification operation is in
compliance with the given set of modes. "flags" is a space
separated list of numerical flags, see "Field 18 - Compliance
flags" above.
** Key related
*** INV_RECP, INV_SGNR
The two similar status codes:
- INV_RECP <reason> <requested_recipient>
- INV_SGNR <reason> <requested_sender>
are issued for each unusable recipient/sender. The reasons codes
currently in use are:
- 0 :: No specific reason given
- 1 :: Not Found
- 2 :: Ambigious specification
- 3 :: Wrong key usage
- 4 :: Key revoked
- 5 :: Key expired
- 6 :: No CRL known
- 7 :: CRL too old
- 8 :: Policy mismatch
- 9 :: Not a secret key
- 10 :: Key not trusted
- 11 :: Missing certificate
- 12 :: Missing issuer certificate
- 13 :: Key disabled
- 14 :: Syntax error in specification
If no specific reason was given a previously emitted status code
KEY_CONSIDERED may be used to analyzed the problem.
Note that for historical reasons the INV_RECP status is also used
for gpgsm's SIGNER command where it relates to signer's of course.
Newer GnuPG versions are using INV_SGNR; applications should
ignore the INV_RECP during the sender's command processing once
they have seen an INV_SGNR. Different codes are used so that they
can be distinguish while doing an encrypt+sign operation.
*** NO_RECP <reserved>
Issued if no recipients are usable.
*** NO_SGNR <reserved>
Issued if no senders are usable.
*** KEY_CONSIDERED <fpr> <flags>
Issued to explian the lookup of a key. FPR is the hexified
fingerprint of the primary key. The bit values for FLAGS are:
- 1 :: The key has not been selected.
- 2 :: All subkeys of the key are expired or have been revoked.
*** KEYEXPIRED <expire-timestamp>
The key has expired. expire-timestamp is the expiration time in
seconds since Epoch. This status line is not very useful because
it will also be emitted for expired subkeys even if this subkey is
not used. To check whether a key used to sign a message has
expired, the EXPKEYSIG status line is to be used.
Note, that the TIMESTAMP may either be a number of seconds since
Epoch or an ISO 8601 string which can be detected by the presence
of the letter 'T'.
*** KEYREVOKED
The used key has been revoked by its owner. No arguments yet.
*** NO_PUBKEY <long keyid>
The public key is not available
*** NO_SECKEY <long keyid>
The secret key is not available
*** KEY_CREATED <type> <fingerprint> [<handle>]
A key has been created. Values for <type> are:
- B :: primary and subkey
- P :: primary
- S :: subkey
The fingerprint is one of the primary key for type B and P and the
one of the subkey for S. Handle is an arbitrary non-whitespace
string used to match key parameters from batch key creation run.
*** KEY_NOT_CREATED [<handle>]
The key from batch run has not been created due to errors.
*** TRUST_
These are several similar status codes:
- TRUST_UNDEFINED <error_token>
- TRUST_NEVER <error_token>
- TRUST_MARGINAL [0 [<validation_model>]]
- TRUST_FULLY [0 [<validation_model>]]
- TRUST_ULTIMATE [0 [<validation_model>]]
For good signatures one of these status lines are emitted to
indicate the validity of the key used to create the signature.
The error token values are currently only emitted by gpgsm.
VALIDATION_MODEL describes the algorithm used to check the
validity of the key. The defaults are the standard Web of Trust
model for gpg and the standard X.509 model for gpgsm. The
defined values are
- pgp :: The standard PGP WoT.
- shell :: The standard X.509 model.
- chain :: The chain model.
- steed :: The STEED model.
- tofu :: The TOFU model
Note that the term =TRUST_= in the status names is used for
historic reasons; we now speak of validity.
*** TOFU_USER <fingerprint_in_hex> <mbox>
This status identifies the key and the userid for all following
Tofu information. The fingerprint is the fingerprint of the
primary key and the mbox is in general the addr-spec part of the
userid encoded in UTF-8 and percent escaped. The fingerprint is
identical for all TOFU_USER lines up to a NEWSIG line.
*** TOFU_STATS <MANY_ARGS>
Statistics for the current user id.
The <MANY_ARGS> are the usual space delimited arguments. Here we
have too many of them to fit on one printed line and thus they are
given on 3 printed lines:
: <summary> <sign-count> <encryption-count>
: [<policy> [<tm1> <tm2> <tm3> <tm4>
: [<validity> [<sign-days> <encrypt-days>]]]]
Values for SUMMARY are:
- 0 :: attention, an interaction with the user is required (conflict)
- 1 :: key with no verification/encryption history
- 2 :: key with little history
- 3 :: key with enough history for basic trust
- 4 :: key with a lot of history
Values for POLICY are:
- none :: No Policy set
- auto :: Policy is "auto"
- good :: Policy is "good"
- bad :: Policy is "bad"
- ask :: Policy is "ask"
- unknown :: Policy is "unknown" (TOFU information does not
contribute to the key's validity)
TM1 is the time the first message was verified. TM2 is the time
the most recent message was verified. TM3 is the time the first
message was encrypted. TM4 is the most recent encryption. All may
either be seconds since Epoch or an ISO time string
(yyyymmddThhmmss).
VALIDITY is the same as SUMMARY with the exception that VALIDITY
doesn't reflect whether the key needs attention. That is it never
takes on value 0. Instead, if there is a conflict, VALIDITY still
reflects the key's validity (values: 1-4).
SUMMARY values use the euclidean distance (m = sqrt(a² + b²)) rather
then the sum of the magnitudes (m = a + b) to ensure a balance between
verified signatures and encrypted messages.
Values are calculated based on the number of days where a key was used
for verifying a signature or to encrypt to it.
The ranges for the values are:
- 1 :: signature_days + encryption_days == 0
- 2 :: 1 <= sqrt(signature_days² + encryption_days²) < 8
- 3 :: 8 <= sqrt(signature_days² + encryption_days²) < 42
- 4 :: sqrt(signature_days² + encryption_days²) >= 42
SIGN-COUNT and ENCRYPTION-COUNT are the number of messages that we
have seen that have been signed by this key / encryption to this
key.
SIGN-DAYS and ENCRYPTION-DAYS are similar, but the number of days
(in UTC) on which we have seen messages signed by this key /
encrypted to this key.
*** TOFU_STATS_SHORT <long_string>
Information about the TOFU binding for the signature.
Example: "15 signatures verified. 10 messages encrypted"
*** TOFU_STATS_LONG <long_string>
Information about the TOFU binding for the signature in verbose
format. The LONG_STRING is percent escaped.
Example: 'Verified 9 messages signed by "Werner Koch
(dist sig)" in the past 3 minutes, 40 seconds. The most
recent message was verified 4 seconds ago.'
*** PKA_TRUST_
This is one of:
- PKA_TRUST_GOOD <addr-spec>
- PKA_TRUST_BAD <addr-spec>
Depending on the outcome of the PKA check one of the above status
codes is emitted in addition to a =TRUST_*= status.
** Remote control
*** GET_BOOL, GET_LINE, GET_HIDDEN, GOT_IT
These status line are used with --command-fd for interactive
control of the process.
*** USERID_HINT <long main keyid> <string>
Give a hint about the user ID for a certain keyID.
*** NEED_PASSPHRASE <long keyid> <long main keyid> <keytype> <keylength>
Issued whenever a passphrase is needed. KEYTYPE is the numerical
value of the public key algorithm or 0 if this is not applicable,
KEYLENGTH is the length of the key or 0 if it is not known (this
is currently always the case).
*** NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash>
Issued whenever a passphrase for symmetric encryption is needed.
*** NEED_PASSPHRASE_PIN <card_type> <chvno> [<serialno>]
Issued whenever a PIN is requested to unlock a card.
*** MISSING_PASSPHRASE
No passphrase was supplied. An application which encounters this
message may want to stop parsing immediately because the next
message will probably be a BAD_PASSPHRASE. However, if the
application is a wrapper around the key edit menu functionality it
might not make sense to stop parsing but simply ignoring the
following BAD_PASSPHRASE.
*** BAD_PASSPHRASE <long keyid>
The supplied passphrase was wrong or not given. In the latter
case you may have seen a MISSING_PASSPHRASE.
*** GOOD_PASSPHRASE
The supplied passphrase was good and the secret key material
is therefore usable.
** Import/Export
*** IMPORT_CHECK <long keyid> <fingerprint> <user ID>
This status is emitted in interactive mode right before
the "import.okay" prompt.
*** IMPORTED <long keyid> <username>
The keyid and name of the signature just imported
*** IMPORT_OK <reason> [<fingerprint>]
The key with the primary key's FINGERPRINT has been imported.
REASON flags are:
- 0 :: Not actually changed
- 1 :: Entirely new key.
- 2 :: New user IDs
- 4 :: New signatures
- 8 :: New subkeys
- 16 :: Contains private key.
The flags may be ORed.
*** IMPORT_PROBLEM <reason> [<fingerprint>]
Issued for each import failure. Reason codes are:
- 0 :: No specific reason given.
- 1 :: Invalid Certificate.
- 2 :: Issuer Certificate missing.
- 3 :: Certificate Chain too long.
- 4 :: Error storing certificate.
*** IMPORT_RES <args>
Final statistics on import process (this is one long line). The
args are a list of unsigned numbers separated by white space:
- <count>
- <no_user_id>
- <imported>
- always 0 (formerly used for the number of RSA keys)
- <unchanged>
- <n_uids>
- <n_subk>
- <n_sigs>
- <n_revoc>
- <sec_read>
- <sec_imported>
- <sec_dups>
- <skipped_new_keys>
- <not_imported>
- <skipped_v3_keys>
*** EXPORTED <fingerprint>
The key with <fingerprint> has been exported. The fingerprint is
the fingerprint of the primary key even if the primary key has
been replaced by a stub key during secret key export.
*** EXPORT_RES <args>
Final statistics on export process (this is one long line). The
args are a list of unsigned numbers separated by white space:
- <count>
- <secret_count>
- <exported>
** Smartcard related
*** CARDCTRL <what> [<serialno>]
This is used to control smartcard operations. Defined values for
WHAT are:
- 1 :: Request insertion of a card. Serialnumber may be given
to request a specific card. Used by gpg 1.4 w/o
scdaemon
- 2 :: Request removal of a card. Used by gpg 1.4 w/o scdaemon.
- 3 :: Card with serialnumber detected
- 4 :: No card available
- 5 :: No card reader available
- 6 :: No card support available
- 7 :: Card is in termination state
*** SC_OP_FAILURE [<code>]
An operation on a smartcard definitely failed. Currently there is
no indication of the actual error code, but application should be
prepared to later accept more arguments. Defined values for
<code> are:
- 0 :: unspecified error (identically to a missing CODE)
- 1 :: canceled
- 2 :: bad PIN
*** SC_OP_SUCCESS
A smart card operaion succeeded. This status is only printed for
certain operation and is mostly useful to check whether a PIN
change really worked.
** Miscellaneous status codes
*** NODATA <what>
No data has been found. Codes for WHAT are:
- 1 :: No armored data.
- 2 :: Expected a packet but did not found one.
- 3 :: Invalid packet found, this may indicate a non OpenPGP
message.
- 4 :: Signature expected but not found
You may see more than one of these status lines.
*** UNEXPECTED <what>
Unexpected data has been encountered. Codes for WHAT are:
- 0 :: Not further specified
- 1 :: Corrupted message structure
*** TRUNCATED <maxno>
The output was truncated to MAXNO items. This status code is
issued for certain external requests.
*** ERROR <error location> <error code> [<more>]
This is a generic error status message, it might be followed by
error location specific data. <error code> and <error_location>
should not contain spaces. The error code is a either a string
commencing with a letter or such a string prefixed with a
numerical error code and an underscore; e.g.: "151011327_EOF".
*** WARNING <location> <error code> [<text>]
This is a generic warning status message, it might be followed by
error location specific data. <error code> and <location>
should not contain spaces. The error code is a either a string
commencing with a letter or such a string prefixed with a
numerical error code and an underscore; e.g.: "151011327_EOF".
*** SUCCESS [<location>]
Positive confirmation that an operation succeeded. It is used
similar to ISO-C's EXIT_SUCCESS. <location> is optional but if
given should not contain spaces. Used only with a few commands.
*** FAILURE <location> <error_code>
This is the counterpart to SUCCESS and used to indicate a program
failure. It is used similar to ISO-C's EXIT_FAILURE but allows
conveying more information, in particular a gpg-error error code.
That numerical error code may optionally have a suffix made of an
underscore and a string with an error symbol like "151011327_EOF".
A dash may be used instead of <location>.
*** BADARMOR
The ASCII armor is corrupted. No arguments yet.
*** DELETE_PROBLEM <reason_code>
Deleting a key failed. Reason codes are:
- 1 :: No such key
- 2 :: Must delete secret key first
- 3 :: Ambigious specification
- 4 :: Key is stored on a smartcard.
*** PROGRESS <what> <char> <cur> <total> [<units>]
- Used by the primegen and Public key functions to indicate
+ Used by the primegen and public key functions to indicate
progress. <char> is the character displayed with no --status-fd
enabled, with the linefeed replaced by an 'X'. <cur> is the
current amount done and <total> is amount to be done; a <total> of
- 0 indicates that the total amount is not known. The condition
+ 0 indicates that the total amount is not known. Both are
+ non-negative integers. The condition
: TOTAL && CUR == TOTAL
may be used to detect the end of an operation.
- Well known values for WHAT are:
+ Well known values for <what> are:
- pk_dsa :: DSA key generation
- pk_elg :: Elgamal key generation
- primegen :: Prime generation
- need_entropy :: Waiting for new entropy in the RNG
- tick :: Generic tick without any special meaning - useful
for letting clients know that the server is still
working.
- starting_agent :: A gpg-agent was started because it is not
running as a daemon.
- learncard :: Send by the agent and gpgsm while learing
the data of a smartcard.
- card_busy :: A smartcard is still working
- <units> is sometines used to describe the units for <current> and
+ When <what> refers to a file path, it may be truncated.
+
+ <units> is sometimes used to describe the units for <current> and
<total>. For example "B", "KiB", or "MiB".
*** BACKUP_KEY_CREATED <fingerprint> <fname>
A backup of a key identified by <fingerprint> has been writte to
the file <fname>; <fname> is percent-escaped.
*** MOUNTPOINT <name>
<name> is a percent-plus escaped filename describing the
mountpoint for the current operation (e.g. used by "g13 --mount").
This may either be the specified mountpoint or one randomly
chosen by g13.
*** PINENTRY_LAUNCHED <pid>[:<extra>]
This status line is emitted by gpg to notify a client that a
Pinentry has been launched. <pid> is the PID of the Pinentry. It
may be used to display a hint to the user but can't be used to
synchronize with Pinentry. Note that there is also an Assuan
inquiry line with the same name used internally or, if enabled,
send to the client instead of this status line. Such an inquiry
may be used to sync with Pinentry
** Obsolete status codes
*** SIGEXPIRED
Removed on 2011-02-04. This is deprecated in favor of KEYEXPIRED.
*** RSA_OR_IDEA
Obsolete. This status message used to be emitted for requests to
use the IDEA or RSA algorithms. It has been dropped from GnuPG
2.1 after the respective patents expired.
*** SHM_INFO, SHM_GET, SHM_GET_BOOL, SHM_GET_HIDDEN
These were used for the ancient shared memory based co-processing.
*** BEGIN_STREAM, END_STREAM
Used to issued by the experimental pipemode.
* Format of the --attribute-fd output
When --attribute-fd is set, during key listings (--list-keys,
--list-secret-keys) GnuPG dumps each attribute packet to the file
descriptor specified. --attribute-fd is intended for use with
--status-fd as part of the required information is carried on the
ATTRIBUTE status tag (see above).
The contents of the attribute data is specified by RFC 4880. For
convenience, here is the Photo ID format, as it is currently the
only attribute defined:
- Byte 0-1 :: The length of the image header. Due to a historical
accident (i.e. oops!) back in the NAI PGP days, this
is a little-endian number. Currently 16 (0x10 0x00).
- Byte 2 :: The image header version. Currently 0x01.
- Byte 3 :: Encoding format. 0x01 == JPEG.
- Byte 4-15 :: Reserved, and currently unused.
All other data after this header is raw image (JPEG) data.
* Layout of the TrustDB
The TrustDB is built from fixed length records, where the first byte
describes the record type. All numeric values are stored in network
byte order. The length of each record is 40 bytes. The first
record of the DB is always of type 1 and this is the only record of
this type.
The record types: directory(2), key(3), uid(4), pref(5), sigrec(6),
and shadow directory(8) are not anymore used by version 2 of the
TrustDB.
** Record type 0
Unused record or deleted, can be reused for any purpose. Such
records should in general not exist because deleted records are of
type 254 and kept in a linked list.
** Version info (RECTYPE_VER, 1)
Version information for this TrustDB. This is always the first
record of the DB and the only one of this type.
- 1 u8 :: Record type (value: 1).
- 3 byte :: Magic value ("gpg")
- 1 u8 :: TrustDB version (value: 2).
- 1 u8 :: =marginals=. How many marginal trusted keys are required.
- 1 u8 :: =completes=. How many completely trusted keys are
required.
- 1 u8 :: =max_cert_depth=. How deep is the WoT evaluated. Along
with =marginals= and =completes=, this value is used to
check whether the cached validity value from a [FIXME
dir] record can be used.
- 1 u8 :: =trust_model=
- 1 u8 :: =min_cert_level=
- 2 byte :: Not used
- 1 u32 :: =created=. Timestamp of trustdb creation.
- 1 u32 :: =nextcheck=. Timestamp of last modification which may
affect the validity of keys in the trustdb. This value
is checked against the validity timestamp in the dir
records.
- 1 u32 :: =reserved=. Not used.
- 1 u32 :: =reserved2=. Not used.
- 1 u32 :: =firstfree=. Number of the record with the head record
of the RECTYPE_FREE linked list.
- 1 u32 :: =reserved3=. Not used.
- 1 u32 :: =trusthashtbl=. Record number of the trusthashtable.
** Hash table (RECTYPE_HTBL, 10)
Due to the fact that we use fingerprints to lookup keys, we can
implement quick access by some simple hash methods, and avoid the
overhead of gdbm. A property of fingerprints is that they can be
used directly as hash values. What we use is a dynamic multilevel
architecture, which combines hash tables, record lists, and linked
lists.
This record is a hash table of 256 entries with the property that
all these records are stored consecutively to make one big
table. The hash value is simple the 1st, 2nd, ... byte of the
fingerprint (depending on the indirection level).
- 1 u8 :: Record type (value: 10).
- 1 u8 :: Reserved
- n u32 :: =recnum=. A table with the hash table items fitting into
this record. =n= depends on the record length:
$n=(reclen-2)/4$ which yields 9 for oure current record
length of 40 bytes.
The total number of hash table records to form the table is:
$m=(256+n-1)/n$. This is 29 for our record length of 40.
To look up a key we use the first byte of the fingerprint to get
the recnum from this hash table and then look up the addressed
record:
- If that record is another hash table, we use 2nd byte to index
that hash table and so on;
- if that record is a hash list, we walk all entries until we find
a matching one; or
- if that record is a key record, we compare the fingerprint to
decide whether it is the requested key;
** Hash list (RECTYPE_HLST, 11)
See hash table above on how it is used. It may also be used for
other purposes.
- 1 u8 :: Record type (value: 11).
- 1 u8 :: Reserved.
- 1 u32 :: =next=. Record number of the next hash list record or 0
if none.
- n u32 :: =rnum=. Array with record numbers to values. With
$n=(reclen-5)/5$ and our record length of 40, n is 7.
** Trust record (RECTYPE_TRUST, 12)
- 1 u8 :: Record type (value: 12).
- 1 u8 :: Reserved.
- 20 byte :: =fingerprint=.
- 1 u8 :: =ownertrust=.
- 1 u8 :: =depth=.
- 1 u8 :: =min_ownertrust=.
- 1 byte :: Not used.
- 1 u32 :: =validlist=.
- 10 byte :: Not used.
** Validity record (RECTYPE_VALID, 13)
- 1 u8 :: Record type (value: 13).
- 1 u8 :: Reserved.
- 20 byte :: =namehash=.
- 1 u8 :: =validity=
- 1 u32 :: =next=.
- 1 u8 :: =full_count=.
- 1 u8 :: =marginal_count=.
- 11 byte :: Not used.
** Free record (RECTYPE_FREE, 254)
All these records form a linked list of unused records in the TrustDB.
- 1 u8 :: Record type (value: 254)
- 1 u8 :: Reserved.
- 1 u32 :: =next=. Record number of the next rcord of this type.
The record number to the head of this linked list is
stored in the version info record.
* Database scheme for the TOFU info
#+begin_src sql
--
-- The VERSION table holds the version of our TOFU data structures.
--
CREATE TABLE version (
version integer -- As of now this is always 1
);
--
-- The BINDINGS table associates mail addresses with keys.
--
CREATE TABLE bindings (
oid integer primary key autoincrement,
fingerprint text, -- The key's fingerprint in hex
email text, -- The normalized mail address destilled from user_id
user_id text, -- The unmodified user id
time integer, -- The time this binding was first observed.
policy boolean check
(policy in (1, 2, 3, 4, 5)), -- The trust policy with the values:
-- 1 := Auto
-- 2 := Good
-- 3 := Unknown
-- 4 := Bad
-- 5 := Ask
conflict string, -- NULL or a hex formatted fingerprint.
unique (fingerprint, email)
);
CREATE INDEX bindings_fingerprint_email on bindings (fingerprint, email);
CREATE INDEX bindings_email on bindings (email);
--
-- The SIGNATURES table records all data signatures we verified
--
CREATE TABLE signatures (
binding integer not null, -- Link to bindings table,
-- references bindings.oid.
sig_digest text, -- The digest of the signed message.
origin text, -- String describing who initially fed
-- the signature to gpg (e.g. "email:claws").
sig_time integer, -- Timestamp from the signature.
time integer, -- Time this record was created.
primary key (binding, sig_digest, origin)
);
#+end_src
* GNU extensions to the S2K algorithm
1 octet - S2K Usage: either 254 or 255.
1 octet - S2K Cipher Algo: 0
1 octet - S2K Specifier: 101
3 octets - "GNU"
1 octet - GNU S2K Extension Number.
If such a GNU extension is used neither an IV nor any kind of
checksum is used. The defined GNU S2K Extension Numbers are:
- 1 :: Do not store the secret part at all. No specific data
follows.
- 2 :: A stub to access smartcards. This data follows:
- One octet with the length of the following serial number.
- The serial number. Regardless of what the length octet
indicates no more than 16 octets are stored.
Note that gpg stores the GNU S2K Extension Number internally as an
S2K Specifier with an offset of 1000.
* Format of the OpenPGP TRUST packet
According to RFC4880 (5.10), the trust packet (aka ring trust) is
only used within keyrings and contains data that records the user's
specifications of which key holds trusted introducers. The RFC also
states that the format of this packet is implementation defined and
SHOULD NOT be emitted to output streams or should be ignored on
import. GnuPG uses this packet in several additional ways:
- 1 octet :: Trust-Value (only used by Subtype SIG)
- 1 octet :: Signature-Cache (only used by Subtype SIG; value must
be less than 128)
- 3 octets :: Fixed value: "gpg"
- 1 octet :: Subtype
- 0 :: Signature cache (SIG)
- 1 :: Key source on the primary key (KEY)
- 2 :: Key source on a user id (UID)
- 1 octet :: Key Source; i.e. the origin of the key:
- 0 :: Unknown source.
- 1 :: Public keyserver.
- 2 :: Preferred keyserver.
- 3 :: OpenPGP DANE.
- 4 :: Web Key Directory.
- 5 :: Import from a trusted URL.
- 6 :: Import from a trusted file.
- 7 :: Self generated.
- 4 octets :: Time of last update. This is a a four-octet scalar
with the seconds since Epoch.
- 1 octet :: Scalar with the length of the following field.
- N octets :: String with the URL of the source. This may be a
zero-length string.
If the packets contains only two octets a Subtype of 0 is assumed;
this is the only format recognized by GnuPG versions < 2.1.18.
Trust-Value and Signature-Cache must be zero for all subtypes other
than SIG.
* Keyserver helper message format
*This information is obsolete*
(Keyserver helpers have been replaced by dirmngr)
The keyserver may be contacted by a Unix Domain socket or via TCP.
The format of a request is:
#+begin_example
command-tag
"Content-length:" digits
CRLF
#+end_example
Where command-tag is
#+begin_example
NOOP
GET <user-name>
PUT
DELETE <user-name>
#+end_example
The format of a response is:
#+begin_example
"GNUPG/1.0" status-code status-text
"Content-length:" digits
CRLF
#+end_example
followed by <digits> bytes of data
Status codes are:
- 1xx :: Informational - Request received, continuing process
- 2xx :: Success - The action was successfully received, understood,
and accepted
- 4xx :: Client Error - The request contains bad syntax or cannot be
fulfilled
- 5xx :: Server Error - The server failed to fulfill an apparently
valid request
* Object identifiers
OIDs below the GnuPG arc:
#+begin_example
1.3.6.1.4.1.11591.2 GnuPG
1.3.6.1.4.1.11591.2.1 notation
1.3.6.1.4.1.11591.2.1.1 pkaAddress
1.3.6.1.4.1.11591.2.2 X.509 extensions
1.3.6.1.4.1.11591.2.2.1 standaloneCertificate
1.3.6.1.4.1.11591.2.2.2 wellKnownPrivateKey
1.3.6.1.4.1.11591.2.12242973 invalid encoded OID
#+end_example
* Debug flags
This tables gives the flag values for the --debug option along with
the alternative names used by the components.
| | gpg | gpgsm | agent | scd | dirmngr | g13 | wks |
|-------+---------+---------+---------+---------+---------+---------+---------|
| 1 | packet | x509 | | | x509 | mount | mime |
| 2 | mpi | mpi | mpi | mpi | | | parser |
| 4 | crypto | crypto | crypto | crypto | crypto | crypto | crypto |
| 8 | filter | | | | | | |
| 16 | iobuf | | | | dns | | |
| 32 | memory | memory | memory | memory | memory | memory | memory |
| 64 | cache | cache | cache | cache | cache | | |
| 128 | memstat | memstat | memstat | memstat | memstat | memstat | memstat |
| 256 | trust | | | | | | |
| 512 | hashing | hashing | hashing | hashing | hashing | | |
| 1024 | ipc | ipc | ipc | ipc | ipc | ipc | ipc |
| 2048 | | | | cardio | network | | |
| 4096 | clock | | | reader | | | |
| 8192 | lookup | | | | lookup | | |
| 16384 | extprog | | | | | | extprog |
Description of some debug flags:
- cardio :: Used by scdaemon to trace the APDUs exchange with the
card.
- clock :: Show execution times of certain functions.
- crypto :: Trace crypto operations.
- hashing :: Create files with the hashed data.
- ipc :: Trace the Assuan commands.
- mpi :: Show the values of the MPIs.
- reader :: Used by scdaemon to trace card reader related code. For
example: Open and close reader.
* Miscellaneous notes
** v3 fingerprints
For packet version 3 we calculate the keyids this way:
- RSA :: Low 64 bits of n
- ELGAMAL :: Build a v3 pubkey packet (with CTB 0x99) and
calculate a RMD160 hash value from it. This is used
as the fingerprint and the low 64 bits are the keyid.
** Simplified revocation certificates
Revocation certificates consist only of the signature packet;
"--import" knows how to handle this. The rationale behind it is to
keep them small.
** Documentation on HKP (the http keyserver protocol):
A minimalistic HTTP server on port 11371 recognizes a GET for
/pks/lookup. The standard http URL encoded query parameters are
this (always key=value):
- op=index (like pgp -kv), op=vindex (like pgp -kvv) and op=get (like
pgp -kxa)
- search=<stringlist>. This is a list of words that must occur in the key.
The words are delimited with space, points, @ and so on. The delimiters
are not searched for and the order of the words doesn't matter (but see
next option).
- exact=on. This switch tells the hkp server to only report exact matching
keys back. In this case the order and the "delimiters" are important.
- fingerprint=on. Also reports the fingerprints when used with 'index' or
'vindex'
The keyserver also recognizes http-POSTs to /pks/add. Use this to upload
keys.
A better way to do this would be a request like:
/pks/lookup/<gnupg_formatierte_user_id>?op=<operation>
This can be implemented using Hurd's translator mechanism.
However, I think the whole keyserver stuff has to be re-thought;
I have some ideas and probably create a white paper.
** Algorithm names for the "keygen.algo" prompt
When using a --command-fd controlled key generation or "addkey"
there is way to know the number to enter on the "keygen.algo"
prompt. The displayed numbers are for human reception and may
change with releases. To provide a stable way to enter a desired
algorithm choice the prompt also accepts predefined names for the
algorithms, which will not change.
| Name | No | Description |
|---------+----+---------------------------------|
| rsa+rsa | 1 | RSA and RSA (default) |
| dsa+elg | 2 | DSA and Elgamal |
| dsa | 3 | DSA (sign only) |
| rsa/s | 4 | RSA (sign only) |
| elg | 5 | Elgamal (encrypt only) |
| rsa/e | 6 | RSA (encrypt only) |
| dsa/* | 7 | DSA (set your own capabilities) |
| rsa/* | 8 | RSA (set your own capabilities) |
| ecc+ecc | 9 | ECC and ECC |
| ecc/s | 10 | ECC (sign only) |
| ecc/* | 11 | ECC (set your own capabilities) |
| ecc/e | 12 | ECC (encrypt only) |
| keygrip | 13 | Existing key |
If one of the "foo/*" names are used a "keygen.flags" prompt needs
to be answered as well. Instead of toggling the predefined flags,
it is also possible to set them direct: Use a "=" character
directly followed by a combination of "a" (for authentication), "s"
(for signing), or "c" (for certification).
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c0c7fd0b7..21e3e4578 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,199 +1,199 @@
# Copyright (C) 2002, 2004 Free Software Foundation, Inc.
#
# This file is part of GnuPG.
#
# GnuPG is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# GnuPG is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, see <https://www.gnu.org/licenses/>.
## Process this file with automake to produce Makefile.in
AM_CPPFLAGS =
include $(top_srcdir)/am/cmacros.am
examples = examples/README examples/scd-event examples/trustlist.txt \
examples/vsnfd.prf examples/debug.prf examples/qualified.txt \
examples/systemd-user/README \
examples/systemd-user/dirmngr.service \
examples/systemd-user/dirmngr.socket \
examples/systemd-user/gpg-agent.service \
examples/systemd-user/gpg-agent.socket \
examples/systemd-user/gpg-agent-ssh.socket \
examples/systemd-user/gpg-agent-browser.socket \
examples/systemd-user/gpg-agent-extra.socket \
examples/gpgconf.conf examples/pwpattern.list
helpfiles = help.txt help.be.txt help.ca.txt help.cs.txt \
help.da.txt help.de.txt help.el.txt help.eo.txt \
help.es.txt help.et.txt help.fi.txt help.fr.txt \
help.gl.txt help.hu.txt help.id.txt help.it.txt \
help.ja.txt help.nb.txt help.pl.txt help.pt.txt \
help.pt_BR.txt help.ro.txt help.ru.txt help.sk.txt \
help.sv.txt help.tr.txt help.zh_CN.txt help.zh_TW.txt
profiles =
EXTRA_DIST = samplekeys.asc mksamplekeys com-certs.pem \
gnupg-logo.eps gnupg-logo.pdf gnupg-logo.png gnupg-logo-tr.png \
gnupg-module-overview.png gnupg-module-overview.pdf \
gnupg-card-architecture.png gnupg-card-architecture.pdf \
FAQ gnupg7.texi mkdefsinc.c defsincdate \
opt-homedir.texi see-also-note.texi specify-user-id.texi \
gpgv.texi yat2m.c ChangeLog-2011 whats-new-in-2.1.txt
BUILT_SOURCES = gnupg-module-overview.png gnupg-module-overview.pdf \
gnupg-card-architecture.png gnupg-card-architecture.pdf \
defsincdate defs.inc
info_TEXINFOS = gnupg.texi
dist_pkgdata_DATA = $(helpfiles) $(profiles)
nobase_dist_doc_DATA = FAQ DETAILS HACKING DCO TRANSLATE OpenPGP KEYSERVER \
$(examples)
#dist_html_DATA =
gnupg_TEXINFOS = \
gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \
tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \
sysnotes.texi dirmngr.texi wks.texi \
gnupg-module-overview.svg \
gnupg-card-architecture.fig \
howtos.texi howto-create-a-server-cert.texi
gnupg.texi : defs.inc
# We need EPS files for "make distcheck" but we do not want to distribute
# them due to their size. Let's build them as needed.
gnupg.dvi : gnupg-module-overview.eps gnupg-card-architecture.eps
DVIPS = TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" dvips
AM_MAKEINFOFLAGS = -I $(srcdir) --css-ref=/share/site.css
YAT2M_OPTIONS = -I $(srcdir) \
--release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard 2.1"
myman_sources = gnupg7.texi gpg.texi gpgsm.texi gpg-agent.texi \
dirmngr.texi scdaemon.texi tools.texi wks.texi
myman_pages = gpgsm.1 gpg-agent.1 dirmngr.8 scdaemon.1 \
watchgnupg.1 gpgconf.1 addgnupghome.8 gpg-preset-passphrase.1 \
- gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 \
+ gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 gpgtar.1 \
applygnupgdefaults.8 gpg-wks-client.1 gpg-wks-server.1 \
dirmngr-client.1
if USE_GPG2_HACK
myman_pages += gpg2.1 gpgv2.1
else
myman_pages += gpg.1 gpgv.1
endif
man_MANS = $(myman_pages) gnupg.7
watchgnupg_SOURCE = gnupg.texi
CLEANFILES = yat2m mkdefsinc defs.inc
DISTCLEANFILES = gnupg.tmp gnupg.ops yat2m-stamp.tmp yat2m-stamp \
gnupg-card-architecture.eps \
gnupg-module-overview.eps \
- $(myman_pages) gpg-zip.1 gnupg.7
+ $(myman_pages) gnupg.7
yat2m: yat2m.c
$(CC_FOR_BUILD) -o $@ $(srcdir)/yat2m.c
mkdefsinc: mkdefsinc.c Makefile ../config.h
$(CC_FOR_BUILD) -I. -I.. -I$(srcdir) $(AM_CPPFLAGS) \
-o $@ $(srcdir)/mkdefsinc.c
.svg.eps:
convert `test -f '$<' || echo '$(srcdir)/'`$< $@
.svg.png:
convert `test -f '$<' || echo '$(srcdir)/'`$< $@
.svg.pdf:
convert `test -f '$<' || echo '$(srcdir)/'`$< $@
.fig.png:
fig2dev -L png `test -f '$<' || echo '$(srcdir)/'`$< $@
.fig.jpg:
fig2dev -L jpeg `test -f '$<' || echo '$(srcdir)/'`$< $@
.fig.eps:
fig2dev -L eps `test -f '$<' || echo '$(srcdir)/'`$< $@
.fig.pdf:
fig2dev -L pdf `test -f '$<' || echo '$(srcdir)/'`$< $@
yat2m-stamp: $(myman_sources) defs.inc
@rm -f yat2m-stamp.tmp
@touch yat2m-stamp.tmp
incd="`test -f defsincdate || echo '$(srcdir)/'`defsincdate"; \
for file in $(myman_sources) ; do \
$(YAT2M) $(YAT2M_OPTIONS) --store \
--date "`cat $$incd 2>/dev/null`" \
`test -f '$$file' || echo '$(srcdir)/'`$$file ; done
@mv -f yat2m-stamp.tmp $@
yat2m-stamp: $(YAT2M)
$(myman_pages) gnupg.7 : yat2m-stamp defs.inc
@if test -f $@; then :; else \
trap 'rm -rf yat2m-stamp yat2m-lock' 1 2 13 15; \
if mkdir yat2m-lock 2>/dev/null; then \
rm -f yat2m-stamp; \
$(MAKE) $(AM_MAKEFLAGS) yat2m-stamp; \
rmdir yat2m-lock; \
else \
while test -d yat2m-lock; do sleep 1; done; \
test -f yat2m-stamp; exit $$?; \
fi; \
fi
dist-hook: defsincdate
defsincdate: $(gnupg_TEXINFOS)
: >defsincdate ; \
if test -e $(top_srcdir)/.git; then \
(cd $(srcdir) && git log -1 --format='%ct' \
-- $(gnupg_TEXINFOS) 2>/dev/null) >>defsincdate; \
fi
defs.inc : defsincdate Makefile mkdefsinc
incd="`test -f defsincdate || echo '$(srcdir)/'`defsincdate"; \
./mkdefsinc -C $(srcdir) --date "`cat $$incd 2>/dev/null`" \
$(gnupg_TEXINFOS) >$@
online: gnupg.html gnupg.pdf gnupg-module-overview.png \
gnupg-card-architecture.png
set -e; \
echo "Uploading current manuals to www.gnupg.org ..."; \
cp $(srcdir)/gnupg-logo-tr.png gnupg.html/; \
cp gnupg-module-overview.png gnupg.html/; \
cp gnupg-card-architecture.png gnupg.html/; \
user=werner ; webhost="ftp.gnupg.org" ; dashdevel="" ; \
if echo "@PACKAGE_VERSION@" | grep -- "-beta" >/dev/null; then \
dashdevel="-devel" ; \
else \
rsync -v gnupg.pdf $${user}@$${webhost}:webspace/manuals/ ; \
fi ; \
cd gnupg.html ; \
rsync -vr --exclude='.git' . \
$${user}@$${webhost}:webspace/manuals/gnupg$${dashdevel}/
diff --git a/doc/tools.texi b/doc/tools.texi
index 332fb01b3..5104beaa5 100644
--- a/doc/tools.texi
+++ b/doc/tools.texi
@@ -1,2036 +1,2100 @@
@c Copyright (C) 2004, 2008 Free Software Foundation, Inc.
@c This is part of the GnuPG manual.
@c For copying conditions, see the file GnuPG.texi.
@include defs.inc
@node Helper Tools
@chapter Helper Tools
GnuPG comes with a couple of smaller tools:
@menu
* watchgnupg:: Read logs from a socket.
* gpgv:: Verify OpenPGP signatures.
* addgnupghome:: Create .gnupg home directories.
* gpgconf:: Modify .gnupg home directories.
* applygnupgdefaults:: Run gpgconf for all users.
* gpg-preset-passphrase:: Put a passphrase into the cache.
* gpg-connect-agent:: Communicate with a running agent.
* dirmngr-client:: How to use the Dirmngr client tool.
* gpgparsemail:: Parse a mail message into an annotated format
* symcryptrun:: Call a simple symmetric encryption tool.
-* gpg-zip:: Encrypt or sign files into an archive.
+* gpgtar:: Encrypt or sign files into an archive.
@end menu
@c
@c WATCHGNUPG
@c
@manpage watchgnupg.1
@node watchgnupg
@section Read logs from a socket
@ifset manverb
.B watchgnupg
\- Read and print logs from a socket
@end ifset
@mansect synopsis
@ifset manverb
.B watchgnupg
.RB [ \-\-force ]
.RB [ \-\-verbose ]
.I socketname
@end ifset
@mansect description
Most of the main utilities are able to write their log files to a Unix
Domain socket if configured that way. @command{watchgnupg} is a simple
listener for such a socket. It ameliorates the output with a time stamp
and makes sure that long lines are not interspersed with log output from
other utilities. This tool is not available for Windows.
@noindent
@command{watchgnupg} is commonly invoked as
@example
watchgnupg --force $(gpgconf --list-dirs socketdir)/S.log
@end example
@manpause
@noindent
This starts it on the current terminal for listening on the standard
logging socket (which is either @file{~/.gnupg/S.log} or
@file{/var/run/user/UID/gnupg/S.log}).
@mansect options
@noindent
@command{watchgnupg} understands these options:
@table @gnupgtabopt
@item --force
@opindex force
Delete an already existing socket file.
@anchor{option watchgnupg --tcp}
@item --tcp @var{n}
Instead of reading from a local socket, listen for connects on TCP port
@var{n}.
@item --time-only
@opindex time-only
Do not print the date part of the timestamp.
@item --verbose
@opindex verbose
Enable extra informational output.
@item --version
@opindex version
Print version of the program and exit.
@item --help
@opindex help
Display a brief help page and exit.
@end table
@noindent
@mansect examples
@chapheading Examples
@example
$ watchgnupg --force --time-only $(gpgconf --list-dirs socketdir)/S.log
@end example
This waits for connections on the local socket
(e.g. @file{/home/foo/.gnupg/S.log}) and shows all log entries. To
make this work the option @option{log-file} needs to be used with all
modules which logs are to be shown. The suggested entry for the
configuration files is:
@example
log-file socket://
@end example
If the default socket as given above and returned by "echo $(gpgconf
--list-dirs socketdir)/S.log" is not desired an arbitrary socket name
can be specified, for example @file{socket:///home/foo/bar/mysocket}.
For debugging purposes it is also possible to do remote logging. Take
care if you use this feature because the information is send in the
clear over the network. Use this syntax in the conf files:
@example
log-file tcp://192.168.1.1:4711
@end example
You may use any port and not just 4711 as shown above; only IP
addresses are supported (v4 and v6) and no host names. You need to
start @command{watchgnupg} with the @option{tcp} option. Note that
under Windows the registry entry
@var{HKCU\Software\GNU\GnuPG:DefaultLogFile} can be used to change the
default log output from @code{stderr} to whatever is given by that
entry. However the only useful entry is a TCP name for remote
debugging.
@mansect see also
@ifset isman
@command{gpg}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
@command{scdaemon}(1)
@end ifset
@include see-also-note.texi
@c
@c GPGV
@c
@include gpgv.texi
@c
@c ADDGNUPGHOME
@c
@manpage addgnupghome.8
@node addgnupghome
@section Create .gnupg home directories
@ifset manverb
.B addgnupghome
\- Create .gnupg home directories
@end ifset
@mansect synopsis
@ifset manverb
.B addgnupghome
.I account_1
.IR account_2 ... account_n
@end ifset
@mansect description
If GnuPG is installed on a system with existing user accounts, it is
sometimes required to populate the GnuPG home directory with existing
files. Especially a @file{trustlist.txt} and a keybox with some
initial certificates are often desired. This script helps to do this
by copying all files from @file{/etc/skel/.gnupg} to the home
directories of the accounts given on the command line. It takes care
not to overwrite existing GnuPG home directories.
@noindent
@command{addgnupghome} is invoked by root as:
@example
addgnupghome account1 account2 ... accountn
@end example
@c
@c GPGCONF
@c
@manpage gpgconf.1
@node gpgconf
@section Modify .gnupg home directories
@ifset manverb
.B gpgconf
\- Modify .gnupg home directories
@end ifset
@mansect synopsis
@ifset manverb
.B gpgconf
.RI [ options ]
.B \-\-list-components
.br
.B gpgconf
.RI [ options ]
.B \-\-list-options
.I component
.br
.B gpgconf
.RI [ options ]
.B \-\-change-options
.I component
@end ifset
@mansect description
The @command{gpgconf} is a utility to automatically and reasonable
safely query and modify configuration files in the @file{.gnupg} home
directory. It is designed not to be invoked manually by the user, but
automatically by graphical user interfaces (GUI).@footnote{Please note
that currently no locking is done, so concurrent access should be
avoided. There are some precautions to avoid corruption with
concurrent usage, but results may be inconsistent and some changes may
get lost. The stateless design makes it difficult to provide more
guarantees.}
@command{gpgconf} provides access to the configuration of one or more
components of the GnuPG system. These components correspond more or
less to the programs that exist in the GnuPG framework, like GPG,
GPGSM, DirMngr, etc. But this is not a strict one-to-one
relationship. Not all configuration options are available through
@command{gpgconf}. @command{gpgconf} provides a generic and abstract
method to access the most important configuration options that can
feasibly be controlled via such a mechanism.
@command{gpgconf} can be used to gather and change the options
available in each component, and can also provide their default
values. @command{gpgconf} will give detailed type information that
can be used to restrict the user's input without making an attempt to
commit the changes.
@command{gpgconf} provides the backend of a configuration editor. The
configuration editor would usually be a graphical user interface
program that displays the current options, their default
values, and allows the user to make changes to the options. These
changes can then be made active with @command{gpgconf} again. Such a
program that uses @command{gpgconf} in this way will be called GUI
throughout this section.
@menu
* Invoking gpgconf:: List of all commands and options.
* Format conventions:: Formatting conventions relevant for all commands.
* Listing components:: List all gpgconf components.
* Checking programs:: Check all programs known to gpgconf.
* Listing options:: List all options of a component.
* Changing options:: Changing options of a component.
* Listing global options:: List all global options.
* Querying versions:: Get and compare software versions.
* Files used by gpgconf:: What files are used by gpgconf.
@end menu
@manpause
@node Invoking gpgconf
@subsection Invoking gpgconf
@mansect commands
One of the following commands must be given:
@table @gnupgtabopt
@item --list-components
List all components. This is the default command used if none is
specified.
@item --check-programs
List all available backend programs and test whether they are runnable.
@item --list-options @var{component}
List all options of the component @var{component}.
@item --change-options @var{component}
Change the options of the component @var{component}.
@item --check-options @var{component}
Check the options for the component @var{component}.
@item --apply-profile @var{file}
Apply the configuration settings listed in @var{file} to the
configuration files. If @var{file} has no suffix and no slashes the
command first tries to read a file with the suffix @code{.prf} from
the the data directory (@code{gpgconf --list-dirs datadir}) before it
reads the file verbatim. A profile is divided into sections using the
bracketed component name. Each section then lists the option which
shall go into the respective configuration file.
@item --apply-defaults
Update all configuration files with values taken from the global
configuration file (usually @file{/etc/gnupg/gpgconf.conf}).
@item --list-dirs [@var{names}]
Lists the directories used by @command{gpgconf}. One directory is
listed per line, and each line consists of a colon-separated list where
the first field names the directory type (for example @code{sysconfdir})
and the second field contains the percent-escaped directory. Although
they are not directories, the socket file names used by
@command{gpg-agent} and @command{dirmngr} are printed as well. Note
that the socket file names and the @code{homedir} lines are the default
names and they may be overridden by command line switches. If
@var{names} are given only the directories or file names specified by
the list names are printed without any escaping.
@item --list-config [@var{filename}]
List the global configuration file in a colon separated format. If
@var{filename} is given, check that file instead.
@item --check-config [@var{filename}]
Run a syntax check on the global configuration file. If @var{filename}
is given, check that file instead.
@item --query-swdb @var{package_name} [@var{version_string}]
Returns the current version for @var{package_name} and if
@var{version_string} is given also an indicator on whether an update
is available. The actual file with the software version is
automatically downloaded and checked by @command{dirmngr}.
@command{dirmngr} uses a thresholds to avoid download the file too
often and it does this by default only if it can be done via Tor. To
force an update of that file this command can be used:
@example
gpg-connect-agent --dirmngr 'loadswdb --force' /bye
@end example
@item --reload [@var{component}]
@opindex reload
Reload all or the given component. This is basically the same as
sending a SIGHUP to the component. Components which don't support
reloading are ignored. Without @var{component} or by using "all" for
@var{component} all components which are daemons are reloaded.
@item --launch [@var{component}]
@opindex launch
If the @var{component} is not already running, start it.
@command{component} must be a daemon. This is in general not required
because the system starts these daemons as needed. However, external
software making direct use of @command{gpg-agent} or @command{dirmngr}
may use this command to ensure that they are started. Using "all" for
@var{component} launches all components which are daemons.
@item --kill [@var{component}]
@opindex kill
Kill the given component. Components which support killing are
@command{gpg-agent} and @command{scdaemon}. Components which don't
support reloading are ignored. Using "all" for @var{component} kills
all components running as daemons. Note that as of now reload and
kill have the same effect for @command{scdaemon}.
@item --create-socketdir
@opindex create-socketdir
Create a directory for sockets below /run/user or /var/run/user. This
is command is only required if a non default home directory is used
and the /run based sockets shall be used. For the default home
directory GnUPG creates a directory on the fly.
@item --remove-socketdir
@opindex remove-socketdir
Remove a directory created with command @option{--create-socketdir}.
@end table
@mansect options
The following options may be used:
@table @gnupgtabopt
@item -o @var{file}
@itemx --output @var{file}
Write output to @var{file}. Default is to write to stdout.
@item -v
@itemx --verbose
Outputs additional information while running. Specifically, this
extends numerical field values by human-readable descriptions.
@item -q
@itemx --quiet
@opindex quiet
Try to be as quiet as possible.
@item -n
@itemx --dry-run
Do not actually change anything. This is currently only implemented
for @code{--change-options} and can be used for testing purposes.
@item -r
@itemx --runtime
Only used together with @code{--change-options}. If one of the
modified options can be changed in a running daemon process, signal
the running daemon to ask it to reparse its configuration file after
changing.
This means that the changes will take effect at run-time, as far as
this is possible. Otherwise, they will take effect at the next start
of the respective backend programs.
@manpause
@end table
@node Format conventions
@subsection Format conventions
Some lines in the output of @command{gpgconf} contain a list of
colon-separated fields. The following conventions apply:
@itemize @bullet
@item
The GUI program is required to strip off trailing newline and/or
carriage return characters from the output.
@item
@command{gpgconf} will never leave out fields. If a certain version
provides a certain field, this field will always be present in all
@command{gpgconf} versions from that time on.
@item
Future versions of @command{gpgconf} might append fields to the list.
New fields will always be separated from the previously last field by
a colon separator. The GUI should be prepared to parse the last field
it knows about up until a colon or end of line.
@item
Not all fields are defined under all conditions. You are required to
ignore the content of undefined fields.
@end itemize
There are several standard types for the content of a field:
@table @asis
@item verbatim
Some fields contain strings that are not escaped in any way. Such
fields are described to be used @emph{verbatim}. These fields will
never contain a colon character (for obvious reasons). No de-escaping
or other formatting is required to use the field content. This is for
easy parsing of the output, when it is known that the content can
never contain any special characters.
@item percent-escaped
Some fields contain strings that are described to be
@emph{percent-escaped}. Such strings need to be de-escaped before
their content can be presented to the user. A percent-escaped string
is de-escaped by replacing all occurrences of @code{%XY} by the byte
that has the hexadecimal value @code{XY}. @code{X} and @code{Y} are
from the set @code{0-9a-f}.
@item localized
Some fields contain strings that are described to be @emph{localized}.
Such strings are translated to the active language and formatted in
the active character set.
@item @w{unsigned number}
Some fields contain an @emph{unsigned number}. This number will
always fit into a 32-bit unsigned integer variable. The number may be
followed by a space, followed by a human readable description of that
value (if the verbose option is used). You should ignore everything
in the field that follows the number.
@item @w{signed number}
Some fields contain a @emph{signed number}. This number will always
fit into a 32-bit signed integer variable. The number may be followed
by a space, followed by a human readable description of that value (if
the verbose option is used). You should ignore everything in the
field that follows the number.
@item @w{boolean value}
Some fields contain a @emph{boolean value}. This is a number with
either the value 0 or 1. The number may be followed by a space,
followed by a human readable description of that value (if the verbose
option is used). You should ignore everything in the field that follows
the number; checking just the first character is sufficient in this
case.
@item option
Some fields contain an @emph{option} argument. The format of an
option argument depends on the type of the option and on some flags:
@table @asis
@item no argument
The simplest case is that the option does not take an argument at all
(@var{type} @code{0}). Then the option argument is an unsigned number
that specifies how often the option occurs. If the @code{list} flag
is not set, then the only valid number is @code{1}. Options that do
not take an argument never have the @code{default} or @code{optional
arg} flag set.
@item number
If the option takes a number argument (@var{alt-type} is @code{2} or
@code{3}), and it can only occur once (@code{list} flag is not set),
then the option argument is either empty (only allowed if the argument
is optional), or it is a number. A number is a string that begins
with an optional minus character, followed by one or more digits. The
number must fit into an integer variable (unsigned or signed,
depending on @var{alt-type}).
@item number list
If the option takes a number argument and it can occur more than once,
then the option argument is either empty, or it is a comma-separated
list of numbers as described above.
@item string
If the option takes a string argument (@var{alt-type} is 1), and it
can only occur once (@code{list} flag is not set) then the option
argument is either empty (only allowed if the argument is optional),
or it starts with a double quote character (@code{"}) followed by a
percent-escaped string that is the argument value. Note that there is
only a leading double quote character, no trailing one. The double
quote character is only needed to be able to differentiate between no
value and the empty string as value.
@item string list
If the option takes a string argument and it can occur more than once,
then the option argument is either empty, or it is a comma-separated
list of string arguments as described above.
@end table
@end table
The active language and character set are currently determined from
the locale environment of the @command{gpgconf} program.
@c FIXME: Document the active language and active character set. Allow
@c to change it via the command line?
@mansect usage
@node Listing components
@subsection Listing components
The command @code{--list-components} will list all components that can
be configured with @command{gpgconf}. Usually, one component will
correspond to one GnuPG-related program and contain the options of
that program's configuration file that can be modified using
@command{gpgconf}. However, this is not necessarily the case. A
component might also be a group of selected options from several
programs, or contain entirely virtual options that have a special
effect rather than changing exactly one option in one configuration
file.
A component is a set of configuration options that semantically belong
together. Furthermore, several changes to a component can be made in
an atomic way with a single operation. The GUI could for example
provide a menu with one entry for each component, or a window with one
tabulator sheet per component.
The command @code{--list-components} lists all available
components, one per line. The format of each line is:
@code{@var{name}:@var{description}:@var{pgmname}:}
@table @var
@item name
This field contains a name tag of the component. The name tag is used
to specify the component in all communication with @command{gpgconf}.
The name tag is to be used @emph{verbatim}. It is thus not in any
escaped format.
@item description
The @emph{string} in this field contains a human-readable description
of the component. It can be displayed to the user of the GUI for
informational purposes. It is @emph{percent-escaped} and
@emph{localized}.
@item pgmname
The @emph{string} in this field contains the absolute name of the
program's file. It can be used to unambiguously invoke that program.
It is @emph{percent-escaped}.
@end table
Example:
@example
$ gpgconf --list-components
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:
dirmngr:Directory Manager:/usr/local/bin/dirmngr:
@end example
@node Checking programs
@subsection Checking programs
The command @code{--check-programs} is similar to
@code{--list-components} but works on backend programs and not on
components. It runs each program to test whether it is installed and
runnable. This also includes a syntax check of all config file options
of the program.
The command @code{--check-programs} lists all available
programs, one per line. The format of each line is:
@code{@var{name}:@var{description}:@var{pgmname}:@var{avail}:@var{okay}:@var{cfgfile}:@var{line}:@var{error}:}
@table @var
@item name
This field contains a name tag of the program which is identical to the
name of the component. The name tag is to be used @emph{verbatim}. It
is thus not in any escaped format. This field may be empty to indicate
a continuation of error descriptions for the last name. The description
and pgmname fields are then also empty.
@item description
The @emph{string} in this field contains a human-readable description
of the component. It can be displayed to the user of the GUI for
informational purposes. It is @emph{percent-escaped} and
@emph{localized}.
@item pgmname
The @emph{string} in this field contains the absolute name of the
program's file. It can be used to unambiguously invoke that program.
It is @emph{percent-escaped}.
@item avail
The @emph{boolean value} in this field indicates whether the program is
installed and runnable.
@item okay
The @emph{boolean value} in this field indicates whether the program's
config file is syntactically okay.
@item cfgfile
If an error occurred in the configuration file (as indicated by a false
value in the field @code{okay}), this field has the name of the failing
configuration file. It is @emph{percent-escaped}.
@item line
If an error occurred in the configuration file, this field has the line
number of the failing statement in the configuration file.
It is an @emph{unsigned number}.
@item error
If an error occurred in the configuration file, this field has the error
text of the failing statement in the configuration file. It is
@emph{percent-escaped} and @emph{localized}.
@end table
@noindent
In the following example the @command{dirmngr} is not runnable and the
configuration file of @command{scdaemon} is not okay.
@example
$ gpgconf --check-programs
gpg:GPG for OpenPGP:/usr/local/bin/gpg2:1:1:
gpg-agent:GPG Agent:/usr/local/bin/gpg-agent:1:1:
scdaemon:Smartcard Daemon:/usr/local/bin/scdaemon:1:0:
gpgsm:GPG for S/MIME:/usr/local/bin/gpgsm:1:1:
dirmngr:Directory Manager:/usr/local/bin/dirmngr:0:0:
@end example
@noindent
The command @w{@code{--check-options @var{component}}} will verify the
configuration file in the same manner as @code{--check-programs}, but
only for the component @var{component}.
@node Listing options
@subsection Listing options
Every component contains one or more options. Options may be gathered
into option groups to allow the GUI to give visual hints to the user
about which options are related.
The command @code{@w{--list-options @var{component}}} lists
all options (and the groups they belong to) in the component
@var{component}, one per line. @var{component} must be the string in
the field @var{name} in the output of the @code{--list-components}
command.
There is one line for each option and each group. First come all
options that are not in any group. Then comes a line describing a
group. Then come all options that belong into each group. Then comes
the next group and so on. There does not need to be any group (and in
this case the output will stop after the last non-grouped option).
The format of each line is:
@code{@var{name}:@var{flags}:@var{level}:@var{description}:@var{type}:@var{alt-type}:@var{argname}:@var{default}:@var{argdef}:@var{value}}
@table @var
@item name
This field contains a name tag for the group or option. The name tag
is used to specify the group or option in all communication with
@command{gpgconf}. The name tag is to be used @emph{verbatim}. It is
thus not in any escaped format.
@item flags
The flags field contains an @emph{unsigned number}. Its value is the
OR-wise combination of the following flag values:
@table @code
@item group (1)
If this flag is set, this is a line describing a group and not an
option.
@end table
The following flag values are only defined for options (that is, if
the @code{group} flag is not used).
@table @code
@item optional arg (2)
If this flag is set, the argument is optional. This is never set for
@var{type} @code{0} (none) options.
@item list (4)
If this flag is set, the option can be given multiple times.
@item runtime (8)
If this flag is set, the option can be changed at runtime.
@item default (16)
If this flag is set, a default value is available.
@item default desc (32)
If this flag is set, a (runtime) default is available. This and the
@code{default} flag are mutually exclusive.
@item no arg desc (64)
If this flag is set, and the @code{optional arg} flag is set, then the
option has a special meaning if no argument is given.
@item no change (128)
If this flag is set, @command{gpgconf} ignores requests to change the
value. GUI frontends should grey out this option. Note, that manual
changes of the configuration files are still possible.
@end table
@item level
This field is defined for options and for groups. It contains an
@emph{unsigned number} that specifies the expert level under which
this group or option should be displayed. The following expert levels
are defined for options (they have analogous meaning for groups):
@table @code
@item basic (0)
This option should always be offered to the user.
@item advanced (1)
This option may be offered to advanced users.
@item expert (2)
This option should only be offered to expert users.
@item invisible (3)
This option should normally never be displayed, not even to expert
users.
@item internal (4)
This option is for internal use only. Ignore it.
@end table
The level of a group will always be the lowest level of all options it
contains.
@item description
This field is defined for options and groups. The @emph{string} in
this field contains a human-readable description of the option or
group. It can be displayed to the user of the GUI for informational
purposes. It is @emph{percent-escaped} and @emph{localized}.
@item type
This field is only defined for options. It contains an @emph{unsigned
number} that specifies the type of the option's argument, if any. The
following types are defined:
Basic types:
@table @code
@item none (0)
No argument allowed.
@item string (1)
An @emph{unformatted string}.
@item int32 (2)
A @emph{signed number}.
@item uint32 (3)
An @emph{unsigned number}.
@end table
Complex types:
@table @code
@item pathname (32)
A @emph{string} that describes the pathname of a file. The file does
not necessarily need to exist.
@item ldap server (33)
A @emph{string} that describes an LDAP server in the format:
@code{@var{hostname}:@var{port}:@var{username}:@var{password}:@var{base_dn}}
@item key fingerprint (34)
A @emph{string} with a 40 digit fingerprint specifying a certificate.
@item pub key (35)
A @emph{string} that describes a certificate by user ID, key ID or
fingerprint.
@item sec key (36)
A @emph{string} that describes a certificate with a key by user ID,
key ID or fingerprint.
@item alias list (37)
A @emph{string} that describes an alias list, like the one used with
gpg's group option. The list consists of a key, an equal sign and space
separated values.
@end table
More types will be added in the future. Please see the @var{alt-type}
field for information on how to cope with unknown types.
@item alt-type
This field is identical to @var{type}, except that only the types
@code{0} to @code{31} are allowed. The GUI is expected to present the
user the option in the format specified by @var{type}. But if the
argument type @var{type} is not supported by the GUI, it can still
display the option in the more generic basic type @var{alt-type}. The
GUI must support all the defined basic types to be able to display all
options. More basic types may be added in future versions. If the
GUI encounters a basic type it doesn't support, it should report an
error and abort the operation.
@item argname
This field is only defined for options with an argument type
@var{type} that is not @code{0}. In this case it may contain a
@emph{percent-escaped} and @emph{localized string} that gives a short
name for the argument. The field may also be empty, though, in which
case a short name is not known.
@item default
This field is defined only for options for which the @code{default} or
@code{default desc} flag is set. If the @code{default} flag is set,
its format is that of an @emph{option argument} (@pxref{Format
conventions}, for details). If the default value is empty, then no
default is known. Otherwise, the value specifies the default value
for this option. If the @code{default desc} flag is set, the field is
either empty or contains a description of the effect if the option is
not given.
@item argdef
This field is defined only for options for which the @code{optional
arg} flag is set. If the @code{no arg desc} flag is not set, its
format is that of an @emph{option argument} (@pxref{Format
conventions}, for details). If the default value is empty, then no
default is known. Otherwise, the value specifies the default argument
for this option. If the @code{no arg desc} flag is set, the field is
either empty or contains a description of the effect of this option if
no argument is given.
@item value
This field is defined only for options. Its format is that of an
@emph{option argument}. If it is empty, then the option is not
explicitly set in the current configuration, and the default applies
(if any). Otherwise, it contains the current value of the option.
Note that this field is also meaningful if the option itself does not
take a real argument (in this case, it contains the number of times
the option appears).
@end table
@node Changing options
@subsection Changing options
The command @w{@code{--change-options @var{component}}} will attempt
to change the options of the component @var{component} to the
specified values. @var{component} must be the string in the field
@var{name} in the output of the @code{--list-components} command. You
have to provide the options that shall be changed in the following
format on standard input:
@code{@var{name}:@var{flags}:@var{new-value}}
@table @var
@item name
This is the name of the option to change. @var{name} must be the
string in the field @var{name} in the output of the
@code{--list-options} command.
@item flags
The flags field contains an @emph{unsigned number}. Its value is the
OR-wise combination of the following flag values:
@table @code
@item default (16)
If this flag is set, the option is deleted and the default value is
used instead (if applicable).
@end table
@item new-value
The new value for the option. This field is only defined if the
@code{default} flag is not set. The format is that of an @emph{option
argument}. If it is empty (or the field is omitted), the default
argument is used (only allowed if the argument is optional for this
option). Otherwise, the option will be set to the specified value.
@end table
@noindent
The output of the command is the same as that of
@code{--check-options} for the modified configuration file.
Examples:
To set the force option, which is of basic type @code{none (0)}:
@example
$ echo 'force:0:1' | gpgconf --change-options dirmngr
@end example
To delete the force option:
@example
$ echo 'force:16:' | gpgconf --change-options dirmngr
@end example
The @code{--runtime} option can influence when the changes take
effect.
@node Listing global options
@subsection Listing global options
Sometimes it is useful for applications to look at the global options
file @file{gpgconf.conf}.
The colon separated listing format is record oriented and uses the first
field to identify the record type:
@table @code
@item k
This describes a key record to start the definition of a new ruleset for
a user/group. The format of a key record is:
@code{k:@var{user}:@var{group}:}
@table @var
@item user
This is the user field of the key. It is percent escaped. See the
definition of the gpgconf.conf format for details.
@item group
This is the group field of the key. It is percent escaped.
@end table
@item r
This describes a rule record. All rule records up to the next key record
make up a rule set for that key. The format of a rule record is:
@code{r:::@var{component}:@var{option}:@var{flag}:@var{value}:}
@table @var
@item component
This is the component part of a rule. It is a plain string.
@item option
This is the option part of a rule. It is a plain string.
@item flag
This is the flags part of a rule. There may be only one flag per rule
but by using the same component and option, several flags may be
assigned to an option. It is a plain string.
@item value
This is the optional value for the option. It is a percent escaped
string with a single quotation mark to indicate a string. The quotation
mark is only required to distinguish between no value specified and an
empty string.
@end table
@end table
@noindent
Unknown record types should be ignored. Note that there is intentionally
no feature to change the global option file through @command{gpgconf}.
@node Querying versions
@subsection Get and compare software versions.
The GnuPG Project operates a server to query the current versions of
software packages related to GnuPG. @command{gpgconf} can be used to
access this online database. To allow for offline operations, this
feature works by having @command{dirmngr} download a file from
@code{https://versions.gnupg.org}, checking the signature of that file
and storing the file in the GnuPG home directory. If
@command{gpgconf} is used and @command{dirmngr} is running, it may ask
@command{dirmngr} to refresh that file before itself uses the file.
The command @option{--query-swdb} returns information for the given
package in a colon delimited format:
@table @var
@item name
This is the name of the package as requested. Note that "gnupg" is a
special name which is replaced by the actual package implementing this
version of GnuPG. For this name it is also not required to specify a
version because @command{gpgconf} takes its own version in this case.
@item iversion
The currently installed version or an empty string. The value is
taken from the command line argument but may be provided by gpg
if not given.
@item status
The status of the software package according to this table:
@table @code
@item -
No information available. This is either because no current version
has been specified or due to an error.
@item ?
The given name is not known in the online database.
@item u
An update of the software is available.
@item c
The installed version of the software is current.
@item n
The installed version is already newer than the released version.
@end table
@item urgency
If the value (the empty string should be considered as zero) is
greater than zero an important update is available.
@item error
This returns an @command{gpg-error} error code to distinguish between
various failure modes.
@item filedate
This gives the date of the file with the version numbers in standard
ISO format (@code{yyyymmddThhmmss}). The date has been extracted by
@command{dirmngr} from the signature of the file.
@item verified
This gives the date in ISO format the file was downloaded. This value
can be used to evaluate the freshness of the information.
@item version
This returns the version string for the requested software from the
file.
@item reldate
This returns the release date in ISO format.
@item size
This returns the size of the package as decimal number of bytes.
@item hash
This returns a hexified SHA-2 hash of the package.
@end table
@noindent
More fields may be added in future to the output.
@mansect files
@node Files used by gpgconf
@subsection Files used by gpgconf
@table @file
@item /etc/gnupg/gpgconf.conf
@cindex gpgconf.conf
If this file exists, it is processed as a global configuration file.
A commented example can be found in the @file{examples} directory of
the distribution.
@item @var{GNUPGHOME}/swdb.lst
@cindex swdb.lst
A file with current software versions. @command{dirmngr} creates
this file on demand from an online resource.
@end table
@mansect see also
@ifset isman
@command{gpg}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
@command{scdaemon}(1),
@command{dirmngr}(1)
@end ifset
@include see-also-note.texi
@c
@c APPLYGNUPGDEFAULTS
@c
@manpage applygnupgdefaults.8
@node applygnupgdefaults
@section Run gpgconf for all users
@ifset manverb
.B applygnupgdefaults
\- Run gpgconf --apply-defaults for all users.
@end ifset
@mansect synopsis
@ifset manverb
.B applygnupgdefaults
@end ifset
@mansect description
This script is a wrapper around @command{gpgconf} to run it with the
command @code{--apply-defaults} for all real users with an existing
GnuPG home directory. Admins might want to use this script to update he
GnuPG configuration files for all users after
@file{/etc/gnupg/gpgconf.conf} has been changed. This allows enforcing
certain policies for all users. Note, that this is not a bulletproof way to
force a user to use certain options. A user may always directly edit
the configuration files and bypass gpgconf.
@noindent
@command{applygnupgdefaults} is invoked by root as:
@example
applygnupgdefaults
@end example
@c
@c GPG-PRESET-PASSPHRASE
@c
@node gpg-preset-passphrase
@section Put a passphrase into the cache
@manpage gpg-preset-passphrase.1
@ifset manverb
.B gpg-preset-passphrase
\- Put a passphrase into gpg-agent's cache
@end ifset
@mansect synopsis
@ifset manverb
.B gpg-preset-passphrase
.RI [ options ]
.RI [ command ]
.I cache-id
@end ifset
@mansect description
The @command{gpg-preset-passphrase} is a utility to seed the internal
cache of a running @command{gpg-agent} with passphrases. It is mainly
useful for unattended machines, where the usual @command{pinentry} tool
may not be used and the passphrases for the to be used keys are given at
machine startup.
This program works with GnuPG 2 and later. GnuPG 1.x is not supported.
Passphrases set with this utility don't expire unless the
@option{--forget} option is used to explicitly clear them from the
cache --- or @command{gpg-agent} is either restarted or reloaded (by
sending a SIGHUP to it). Note that the maximum cache time as set with
@option{--max-cache-ttl} is still honored. It is necessary to allow
this passphrase presetting by starting @command{gpg-agent} with the
@option{--allow-preset-passphrase}.
@menu
* Invoking gpg-preset-passphrase:: List of all commands and options.
@end menu
@manpause
@node Invoking gpg-preset-passphrase
@subsection List of all commands and options
@mancont
@noindent
@command{gpg-preset-passphrase} is invoked this way:
@example
gpg-preset-passphrase [options] [command] @var{cacheid}
@end example
@var{cacheid} is either a 40 character keygrip of hexadecimal
characters identifying the key for which the passphrase should be set
or cleared. The keygrip is listed along with the key when running the
command: @code{gpgsm --with-keygrip --list-secret-keys}.
Alternatively an arbitrary string may be used to identify a
passphrase; it is suggested that such a string is prefixed with the
name of the application (e.g @code{foo:12346}). Scripts should always
use the option @option{--with-colons}, which provides the keygrip in a
"grp" line (cf. @file{doc/DETAILS})/
@noindent
One of the following command options must be given:
@table @gnupgtabopt
@item --preset
@opindex preset
Preset a passphrase. This is what you usually will
use. @command{gpg-preset-passphrase} will then read the passphrase from
@code{stdin}.
@item --forget
@opindex forget
Flush the passphrase for the given cache ID from the cache.
@end table
@noindent
The following additional options may be used:
@table @gnupgtabopt
@item -v
@itemx --verbose
@opindex verbose
Output additional information while running.
@item -P @var{string}
@itemx --passphrase @var{string}
@opindex passphrase
Instead of reading the passphrase from @code{stdin}, use the supplied
@var{string} as passphrase. Note that this makes the passphrase visible
for other users.
@end table
@mansect see also
@ifset isman
@command{gpg}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
@command{scdaemon}(1)
@end ifset
@include see-also-note.texi
@c
@c GPG-CONNECT-AGENT
@c
@node gpg-connect-agent
@section Communicate with a running agent
@manpage gpg-connect-agent.1
@ifset manverb
.B gpg-connect-agent
\- Communicate with a running agent
@end ifset
@mansect synopsis
@ifset manverb
.B gpg-connect-agent
.RI [ options ] [commands]
@end ifset
@mansect description
The @command{gpg-connect-agent} is a utility to communicate with a
running @command{gpg-agent}. It is useful to check out the commands
@command{gpg-agent} provides using the Assuan interface. It might
also be useful for scripting simple applications. Input is expected
at stdin and output gets printed to stdout.
It is very similar to running @command{gpg-agent} in server mode; but
here we connect to a running instance.
@menu
* Invoking gpg-connect-agent:: List of all options.
* Controlling gpg-connect-agent:: Control commands.
@end menu
@manpause
@node Invoking gpg-connect-agent
@subsection List of all options
@noindent
@command{gpg-connect-agent} is invoked this way:
@example
gpg-connect-agent [options] [commands]
@end example
@mancont
@noindent
The following options may be used:
@table @gnupgtabopt
@item -v
@itemx --verbose
@opindex verbose
Output additional information while running.
@item -q
@item --quiet
@opindex q
@opindex quiet
Try to be as quiet as possible.
@include opt-homedir.texi
@item --agent-program @var{file}
@opindex agent-program
Specify the agent program to be started if none is running. The
default value is determined by running @command{gpgconf} with the
option @option{--list-dirs}. Note that the pipe symbol (@code{|}) is
used for a regression test suite hack and may thus not be used in the
file name.
@item --dirmngr-program @var{file}
@opindex dirmngr-program
Specify the directory manager (keyserver client) program to be started
if none is running. This has only an effect if used together with the
option @option{--dirmngr}.
@item --dirmngr
@opindex dirmngr
Connect to a running directory manager (keyserver client) instead of
to the gpg-agent. If a dirmngr is not running, start it.
@item -S
@itemx --raw-socket @var{name}
@opindex raw-socket
Connect to socket @var{name} assuming this is an Assuan style server.
Do not run any special initializations or environment checks. This may
be used to directly connect to any Assuan style socket server.
@item -E
@itemx --exec
@opindex exec
Take the rest of the command line as a program and it's arguments and
execute it as an Assuan server. Here is how you would run @command{gpgsm}:
@smallexample
gpg-connect-agent --exec gpgsm --server
@end smallexample
Note that you may not use options on the command line in this case.
@item --no-ext-connect
@opindex no-ext-connect
When using @option{-S} or @option{--exec}, @command{gpg-connect-agent}
connects to the Assuan server in extended mode to allow descriptor
passing. This option makes it use the old mode.
@item --no-autostart
@opindex no-autostart
Do not start the gpg-agent or the dirmngr if it has not yet been
started.
@item -r @var{file}
@itemx --run @var{file}
@opindex run
Run the commands from @var{file} at startup and then continue with the
regular input method. Note, that commands given on the command line are
executed after this file.
@item -s
@itemx --subst
@opindex subst
Run the command @code{/subst} at startup.
@item --hex
@opindex hex
Print data lines in a hex format and the ASCII representation of
non-control characters.
@item --decode
@opindex decode
Decode data lines. That is to remove percent escapes but make sure that
a new line always starts with a D and a space.
@end table
@mansect control commands
@node Controlling gpg-connect-agent
@subsection Control commands
While reading Assuan commands, gpg-agent also allows a few special
commands to control its operation. These control commands all start
with a slash (@code{/}).
@table @code
@item /echo @var{args}
Just print @var{args}.
@item /let @var{name} @var{value}
Set the variable @var{name} to @var{value}. Variables are only
substituted on the input if the @command{/subst} has been used.
Variables are referenced by prefixing the name with a dollar sign and
optionally include the name in curly braces. The rules for a valid name
are identically to those of the standard bourne shell. This is not yet
enforced but may be in the future. When used with curly braces no
leading or trailing white space is allowed.
If a variable is not found, it is searched in the environment and if
found copied to the table of variables.
Variable functions are available: The name of the function must be
followed by at least one space and the at least one argument. The
following functions are available:
@table @code
@item get
Return a value described by the argument. Available arguments are:
@table @code
@item cwd
The current working directory.
@item homedir
The gnupg homedir.
@item sysconfdir
GnuPG's system configuration directory.
@item bindir
GnuPG's binary directory.
@item libdir
GnuPG's library directory.
@item libexecdir
GnuPG's library directory for executable files.
@item datadir
GnuPG's data directory.
@item serverpid
The PID of the current server. Command @command{/serverpid} must
have been given to return a useful value.
@end table
@item unescape @var{args}
Remove C-style escapes from @var{args}. Note that @code{\0} and
@code{\x00} terminate the returned string implicitly. The string to be
converted are the entire arguments right behind the delimiting space of
the function name.
@item unpercent @var{args}
@itemx unpercent+ @var{args}
Remove percent style escaping from @var{args}. Note that @code{%00}
terminates the string implicitly. The string to be converted are the
entire arguments right behind the delimiting space of the function
name. @code{unpercent+} also maps plus signs to a spaces.
@item percent @var{args}
@itemx percent+ @var{args}
Escape the @var{args} using percent style escaping. Tabs, formfeeds,
linefeeds, carriage returns and colons are escaped. @code{percent+} also
maps spaces to plus signs.
@item errcode @var{arg}
@itemx errsource @var{arg}
@itemx errstring @var{arg}
Assume @var{arg} is an integer and evaluate it using @code{strtol}. Return
the gpg-error error code, error source or a formatted string with the
error code and error source.
@item +
@itemx -
@itemx *
@itemx /
@itemx %
Evaluate all arguments as long integers using @code{strtol} and apply
this operator. A division by zero yields an empty string.
@item !
@itemx |
@itemx &
Evaluate all arguments as long integers using @code{strtol} and apply
the logical operators NOT, OR or AND. The NOT operator works on the
last argument only.
@end table
@item /definq @var{name} @var{var}
Use content of the variable @var{var} for inquiries with @var{name}.
@var{name} may be an asterisk (@code{*}) to match any inquiry.
@item /definqfile @var{name} @var{file}
Use content of @var{file} for inquiries with @var{name}.
@var{name} may be an asterisk (@code{*}) to match any inquiry.
@item /definqprog @var{name} @var{prog}
Run @var{prog} for inquiries matching @var{name} and pass the
entire line to it as command line arguments.
@item /datafile @var{name}
Write all data lines from the server to the file @var{name}. The file
is opened for writing and created if it does not exists. An existing
file is first truncated to 0. The data written to the file fully
decoded. Using a single dash for @var{name} writes to stdout. The
file is kept open until a new file is set using this command or this
command is used without an argument.
@item /showdef
Print all definitions
@item /cleardef
Delete all definitions
@item /sendfd @var{file} @var{mode}
Open @var{file} in @var{mode} (which needs to be a valid @code{fopen}
mode string) and send the file descriptor to the server. This is
usually followed by a command like @code{INPUT FD} to set the
input source for other commands.
@item /recvfd
Not yet implemented.
@item /open @var{var} @var{file} [@var{mode}]
Open @var{file} and assign the file descriptor to @var{var}. Warning:
This command is experimental and might change in future versions.
@item /close @var{fd}
Close the file descriptor @var{fd}. Warning: This command is
experimental and might change in future versions.
@item /showopen
Show a list of open files.
@item /serverpid
Send the Assuan command @command{GETINFO pid} to the server and store
the returned PID for internal purposes.
@item /sleep
Sleep for a second.
@item /hex
@itemx /nohex
Same as the command line option @option{--hex}.
@item /decode
@itemx /nodecode
Same as the command line option @option{--decode}.
@item /subst
@itemx /nosubst
Enable and disable variable substitution. It defaults to disabled
unless the command line option @option{--subst} has been used.
If /subst as been enabled once, leading whitespace is removed from
input lines which makes scripts easier to read.
@item /while @var{condition}
@itemx /end
These commands provide a way for executing loops. All lines between
the @code{while} and the corresponding @code{end} are executed as long
as the evaluation of @var{condition} yields a non-zero value or is the
string @code{true} or @code{yes}. The evaluation is done by passing
@var{condition} to the @code{strtol} function. Example:
@smallexample
/subst
/let i 3
/while $i
/echo loop couter is $i
/let i $@{- $i 1@}
/end
@end smallexample
@item /if @var{condition}
@itemx /end
These commands provide a way for conditional execution. All lines between
the @code{if} and the corresponding @code{end} are executed only if
the evaluation of @var{condition} yields a non-zero value or is the
string @code{true} or @code{yes}. The evaluation is done by passing
@var{condition} to the @code{strtol} function.
@item /run @var{file}
Run commands from @var{file}.
@item /bye
Terminate the connection and the program.
@item /help
Print a list of available control commands.
@end table
@ifset isman
@mansect see also
@command{gpg-agent}(1),
@command{scdaemon}(1)
@include see-also-note.texi
@end ifset
@c
@c DIRMNGR-CLIENT
@c
@node dirmngr-client
@section The Dirmngr Client Tool
@manpage dirmngr-client.1
@ifset manverb
.B dirmngr-client
\- Tool to access the Dirmngr services
@end ifset
@mansect synopsis
@ifset manverb
.B dirmngr-client
.RI [ options ]
.RI [ certfile | pattern ]
@end ifset
@mansect description
The @command{dirmngr-client} is a simple tool to contact a running
dirmngr and test whether a certificate has been revoked --- either by
being listed in the corresponding CRL or by running the OCSP protocol.
If no dirmngr is running, a new instances will be started but this is
in general not a good idea due to the huge performance overhead.
@noindent
The usual way to run this tool is either:
@example
dirmngr-client @var{acert}
@end example
@noindent
or
@example
dirmngr-client <@var{acert}
@end example
Where @var{acert} is one DER encoded (binary) X.509 certificates to be
tested.
@ifclear isman
The return value of this command is
@end ifclear
@mansect return value
@ifset isman
@command{dirmngr-client} returns these values:
@end ifset
@table @code
@item 0
The certificate under question is valid; i.e. there is a valid CRL
available and it is not listed there or the OCSP request returned that
that certificate is valid.
@item 1
The certificate has been revoked
@item 2 (and other values)
There was a problem checking the revocation state of the certificate.
A message to stderr has given more detailed information. Most likely
this is due to a missing or expired CRL or due to a network problem.
@end table
@mansect options
@noindent
@command{dirmngr-client} may be called with the following options:
@table @gnupgtabopt
@item --version
@opindex version
Print the program version and licensing information. Note that you cannot
abbreviate this command.
@item --help, -h
@opindex help
Print a usage message summarizing the most useful command-line options.
Note that you cannot abbreviate this command.
@item --quiet, -q
@opindex quiet
Make the output extra brief by suppressing any informational messages.
@item -v
@item --verbose
@opindex v
@opindex verbose
Outputs additional information while running.
You can increase the verbosity by giving several
verbose commands to @sc{dirmngr}, such as @samp{-vv}.
@item --pem
@opindex pem
Assume that the given certificate is in PEM (armored) format.
@item --ocsp
@opindex ocsp
Do the check using the OCSP protocol and ignore any CRLs.
@item --force-default-responder
@opindex force-default-responder
When checking using the OCSP protocol, force the use of the default OCSP
responder. That is not to use the Reponder as given by the certificate.
@item --ping
@opindex ping
Check whether the dirmngr daemon is up and running.
@item --cache-cert
@opindex cache-cert
Put the given certificate into the cache of a running dirmngr. This is
mainly useful for debugging.
@item --validate
@opindex validate
Validate the given certificate using dirmngr's internal validation code.
This is mainly useful for debugging.
@item --load-crl
@opindex load-crl
This command expects a list of filenames with DER encoded CRL files.
With the option @option{--url} URLs are expected in place of filenames
and they are loaded directly from the given location. All CRLs will be
validated and then loaded into dirmngr's cache.
@item --lookup
@opindex lookup
Take the remaining arguments and run a lookup command on each of them.
The results are Base-64 encoded outputs (without header lines). This
may be used to retrieve certificates from a server. However the output
format is not very well suited if more than one certificate is returned.
@item --url
@itemx -u
@opindex url
Modify the @command{lookup} and @command{load-crl} commands to take an URL.
@item --local
@itemx -l
@opindex url
Let the @command{lookup} command only search the local cache.
@item --squid-mode
@opindex squid-mode
Run @sc{dirmngr-client} in a mode suitable as a helper program for
Squid's @option{external_acl_type} option.
@end table
@ifset isman
@mansect see also
@command{dirmngr}(8),
@command{gpgsm}(1)
@include see-also-note.texi
@end ifset
@c
@c GPGPARSEMAIL
@c
@node gpgparsemail
@section Parse a mail message into an annotated format
@manpage gpgparsemail.1
@ifset manverb
.B gpgparsemail
\- Parse a mail message into an annotated format
@end ifset
@mansect synopsis
@ifset manverb
.B gpgparsemail
.RI [ options ]
.RI [ file ]
@end ifset
@mansect description
The @command{gpgparsemail} is a utility currently only useful for
debugging. Run it with @code{--help} for usage information.
@c
@c SYMCRYPTRUN
@c
@node symcryptrun
@section Call a simple symmetric encryption tool
@manpage symcryptrun.1
@ifset manverb
.B symcryptrun
\- Call a simple symmetric encryption tool
@end ifset
@mansect synopsis
@ifset manverb
.B symcryptrun
.B \-\-class
.I class
.B \-\-program
.I program
.B \-\-keyfile
.I keyfile
.RB [ --decrypt | --encrypt ]
.RI [ inputfile ]
@end ifset
@mansect description
Sometimes simple encryption tools are already in use for a long time
and there might be a desire to integrate them into the GnuPG
framework. The protocols and encryption methods might be non-standard
or not even properly documented, so that a full-fledged encryption
tool with an interface like @command{gpg} is not doable.
@command{symcryptrun} provides a solution: It operates by calling the
external encryption/decryption module and provides a passphrase for a
key using the standard @command{pinentry} based mechanism through
@command{gpg-agent}.
Note, that @command{symcryptrun} is only available if GnuPG has been
configured with @samp{--enable-symcryptrun} at build time.
@menu
* Invoking symcryptrun:: List of all commands and options.
@end menu
@manpause
@node Invoking symcryptrun
@subsection List of all commands and options
@noindent
@command{symcryptrun} is invoked this way:
@example
symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE
[--decrypt | --encrypt] [inputfile]
@end example
@mancont
For encryption, the plain text must be provided on STDIN or as the
argument @var{inputfile}, and the ciphertext will be output to STDOUT.
For decryption vice versa.
@var{CLASS} describes the calling conventions of the external tool.
Currently it must be given as @samp{confucius}. @var{PROGRAM} is
the full filename of that external tool.
For the class @samp{confucius} the option @option{--keyfile} is
required; @var{keyfile} is the name of a file containing the secret key,
which may be protected by a passphrase. For detailed calling
conventions, see the source code.
@noindent
Note, that @command{gpg-agent} must be running before starting
@command{symcryptrun}.
@noindent
The following additional options may be used:
@table @gnupgtabopt
@item -v
@itemx --verbose
@opindex verbose
Output additional information while running.
@item -q
@item --quiet
@opindex q
@opindex quiet
Try to be as quiet as possible.
@include opt-homedir.texi
@item --log-file @var{file}
@opindex log-file
Append all logging output to @var{file}. Use @file{socket://} to log
to socket. Default is to write logging information to STDERR.
@end table
@noindent
The possible exit status codes of @command{symcryptrun} are:
@table @code
@item 0
Success.
@item 1
Some error occurred.
@item 2
No valid passphrase was provided.
@item 3
The operation was canceled by the user.
@end table
@mansect see also
@ifset isman
@command{gpg}(1),
@command{gpgsm}(1),
@command{gpg-agent}(1),
@end ifset
@include see-also-note.texi
@c
-@c GPG-ZIP
+@c GPGTAR
@c
-@c The original manpage on which this section is based was written
-@c by Colin Tuckley <colin@tuckley.org> and Daniel Leidert
-@c <daniel.leidert@wgdd.de> for the Debian distribution (but may be used by
-@c others).
-@manpage gpg-zip.1
-@node gpg-zip
+@manpage gpgtar.1
+@node gpgtar
@section Encrypt or sign files into an archive
@ifset manverb
-.B gpg-zip
+.B gpgtar
\- Encrypt or sign files into an archive
@end ifset
@mansect synopsis
@ifset manverb
-.B gpg-zip
+.B gpgtar
.RI [ options ]
.I filename1
.I [ filename2, ... ]
.I directory1
.I [ directory2, ... ]
@end ifset
@mansect description
-@command{gpg-zip} encrypts or signs files into an archive. It is an
+@command{gpgtar} encrypts or signs files into an archive. It is an
gpg-ized tar using the same format as used by PGP's PGP Zip.
@manpause
@noindent
-@command{gpg-zip} is invoked this way:
+@command{gpgtar} is invoked this way:
@example
-gpg-zip [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
+gpgtar [options] @var{filename1} [@var{filename2}, ...] @var{directory} [@var{directory2}, ...]
@end example
@mansect options
@noindent
-@command{gpg-zip} understands these options:
+@command{gpgtar} understands these options:
@table @gnupgtabopt
+@item --create
+@opindex create
+Put given files and directories into a vanilla ``ustar'' archive.
+
+@item --extract
+@opindex extract
+Extract all files from a vanilla ``ustar'' archive.
+
@item --encrypt
@itemx -e
@opindex encrypt
-Encrypt data. This option may be combined with @option{--symmetric} (for output that may be decrypted via a secret key or a passphrase).
+Encrypt given files and directories into an archive. This option may
+be combined with option @option{--symmetric} for an archive that may
+be decrypted via a secret key or a passphrase.
@item --decrypt
@itemx -d
@opindex decrypt
-Decrypt data.
+Extract all files from an encrypted archive.
+
+@item --sign
+@itemx -s
+Make a signed archive from the given files and directories. Thsi can
+be combined with option @option{--encrypt} to create a signed and then
+encrypted archive.
+
+@item --list-archive
+@itemx -t
+@opindex list-archive
+List the contents of the specified archive.
@item --symmetric
@itemx -c
Encrypt with a symmetric cipher using a passphrase. The default
-symmetric cipher used is CAST5, but may be chosen with the
+symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
@option{--cipher-algo} option to @command{gpg}.
-@item --sign
-@itemx -s
-Make a signature. See @command{gpg}.
-
@item --recipient @var{user}
@itemx -r @var{user}
@opindex recipient
-Encrypt for user id @var{user}. See @command{gpg}.
+Encrypt for user id @var{user}. For details see @command{gpg}.
@item --local-user @var{user}
@itemx -u @var{user}
@opindex local-user
-Use @var{user} as the key to sign with. See @command{gpg}.
-
-@item --list-archive
-@opindex list-archive
-List the contents of the specified archive.
+Use @var{user} as the key to sign with. For details see @command{gpg}.
@item --output @var{file}
@itemx -o @var{file}
@opindex output
-Write output to specified file @var{file}.
+Write the archive to the specified file @var{file}.
+
+@item --verbose
+@itemx -v
+@opindex verbose
+Enable extra informational output.
+
+@item --quiet
+@itemx -q
+@opindex quiet
+Try to be as quiet as possible.
+
+@item --skip-crypto
+@opindex skip-crypto
+Skip all crypto operations and create or extract vanilla ``ustar''
+archives.
+
+@item --dry-run
+@opindex dry-run
+Do not actually output the extracted files.
+
+@item --directory @var{dir}
+@itemx -C @var{dir}
+@opindex directory
+Extract the files into the directory @var{dir}. The
+default is to take the directory name from
+the input filename. If no input filename is known a directory named
+@file{GPGARCH} is used.
+
+@item --files-from @var{file}
+@itemx -T @var{file}
+Take the file names to work from the file @var{file}; one file per
+line.
+
+@item --null
+@opindex null
+Modify option @option{--files-from} to use a binary nul instead of a
+linefeed to separate file names.
+
+@item --openpgp
+@opindex openpgp
+This option has no effect becuase OpenPGP encryption and signing is
+the default.
+
+@item --cms
+@opindex cms
+This option is reserved and shall not be used. It will eventually be
+used to encrypt or sign using the CMS protocol; but that is not yet
+implemented.
+
+
+@item --set-filename @var{file}
+@opindex set-filename
+Use the last component of @var{file} as the output directory. The
+default is to take the directory name from the input filename. If no
+input filename is known a directory named @file{GPGARCH} is used.
+This option is deprecated in favor of option @option{--directory}.
@item --gpg @var{gpgcmd}
@opindex gpg
Use the specified command @var{gpgcmd} instead of @command{gpg}.
@item --gpg-args @var{args}
@opindex gpg-args
-Pass the specified options to @command{gpg}.
-
-@item --tar @var{tarcmd}
-@opindex tar
-Use the specified command @var{tarcmd} instead of @command{tar}.
+Pass the specified extra options to @command{gpg}.
@item --tar-args @var{args}
@opindex tar-args
-Pass the specified options to @command{tar}.
+Assume @var{args} are standard options of the command @command{tar}
+and parse them. The only supported tar options are "--directory",
+"--files-from", and "--null" This is an obsolete options because those
+supported tar options can also be given directly.
@item --version
@opindex version
Print version of the program and exit.
@item --help
@opindex help
Display a brief help page and exit.
@end table
@mansect diagnostics
@noindent
The program returns 0 if everything was fine, 1 otherwise.
@mansect examples
@ifclear isman
@noindent
Some examples:
@end ifclear
@noindent
Encrypt the contents of directory @file{mydocs} for user Bob to file
@file{test1}:
@example
-gpg-zip --encrypt --output test1 --gpg-args -r Bob mydocs
+gpgtar --encrypt --output test1 -r Bob mydocs
@end example
@noindent
List the contents of archive @file{test1}:
@example
-gpg-zip --list-archive test1
+gpgtar --list-archive test1
@end example
@mansect see also
@ifset isman
@command{gpg}(1),
@command{tar}(1),
@end ifset
@include see-also-note.texi
diff --git a/g10/getkey.c b/g10/getkey.c
index 7061f51eb..0a741cb2d 100644
--- a/g10/getkey.c
+++ b/g10/getkey.c
@@ -1,4502 +1,4503 @@
/* getkey.c - Get a key from the database
* Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
* 2007, 2008, 2010 Free Software Foundation, Inc.
* Copyright (C) 2015, 2016 g10 Code GmbH
*
* This file is part of GnuPG.
*
* GnuPG is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 3 of the License, or
* (at your option) any later version.
*
* GnuPG is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses/>.
*/
#include <config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include "gpg.h"
#include "../common/util.h"
#include "packet.h"
#include "../common/iobuf.h"
#include "keydb.h"
#include "options.h"
#include "main.h"
#include "trustdb.h"
#include "../common/i18n.h"
#include "keyserver-internal.h"
#include "call-agent.h"
#include "../common/host2net.h"
#include "../common/mbox-util.h"
#include "../common/status.h"
#define MAX_PK_CACHE_ENTRIES PK_UID_CACHE_SIZE
#define MAX_UID_CACHE_ENTRIES PK_UID_CACHE_SIZE
#if MAX_PK_CACHE_ENTRIES < 2
#error We need the cache for key creation
#endif
/* Flags values returned by the lookup code. Note that the values are
* directly used by the KEY_CONSIDERED status line. */
#define LOOKUP_NOT_SELECTED (1<<0)
#define LOOKUP_ALL_SUBKEYS_EXPIRED (1<<1) /* or revoked */
/* A context object used by the lookup functions. */
struct getkey_ctx_s
{
/* Part of the search criteria: whether the search is an exact
search or not. A search that is exact requires that a key or
subkey meet all of the specified criteria. A search that is not
exact allows selecting a different key or subkey from the
keyblock that matched the critera. Further, an exact search
returns the key or subkey that matched whereas a non-exact search
typically returns the primary key. See finish_lookup for
details. */
int exact;
/* Part of the search criteria: Whether the caller only wants keys
with an available secret key. This is used by getkey_next to get
the next result with the same initial criteria. */
int want_secret;
/* Part of the search criteria: The type of the requested key. A
mask of PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT.
If non-zero, then for a key to match, it must implement one of
the required uses. */
int req_usage;
/* The database handle. */
KEYDB_HANDLE kr_handle;
/* Whether we should call xfree() on the context when the context is
released using getkey_end()). */
int not_allocated;
/* This variable is used as backing store for strings which have
their address used in ITEMS. */
strlist_t extra_list;
/* Part of the search criteria: The low-level search specification
as passed to keydb_search. */
int nitems;
/* This must be the last element in the structure. When we allocate
the structure, we allocate it so that ITEMS can hold NITEMS. */
KEYDB_SEARCH_DESC items[1];
};
#if 0
static struct
{
int any;
int okay_count;
int nokey_count;
int error_count;
} lkup_stats[21];
#endif
typedef struct keyid_list
{
struct keyid_list *next;
char fpr[MAX_FINGERPRINT_LEN];
u32 keyid[2];
} *keyid_list_t;
#if MAX_PK_CACHE_ENTRIES
typedef struct pk_cache_entry
{
struct pk_cache_entry *next;
u32 keyid[2];
PKT_public_key *pk;
} *pk_cache_entry_t;
static pk_cache_entry_t pk_cache;
static int pk_cache_entries; /* Number of entries in pk cache. */
static int pk_cache_disabled;
#endif
#if MAX_UID_CACHE_ENTRIES < 5
#error we really need the userid cache
#endif
typedef struct user_id_db
{
struct user_id_db *next;
keyid_list_t keyids;
int len;
char name[1];
} *user_id_db_t;
static user_id_db_t user_id_db;
static int uid_cache_entries; /* Number of entries in uid cache. */
static void merge_selfsigs (ctrl_t ctrl, kbnode_t keyblock);
static int lookup (ctrl_t ctrl, getkey_ctx_t ctx, int want_secret,
kbnode_t *ret_keyblock, kbnode_t *ret_found_key);
static kbnode_t finish_lookup (kbnode_t keyblock,
unsigned int req_usage, int want_exact,
int want_secret, unsigned int *r_flags);
static void print_status_key_considered (kbnode_t keyblock, unsigned int flags);
#if 0
static void
print_stats ()
{
int i;
for (i = 0; i < DIM (lkup_stats); i++)
{
if (lkup_stats[i].any)
es_fprintf (es_stderr,
"lookup stats: mode=%-2d ok=%-6d nokey=%-6d err=%-6d\n",
i,
lkup_stats[i].okay_count,
lkup_stats[i].nokey_count, lkup_stats[i].error_count);
}
}
#endif
/* Cache a copy of a public key in the public key cache. PK is not
* cached if caching is disabled (via getkey_disable_caches), if
* PK->FLAGS.DONT_CACHE is set, we don't know how to derive a key id
* from the public key (e.g., unsupported algorithm), or a key with
* the key id is already in the cache.
*
* The public key packet is copied into the cache using
* copy_public_key. Thus, any secret parts are not copied, for
* instance.
*
* This cache is filled by get_pubkey and is read by get_pubkey and
* get_pubkey_fast. */
void
cache_public_key (PKT_public_key * pk)
{
#if MAX_PK_CACHE_ENTRIES
pk_cache_entry_t ce, ce2;
u32 keyid[2];
if (pk_cache_disabled)
return;
if (pk->flags.dont_cache)
return;
if (is_ELGAMAL (pk->pubkey_algo)
|| pk->pubkey_algo == PUBKEY_ALGO_DSA
|| pk->pubkey_algo == PUBKEY_ALGO_ECDSA
|| pk->pubkey_algo == PUBKEY_ALGO_EDDSA
|| pk->pubkey_algo == PUBKEY_ALGO_ECDH
|| is_RSA (pk->pubkey_algo))
{
keyid_from_pk (pk, keyid);
}
else
return; /* Don't know how to get the keyid. */
for (ce = pk_cache; ce; ce = ce->next)
if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1])
{
if (DBG_CACHE)
log_debug ("cache_public_key: already in cache\n");
return;
}
if (pk_cache_entries >= MAX_PK_CACHE_ENTRIES)
{
int n;
/* Remove the last 50% of the entries. */
for (ce = pk_cache, n = 0; ce && n < pk_cache_entries/2; n++)
ce = ce->next;
if (ce && ce != pk_cache && ce->next)
{
ce2 = ce->next;
ce->next = NULL;
ce = ce2;
for (; ce; ce = ce2)
{
ce2 = ce->next;
free_public_key (ce->pk);
xfree (ce);
pk_cache_entries--;
}
}
log_assert (pk_cache_entries < MAX_PK_CACHE_ENTRIES);
}
pk_cache_entries++;
ce = xmalloc (sizeof *ce);
ce->next = pk_cache;
pk_cache = ce;
ce->pk = copy_public_key (NULL, pk);
ce->keyid[0] = keyid[0];
ce->keyid[1] = keyid[1];
#endif
}
/* Return a const utf-8 string with the text "[User ID not found]".
This function is required so that we don't need to switch gettext's
encoding temporary. */
static const char *
user_id_not_found_utf8 (void)
{
static char *text;
if (!text)
text = native_to_utf8 (_("[User ID not found]"));
return text;
}
/* Return the user ID from the given keyblock.
* We use the primary uid flag which has been set by the merge_selfsigs
* function. The returned value is only valid as long as the given
* keyblock is not changed. */
static const char *
get_primary_uid (KBNODE keyblock, size_t * uidlen)
{
KBNODE k;
const char *s;
for (k = keyblock; k; k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID
&& !k->pkt->pkt.user_id->attrib_data
&& k->pkt->pkt.user_id->flags.primary)
{
*uidlen = k->pkt->pkt.user_id->len;
return k->pkt->pkt.user_id->name;
}
}
s = user_id_not_found_utf8 ();
*uidlen = strlen (s);
return s;
}
static void
release_keyid_list (keyid_list_t k)
{
while (k)
{
keyid_list_t k2 = k->next;
xfree (k);
k = k2;
}
}
/****************
* Store the association of keyid and userid
* Feed only public keys to this function.
*/
static void
cache_user_id (KBNODE keyblock)
{
user_id_db_t r;
const char *uid;
size_t uidlen;
keyid_list_t keyids = NULL;
KBNODE k;
for (k = keyblock; k; k = k->next)
{
if (k->pkt->pkttype == PKT_PUBLIC_KEY
|| k->pkt->pkttype == PKT_PUBLIC_SUBKEY)
{
keyid_list_t a = xmalloc_clear (sizeof *a);
/* Hmmm: For a long list of keyids it might be an advantage
* to append the keys. */
fingerprint_from_pk (k->pkt->pkt.public_key, a->fpr, NULL);
keyid_from_pk (k->pkt->pkt.public_key, a->keyid);
/* First check for duplicates. */
for (r = user_id_db; r; r = r->next)
{
keyid_list_t b;
for (b = r->keyids; b; b = b->next)
{
if (!memcmp (b->fpr, a->fpr, MAX_FINGERPRINT_LEN))
{
if (DBG_CACHE)
log_debug ("cache_user_id: already in cache\n");
release_keyid_list (keyids);
xfree (a);
return;
}
}
}
/* Now put it into the cache. */
a->next = keyids;
keyids = a;
}
}
if (!keyids)
BUG (); /* No key no fun. */
uid = get_primary_uid (keyblock, &uidlen);
if (uid_cache_entries >= MAX_UID_CACHE_ENTRIES)
{
/* fixme: use another algorithm to free some cache slots */
r = user_id_db;
user_id_db = r->next;
release_keyid_list (r->keyids);
xfree (r);
uid_cache_entries--;
}
r = xmalloc (sizeof *r + uidlen - 1);
r->keyids = keyids;
r->len = uidlen;
memcpy (r->name, uid, r->len);
r->next = user_id_db;
user_id_db = r;
uid_cache_entries++;
}
/* Disable and drop the public key cache (which is filled by
cache_public_key and get_pubkey). Note: there is currently no way
to re-enable this cache. */
void
getkey_disable_caches ()
{
#if MAX_PK_CACHE_ENTRIES
{
pk_cache_entry_t ce, ce2;
for (ce = pk_cache; ce; ce = ce2)
{
ce2 = ce->next;
free_public_key (ce->pk);
xfree (ce);
}
pk_cache_disabled = 1;
pk_cache_entries = 0;
pk_cache = NULL;
}
#endif
/* fixme: disable user id cache ? */
}
void
pubkey_free (pubkey_t key)
{
if (key)
{
xfree (key->pk);
release_kbnode (key->keyblock);
xfree (key);
}
}
void
pubkeys_free (pubkey_t keys)
{
while (keys)
{
pubkey_t next = keys->next;
pubkey_free (keys);
keys = next;
}
}
/* Returns all keys that match the search specification SEARCH_TERMS.
This function also checks for and warns about duplicate entries in
the keydb, which can occur if the user has configured multiple
keyrings or keyboxes or if a keyring or keybox was corrupted.
Note: SEARCH_TERMS will not be expanded (i.e., it may not be a
group).
USE is the operation for which the key is required. It must be
either PUBKEY_USAGE_ENC, PUBKEY_USAGE_SIG, PUBKEY_USAGE_CERT or
PUBKEY_USAGE_AUTH.
XXX: Currently, only PUBKEY_USAGE_ENC and PUBKEY_USAGE_SIG are
implemented.
INCLUDE_UNUSABLE indicates whether disabled keys are allowed.
(Recipients specified with --encrypt-to and --hidden-encrypt-to may
be disabled. It is possible to edit disabled keys.)
SOURCE is the context in which SEARCH_TERMS was specified, e.g.,
"--encrypt-to", etc. If this function is called interactively,
then this should be NULL.
If WARN_POSSIBLY_AMBIGUOUS is set, then emits a warning if the user
does not specify a long key id or a fingerprint.
The results are placed in *KEYS. *KEYS must be NULL! */
gpg_error_t
get_pubkeys (ctrl_t ctrl,
char *search_terms, int use, int include_unusable, char *source,
int warn_possibly_ambiguous,
pubkey_t *r_keys)
{
/* We show a warning when a key appears multiple times in the DB.
This can happen for two reasons:
- The user has configured multiple keyrings or keyboxes.
- The keyring or keybox has been corrupted in some way, e.g., a
bug or a random process changing them.
For each duplicate, we only want to show the key once. Hence,
this list. */
static strlist_t key_dups;
/* USE transformed to a string. */
char *use_str;
gpg_error_t err;
KEYDB_SEARCH_DESC desc;
GETKEY_CTX ctx;
pubkey_t results = NULL;
pubkey_t r;
int count;
char fingerprint[2 * MAX_FINGERPRINT_LEN + 1];
if (DBG_LOOKUP)
{
log_debug ("\n");
log_debug ("%s: Checking %s=%s\n",
__func__, source ? source : "user input", search_terms);
}
if (*r_keys)
log_bug ("%s: KEYS should be NULL!\n", __func__);
switch (use)
{
case PUBKEY_USAGE_ENC: use_str = "encrypt"; break;
case PUBKEY_USAGE_SIG: use_str = "sign"; break;
case PUBKEY_USAGE_CERT: use_str = "cetify"; break;
case PUBKEY_USAGE_AUTH: use_str = "authentication"; break;
default: log_bug ("%s: Bad value for USE (%d)\n", __func__, use);
}
if (use == PUBKEY_USAGE_CERT || use == PUBKEY_USAGE_AUTH)
log_bug ("%s: use=%s is unimplemented.\n", __func__, use_str);
err = classify_user_id (search_terms, &desc, 1);
if (err)
{
log_info (_("key \"%s\" not found: %s\n"),
search_terms, gpg_strerror (err));
if (!opt.quiet && source)
log_info (_("(check argument of option '%s')\n"), source);
goto out;
}
if (warn_possibly_ambiguous
&& ! (desc.mode == KEYDB_SEARCH_MODE_LONG_KID
|| desc.mode == KEYDB_SEARCH_MODE_FPR16
|| desc.mode == KEYDB_SEARCH_MODE_FPR20
|| desc.mode == KEYDB_SEARCH_MODE_FPR))
{
log_info (_("Warning: '%s' should be a long key ID or a fingerprint\n"),
search_terms);
if (!opt.quiet && source)
log_info (_("(check argument of option '%s')\n"), source);
}
/* Gather all of the results. */
ctx = NULL;
count = 0;
do
{
PKT_public_key *pk = xmalloc_clear (sizeof *pk);
KBNODE kb;
pk->req_usage = use;
if (! ctx)
err = get_pubkey_byname (ctrl, &ctx, pk, search_terms, &kb, NULL,
include_unusable, 1);
else
err = getkey_next (ctrl, ctx, pk, &kb);
if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
/* No more results. */
{
xfree (pk);
break;
}
else if (err)
/* An error (other than "not found"). */
{
log_error (_("error looking up: %s\n"),
gpg_strerror (err));
xfree (pk);
break;
}
/* Another result! */
count ++;
r = xmalloc_clear (sizeof (*r));
r->pk = pk;
r->keyblock = kb;
r->next = results;
results = r;
}
while (ctx);
getkey_end (ctrl, ctx);
if (DBG_LOOKUP)
{
log_debug ("%s resulted in %d matches.\n", search_terms, count);
for (r = results; r; r = r->next)
log_debug (" %s\n",
hexfingerprint (r->keyblock->pkt->pkt.public_key,
fingerprint, sizeof (fingerprint)));
}
if (! results && gpg_err_code (err) == GPG_ERR_NOT_FOUND)
/* No match. */
{
if (DBG_LOOKUP)
log_debug ("%s: '%s' not found.\n", __func__, search_terms);
log_info (_("key \"%s\" not found\n"), search_terms);
if (!opt.quiet && source)
log_info (_("(check argument of option '%s')\n"), source);
goto out;
}
else if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
/* No more matches. */
;
else if (err)
/* Some other error. An error message was already printed
out. Free RESULTS and continue. */
goto out;
/* Check for duplicates. */
if (DBG_LOOKUP)
log_debug ("%s: Checking results of %s='%s' for dups\n",
__func__, source ? source : "user input", search_terms);
count = 0;
for (r = results; r; r = r->next)
{
pubkey_t *prevp;
pubkey_t next;
pubkey_t r2;
int dups = 0;
prevp = &r->next;
next = r->next;
while ((r2 = next))
{
if (cmp_public_keys (r->keyblock->pkt->pkt.public_key,
r2->keyblock->pkt->pkt.public_key) != 0)
/* Not a dup. */
{
prevp = &r2->next;
next = r2->next;
continue;
}
dups ++;
count ++;
/* Remove R2 from the list. */
*prevp = r2->next;
release_kbnode (r2->keyblock);
next = r2->next;
xfree (r2);
}
if (dups)
{
hexfingerprint (r->keyblock->pkt->pkt.public_key,
fingerprint, sizeof fingerprint);
if (! strlist_find (key_dups, fingerprint))
{
char fingerprint_formatted[MAX_FORMATTED_FINGERPRINT_LEN + 1];
log_info (_("Warning: %s appears in the keyring %d times\n"),
format_hexfingerprint (fingerprint,
fingerprint_formatted,
sizeof fingerprint_formatted),
1 + dups);
add_to_strlist (&key_dups, fingerprint);
}
}
}
if (DBG_LOOKUP && count)
{
log_debug ("After removing %d dups:\n", count);
for (r = results, count = 0; r; r = r->next)
log_debug (" %d: %s\n",
count,
hexfingerprint (r->keyblock->pkt->pkt.public_key,
fingerprint, sizeof fingerprint));
}
out:
if (err)
pubkeys_free (results);
else
*r_keys = results;
return err;
}
static void
pk_from_block (PKT_public_key *pk, kbnode_t keyblock, kbnode_t found_key)
{
kbnode_t a = found_key ? found_key : keyblock;
log_assert (a->pkt->pkttype == PKT_PUBLIC_KEY
|| a->pkt->pkttype == PKT_PUBLIC_SUBKEY);
copy_public_key (pk, a->pkt->pkt.public_key);
}
/* Return the public key with the key id KEYID and store it at PK.
* The resources in *PK should be released using
* release_public_key_parts(). This function also stores a copy of
* the public key in the user id cache (see cache_public_key).
*
* If PK is NULL, this function just stores the public key in the
* cache and returns the usual return code.
*
* PK->REQ_USAGE (which is a mask of PUBKEY_USAGE_SIG,
* PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT) is passed through to the
* lookup function. If this is non-zero, only keys with the specified
* usage will be returned. As such, it is essential that
* PK->REQ_USAGE be correctly initialized!
*
* Returns 0 on success, GPG_ERR_NO_PUBKEY if there is no public key
* with the specified key id, or another error code if an error
* occurs.
*
* If the data was not read from the cache, then the self-signed data
* has definitely been merged into the public key using
* merge_selfsigs. */
int
get_pubkey (ctrl_t ctrl, PKT_public_key * pk, u32 * keyid)
{
int internal = 0;
int rc = 0;
#if MAX_PK_CACHE_ENTRIES
if (pk)
{
/* Try to get it from the cache. We don't do this when pk is
NULL as it does not guarantee that the user IDs are
cached. */
pk_cache_entry_t ce;
for (ce = pk_cache; ce; ce = ce->next)
{
if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1])
/* XXX: We don't check PK->REQ_USAGE here, but if we don't
read from the cache, we do check it! */
{
copy_public_key (pk, ce->pk);
return 0;
}
}
}
#endif
/* More init stuff. */
if (!pk)
{
pk = xmalloc_clear (sizeof *pk);
internal++;
}
/* Do a lookup. */
{
struct getkey_ctx_s ctx;
KBNODE kb = NULL;
KBNODE found_key = NULL;
memset (&ctx, 0, sizeof ctx);
ctx.exact = 1; /* Use the key ID exactly as given. */
ctx.not_allocated = 1;
if (ctrl && ctrl->cached_getkey_kdb)
{
ctx.kr_handle = ctrl->cached_getkey_kdb;
ctrl->cached_getkey_kdb = NULL;
keydb_search_reset (ctx.kr_handle);
}
else
{
ctx.kr_handle = keydb_new ();
if (!ctx.kr_handle)
{
rc = gpg_error_from_syserror ();
goto leave;
}
}
ctx.nitems = 1;
ctx.items[0].mode = KEYDB_SEARCH_MODE_LONG_KID;
ctx.items[0].u.kid[0] = keyid[0];
ctx.items[0].u.kid[1] = keyid[1];
ctx.req_usage = pk->req_usage;
rc = lookup (ctrl, &ctx, 0, &kb, &found_key);
if (!rc)
{
pk_from_block (pk, kb, found_key);
}
getkey_end (ctrl, &ctx);
release_kbnode (kb);
}
if (!rc)
goto leave;
rc = GPG_ERR_NO_PUBKEY;
leave:
if (!rc)
cache_public_key (pk);
if (internal)
free_public_key (pk);
return rc;
}
/* Similar to get_pubkey, but it does not take PK->REQ_USAGE into
* account nor does it merge in the self-signed data. This function
* also only considers primary keys. It is intended to be used as a
* quick check of the key to avoid recursion. It should only be used
* in very certain cases. Like get_pubkey and unlike any of the other
* lookup functions, this function also consults the user id cache
* (see cache_public_key).
*
* Return the public key in *PK. The resources in *PK should be
* released using release_public_key_parts(). */
int
get_pubkey_fast (PKT_public_key * pk, u32 * keyid)
{
int rc = 0;
KEYDB_HANDLE hd;
KBNODE keyblock;
u32 pkid[2];
log_assert (pk);
#if MAX_PK_CACHE_ENTRIES
{
/* Try to get it from the cache */
pk_cache_entry_t ce;
for (ce = pk_cache; ce; ce = ce->next)
{
if (ce->keyid[0] == keyid[0] && ce->keyid[1] == keyid[1]
/* Only consider primary keys. */
&& ce->pk->keyid[0] == ce->pk->main_keyid[0]
&& ce->pk->keyid[1] == ce->pk->main_keyid[1])
{
if (pk)
copy_public_key (pk, ce->pk);
return 0;
}
}
}
#endif
hd = keydb_new ();
if (!hd)
return gpg_error_from_syserror ();
rc = keydb_search_kid (hd, keyid);
if (gpg_err_code (rc) == GPG_ERR_NOT_FOUND)
{
keydb_release (hd);
return GPG_ERR_NO_PUBKEY;
}
rc = keydb_get_keyblock (hd, &keyblock);
keydb_release (hd);
if (rc)
{
log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (rc));
return GPG_ERR_NO_PUBKEY;
}
log_assert (keyblock && keyblock->pkt
&& keyblock->pkt->pkttype == PKT_PUBLIC_KEY);
/* We return the primary key. If KEYID matched a subkey, then we
return an error. */
keyid_from_pk (keyblock->pkt->pkt.public_key, pkid);
if (keyid[0] == pkid[0] && keyid[1] == pkid[1])
copy_public_key (pk, keyblock->pkt->pkt.public_key);
else
rc = GPG_ERR_NO_PUBKEY;
release_kbnode (keyblock);
/* Not caching key here since it won't have all of the fields
properly set. */
return rc;
}
/* Return the key block for the key with key id KEYID or NULL, if an
* error occurs. Use release_kbnode() to release the key block.
*
* The self-signed data has already been merged into the public key
* using merge_selfsigs. */
kbnode_t
get_pubkeyblock (ctrl_t ctrl, u32 * keyid)
{
struct getkey_ctx_s ctx;
int rc = 0;
KBNODE keyblock = NULL;
memset (&ctx, 0, sizeof ctx);
/* No need to set exact here because we want the entire block. */
ctx.not_allocated = 1;
ctx.kr_handle = keydb_new ();
if (!ctx.kr_handle)
return NULL;
ctx.nitems = 1;
ctx.items[0].mode = KEYDB_SEARCH_MODE_LONG_KID;
ctx.items[0].u.kid[0] = keyid[0];
ctx.items[0].u.kid[1] = keyid[1];
rc = lookup (ctrl, &ctx, 0, &keyblock, NULL);
getkey_end (ctrl, &ctx);
return rc ? NULL : keyblock;
}
/* Return the public key with the key id KEYID iff the secret key is
* available and store it at PK. The resources should be released
* using release_public_key_parts().
*
* Unlike other lookup functions, PK may not be NULL. PK->REQ_USAGE
* is passed through to the lookup function and is a mask of
* PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. Thus, it
* must be valid! If this is non-zero, only keys with the specified
* usage will be returned.
*
* Returns 0 on success. If a public key with the specified key id is
* not found or a secret key is not available for that public key, an
* error code is returned. Note: this function ignores legacy keys.
* An error code is also return if an error occurs.
*
* The self-signed data has already been merged into the public key
* using merge_selfsigs. */
gpg_error_t
get_seckey (ctrl_t ctrl, PKT_public_key *pk, u32 *keyid)
{
gpg_error_t err;
struct getkey_ctx_s ctx;
kbnode_t keyblock = NULL;
kbnode_t found_key = NULL;
memset (&ctx, 0, sizeof ctx);
ctx.exact = 1; /* Use the key ID exactly as given. */
ctx.not_allocated = 1;
ctx.kr_handle = keydb_new ();
if (!ctx.kr_handle)
return gpg_error_from_syserror ();
ctx.nitems = 1;
ctx.items[0].mode = KEYDB_SEARCH_MODE_LONG_KID;
ctx.items[0].u.kid[0] = keyid[0];
ctx.items[0].u.kid[1] = keyid[1];
ctx.req_usage = pk->req_usage;
err = lookup (ctrl, &ctx, 1, &keyblock, &found_key);
if (!err)
{
pk_from_block (pk, keyblock, found_key);
}
getkey_end (ctrl, &ctx);
release_kbnode (keyblock);
if (!err)
{
err = agent_probe_secret_key (/*ctrl*/NULL, pk);
if (err)
release_public_key_parts (pk);
}
return err;
}
/* Skip unusable keys. A key is unusable if it is revoked, expired or
disabled or if the selected user id is revoked or expired. */
static int
skip_unusable (void *opaque, u32 * keyid, int uid_no)
{
ctrl_t ctrl = opaque;
int unusable = 0;
KBNODE keyblock;
PKT_public_key *pk;
keyblock = get_pubkeyblock (ctrl, keyid);
if (!keyblock)
{
log_error ("error checking usability status of %s\n", keystr (keyid));
goto leave;
}
pk = keyblock->pkt->pkt.public_key;
/* Is the key revoked or expired? */
if (pk->flags.revoked || pk->has_expired)
unusable = 1;
/* Is the user ID in question revoked or expired? */
if (!unusable && uid_no)
{
KBNODE node;
int uids_seen = 0;
for (node = keyblock; node; node = node->next)
{
if (node->pkt->pkttype == PKT_USER_ID)
{
PKT_user_id *user_id = node->pkt->pkt.user_id;
uids_seen ++;
if (uids_seen != uid_no)
continue;
if (user_id->flags.revoked || user_id->flags.expired)
unusable = 1;
break;
}
}
/* If UID_NO is non-zero, then the keyblock better have at least
that many UIDs. */
log_assert (uids_seen == uid_no);
}
if (!unusable)
unusable = pk_is_disabled (pk);
leave:
release_kbnode (keyblock);
return unusable;
}
/* Search for keys matching some criteria.
If RETCTX is not NULL, then the constructed context is returned in
*RETCTX so that getpubkey_next can be used to get subsequent
results. In this case, getkey_end() must be used to free the
search context. If RETCTX is not NULL, then RET_KDBHD must be
NULL.
If NAMELIST is not NULL, then a search query is constructed using
classify_user_id on each of the strings in the list. (Recall: the
database does an OR of the terms, not an AND.) If NAMELIST is
NULL, then all results are returned.
If PK is not NULL, the public key of the first result is returned
in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
set, it is used to filter the search results. See the
documentation for finish_lookup to understand exactly how this is
used. Note: The self-signed data has already been merged into the
public key using merge_selfsigs. Free *PK by calling
release_public_key_parts (or, if PK was allocated using xfree, you
can use free_public_key, which calls release_public_key_parts(PK)
and then xfree(PK)).
If WANT_SECRET is set, then only keys with an available secret key
(either locally or via key registered on a smartcard) are returned.
If INCLUDE_UNUSABLE is set, then unusable keys (see the
documentation for skip_unusable for an exact definition) are
skipped unless they are looked up by key id or by fingerprint.
If RET_KB is not NULL, the keyblock is returned in *RET_KB. This
should be freed using release_kbnode().
If RET_KDBHD is not NULL, then the new database handle used to
conduct the search is returned in *RET_KDBHD. This can be used to
get subsequent results using keydb_search_next. Note: in this
case, no advanced filtering is done for subsequent results (e.g.,
WANT_SECRET and PK->REQ_USAGE are not respected).
This function returns 0 on success. Otherwise, an error code is
returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
(if want_secret is set) is returned if the key is not found. */
static int
key_byname (ctrl_t ctrl, GETKEY_CTX *retctx, strlist_t namelist,
PKT_public_key *pk,
int want_secret, int include_unusable,
KBNODE * ret_kb, KEYDB_HANDLE * ret_kdbhd)
{
int rc = 0;
int n;
strlist_t r;
GETKEY_CTX ctx;
KBNODE help_kb = NULL;
KBNODE found_key = NULL;
if (retctx)
{
/* Reset the returned context in case of error. */
log_assert (!ret_kdbhd); /* Not allowed because the handle is stored
in the context. */
*retctx = NULL;
}
if (ret_kdbhd)
*ret_kdbhd = NULL;
if (!namelist)
/* No search terms: iterate over the whole DB. */
{
ctx = xmalloc_clear (sizeof *ctx);
ctx->nitems = 1;
ctx->items[0].mode = KEYDB_SEARCH_MODE_FIRST;
if (!include_unusable)
{
ctx->items[0].skipfnc = skip_unusable;
ctx->items[0].skipfncvalue = ctrl;
}
}
else
{
/* Build the search context. */
for (n = 0, r = namelist; r; r = r->next)
n++;
/* CTX has space for a single search term at the end. Thus, we
need to allocate sizeof *CTX plus (n - 1) sizeof
CTX->ITEMS. */
ctx = xmalloc_clear (sizeof *ctx + (n - 1) * sizeof ctx->items);
ctx->nitems = n;
for (n = 0, r = namelist; r; r = r->next, n++)
{
gpg_error_t err;
err = classify_user_id (r->d, &ctx->items[n], 1);
if (ctx->items[n].exact)
ctx->exact = 1;
if (err)
{
xfree (ctx);
return gpg_err_code (err); /* FIXME: remove gpg_err_code. */
}
if (!include_unusable
&& ctx->items[n].mode != KEYDB_SEARCH_MODE_SHORT_KID
&& ctx->items[n].mode != KEYDB_SEARCH_MODE_LONG_KID
&& ctx->items[n].mode != KEYDB_SEARCH_MODE_FPR16
&& ctx->items[n].mode != KEYDB_SEARCH_MODE_FPR20
&& ctx->items[n].mode != KEYDB_SEARCH_MODE_FPR)
{
ctx->items[n].skipfnc = skip_unusable;
ctx->items[n].skipfncvalue = ctrl;
}
}
}
ctx->want_secret = want_secret;
ctx->kr_handle = keydb_new ();
if (!ctx->kr_handle)
{
rc = gpg_error_from_syserror ();
getkey_end (ctrl, ctx);
return rc;
}
if (!ret_kb)
ret_kb = &help_kb;
if (pk)
{
ctx->req_usage = pk->req_usage;
}
rc = lookup (ctrl, ctx, want_secret, ret_kb, &found_key);
if (!rc && pk)
{
pk_from_block (pk, *ret_kb, found_key);
}
release_kbnode (help_kb);
if (retctx) /* Caller wants the context. */
*retctx = ctx;
else
{
if (ret_kdbhd)
{
*ret_kdbhd = ctx->kr_handle;
ctx->kr_handle = NULL;
}
getkey_end (ctrl, ctx);
}
return rc;
}
/* Find a public key identified by NAME.
*
* If name appears to be a valid RFC822 mailbox (i.e., email
* address) and auto key lookup is enabled (no_akl == 0), then the
* specified auto key lookup methods (--auto-key-lookup) are used to
* import the key into the local keyring. Otherwise, just the local
* keyring is consulted.
*
* If RETCTX is not NULL, then the constructed context is returned in
* *RETCTX so that getpubkey_next can be used to get subsequent
* results. In this case, getkey_end() must be used to free the
* search context. If RETCTX is not NULL, then RET_KDBHD must be
* NULL.
*
* If PK is not NULL, the public key of the first result is returned
* in *PK. Note: PK->REQ_USAGE must be valid!!! PK->REQ_USAGE is
* passed through to the lookup function and is a mask of
* PUBKEY_USAGE_SIG, PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. If this
* is non-zero, only keys with the specified usage will be returned.
* Note: The self-signed data has already been merged into the public
* key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xfree, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* NAME is a string, which is turned into a search query using
* classify_user_id.
*
* If RET_KEYBLOCK is not NULL, the keyblock is returned in
* *RET_KEYBLOCK. This should be freed using release_kbnode().
*
* If RET_KDBHD is not NULL, then the new database handle used to
* conduct the search is returned in *RET_KDBHD. This can be used to
* get subsequent results using keydb_search_next or to modify the
* returned record. Note: in this case, no advanced filtering is done
* for subsequent results (e.g., PK->REQ_USAGE is not respected).
* Unlike RETCTX, this is always returned.
*
* If INCLUDE_UNUSABLE is set, then unusable keys (see the
* documentation for skip_unusable for an exact definition) are
* skipped unless they are looked up by key id or by fingerprint.
*
* If NO_AKL is set, then the auto key locate functionality is
* disabled and only the local key ring is considered. Note: the
* local key ring is consulted even if local is not in the
* --auto-key-locate option list!
*
* This function returns 0 on success. Otherwise, an error code is
* returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
* (if want_secret is set) is returned if the key is not found. */
int
get_pubkey_byname (ctrl_t ctrl, GETKEY_CTX * retctx, PKT_public_key * pk,
const char *name, KBNODE * ret_keyblock,
KEYDB_HANDLE * ret_kdbhd, int include_unusable, int no_akl)
{
int rc;
strlist_t namelist = NULL;
struct akl *akl;
int is_mbox;
int nodefault = 0;
int anylocalfirst = 0;
/* If RETCTX is not NULL, then RET_KDBHD must be NULL. */
log_assert (retctx == NULL || ret_kdbhd == NULL);
if (retctx)
*retctx = NULL;
/* Does NAME appear to be a mailbox (mail address)? */
is_mbox = is_valid_mailbox (name);
/* The auto-key-locate feature works as follows: there are a number
* of methods to look up keys. By default, the local keyring is
* tried first. Then, each method listed in the --auto-key-locate is
* tried in the order it appears.
*
* This can be changed as follows:
*
* - if nodefault appears anywhere in the list of options, then
* the local keyring is not tried first, or,
*
* - if local appears anywhere in the list of options, then the
* local keyring is not tried first, but in the order in which
* it was listed in the --auto-key-locate option.
*
* Note: we only save the search context in RETCTX if the local
* method is the first method tried (either explicitly or
* implicitly). */
if (!no_akl)
{
/* auto-key-locate is enabled. */
/* nodefault is true if "nodefault" or "local" appear. */
for (akl = opt.auto_key_locate; akl; akl = akl->next)
if (akl->type == AKL_NODEFAULT || akl->type == AKL_LOCAL)
{
nodefault = 1;
break;
}
/* anylocalfirst is true if "local" appears before any other
search methods (except "nodefault"). */
for (akl = opt.auto_key_locate; akl; akl = akl->next)
if (akl->type != AKL_NODEFAULT)
{
if (akl->type == AKL_LOCAL)
anylocalfirst = 1;
break;
}
}
if (!nodefault)
{
/* "nodefault" didn't occur. Thus, "local" is implicitly the
* first method to try. */
anylocalfirst = 1;
}
if (nodefault && is_mbox)
{
/* Either "nodefault" or "local" (explicitly) appeared in the
* auto key locate list and NAME appears to be an email address.
* Don't try the local keyring. */
rc = GPG_ERR_NO_PUBKEY;
}
else
{
/* Either "nodefault" and "local" don't appear in the auto key
* locate list (in which case we try the local keyring first) or
* NAME does not appear to be an email address (in which case we
* only try the local keyring). In this case, lookup NAME in
* the local keyring. */
add_to_strlist (&namelist, name);
rc = key_byname (ctrl, retctx, namelist, pk, 0,
include_unusable, ret_keyblock, ret_kdbhd);
}
/* If the requested name resembles a valid mailbox and automatic
retrieval has been enabled, we try to import the key. */
if (gpg_err_code (rc) == GPG_ERR_NO_PUBKEY && !no_akl && is_mbox)
{
/* NAME wasn't present in the local keyring (or we didn't try
* the local keyring). Since the auto key locate feature is
* enabled and NAME appears to be an email address, try the auto
* locate feature. */
for (akl = opt.auto_key_locate; akl; akl = akl->next)
{
unsigned char *fpr = NULL;
size_t fpr_len;
int did_akl_local = 0;
int no_fingerprint = 0;
const char *mechanism = "?";
switch (akl->type)
{
case AKL_NODEFAULT:
/* This is a dummy mechanism. */
mechanism = "None";
rc = GPG_ERR_NO_PUBKEY;
break;
case AKL_LOCAL:
mechanism = "Local";
did_akl_local = 1;
if (retctx)
{
getkey_end (ctrl, *retctx);
*retctx = NULL;
}
add_to_strlist (&namelist, name);
rc = key_byname (ctrl, anylocalfirst ? retctx : NULL,
namelist, pk, 0,
include_unusable, ret_keyblock, ret_kdbhd);
break;
case AKL_CERT:
mechanism = "DNS CERT";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_cert (ctrl, name, 0, &fpr, &fpr_len);
glo_ctrl.in_auto_key_retrieve--;
break;
case AKL_PKA:
mechanism = "PKA";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_pka (ctrl, name, &fpr, &fpr_len);
glo_ctrl.in_auto_key_retrieve--;
break;
case AKL_DANE:
mechanism = "DANE";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_cert (ctrl, name, 1, &fpr, &fpr_len);
glo_ctrl.in_auto_key_retrieve--;
break;
case AKL_WKD:
mechanism = "WKD";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_wkd (ctrl, name, 0, &fpr, &fpr_len);
glo_ctrl.in_auto_key_retrieve--;
break;
case AKL_LDAP:
mechanism = "LDAP";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_ldap (ctrl, name, &fpr, &fpr_len);
glo_ctrl.in_auto_key_retrieve--;
break;
case AKL_KEYSERVER:
/* Strictly speaking, we don't need to only use a valid
* mailbox for the getname search, but it helps cut down
* on the problem of searching for something like "john"
* and getting a whole lot of keys back. */
if (keyserver_any_configured (ctrl))
{
mechanism = "keyserver";
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_name (ctrl, name, &fpr, &fpr_len,
opt.keyserver);
glo_ctrl.in_auto_key_retrieve--;
}
else
{
mechanism = "Unconfigured keyserver";
rc = GPG_ERR_NO_PUBKEY;
}
break;
case AKL_SPEC:
{
struct keyserver_spec *keyserver;
mechanism = akl->spec->uri;
keyserver = keyserver_match (akl->spec);
glo_ctrl.in_auto_key_retrieve++;
rc = keyserver_import_name (ctrl,
name, &fpr, &fpr_len, keyserver);
glo_ctrl.in_auto_key_retrieve--;
}
break;
}
/* Use the fingerprint of the key that we actually fetched.
* This helps prevent problems where the key that we fetched
* doesn't have the same name that we used to fetch it. In
* the case of CERT and PKA, this is an actual security
* requirement as the URL might point to a key put in by an
* attacker. By forcing the use of the fingerprint, we
* won't use the attacker's key here. */
if (!rc && fpr)
{
char fpr_string[MAX_FINGERPRINT_LEN * 2 + 1];
log_assert (fpr_len <= MAX_FINGERPRINT_LEN);
free_strlist (namelist);
namelist = NULL;
bin2hex (fpr, fpr_len, fpr_string);
if (opt.verbose)
log_info ("auto-key-locate found fingerprint %s\n",
fpr_string);
add_to_strlist (&namelist, fpr_string);
}
else if (!rc && !fpr && !did_akl_local)
{ /* The acquisition method said no failure occurred, but
* it didn't return a fingerprint. That's a failure. */
no_fingerprint = 1;
rc = GPG_ERR_NO_PUBKEY;
}
xfree (fpr);
fpr = NULL;
if (!rc && !did_akl_local)
{ /* There was no error and we didn't do a local lookup.
* This means that we imported a key into the local
* keyring. Try to read the imported key from the
* keyring. */
if (retctx)
{
getkey_end (ctrl, *retctx);
*retctx = NULL;
}
rc = key_byname (ctrl, anylocalfirst ? retctx : NULL,
namelist, pk, 0,
include_unusable, ret_keyblock, ret_kdbhd);
}
if (!rc)
{
/* Key found. */
- log_info (_("automatically retrieved '%s' via %s\n"),
- name, mechanism);
+ if (opt.verbose)
+ log_info (_("automatically retrieved '%s' via %s\n"),
+ name, mechanism);
break;
}
if (gpg_err_code (rc) != GPG_ERR_NO_PUBKEY
|| opt.verbose || no_fingerprint)
log_info (_("error retrieving '%s' via %s: %s\n"),
name, mechanism,
no_fingerprint ? _("No fingerprint") : gpg_strerror (rc));
}
}
if (rc && retctx)
{
getkey_end (ctrl, *retctx);
*retctx = NULL;
}
if (retctx && *retctx)
{
log_assert (!(*retctx)->extra_list);
(*retctx)->extra_list = namelist;
}
else
free_strlist (namelist);
return rc;
}
/* Comparison machinery for get_best_pubkey_byname. */
/* First we have a struct to cache computed information about the key
* in question. */
struct pubkey_cmp_cookie
{
int valid; /* Is this cookie valid? */
PKT_public_key key; /* The key. */
PKT_user_id *uid; /* The matching UID packet. */
unsigned int validity; /* Computed validity of (KEY, UID). */
u32 creation_time; /* Creation time of the newest subkey
capable of encryption. */
};
/* Then we have a series of helper functions. */
static int
key_is_ok (const PKT_public_key *key)
{
return (! key->has_expired && ! key->flags.revoked
&& key->flags.valid && ! key->flags.disabled);
}
static int
uid_is_ok (const PKT_public_key *key, const PKT_user_id *uid)
{
return key_is_ok (key) && ! uid->flags.revoked;
}
static int
subkey_is_ok (const PKT_public_key *sub)
{
return ! sub->flags.revoked && sub->flags.valid && ! sub->flags.disabled;
}
/* Finally this function compares a NEW key to the former candidate
* OLD. Returns < 0 if the old key is worse, > 0 if the old key is
* better, == 0 if it is a tie. */
static int
pubkey_cmp (ctrl_t ctrl, const char *name, struct pubkey_cmp_cookie *old,
struct pubkey_cmp_cookie *new, KBNODE new_keyblock)
{
kbnode_t n;
new->creation_time = 0;
for (n = find_next_kbnode (new_keyblock, PKT_PUBLIC_SUBKEY);
n; n = find_next_kbnode (n, PKT_PUBLIC_SUBKEY))
{
PKT_public_key *sub = n->pkt->pkt.public_key;
if ((sub->pubkey_usage & PUBKEY_USAGE_ENC) == 0)
continue;
if (! subkey_is_ok (sub))
continue;
if (sub->timestamp > new->creation_time)
new->creation_time = sub->timestamp;
}
for (n = find_next_kbnode (new_keyblock, PKT_USER_ID);
n; n = find_next_kbnode (n, PKT_USER_ID))
{
PKT_user_id *uid = n->pkt->pkt.user_id;
char *mbox = mailbox_from_userid (uid->name);
int match = mbox ? strcasecmp (name, mbox) == 0 : 0;
xfree (mbox);
if (! match)
continue;
new->uid = scopy_user_id (uid);
new->validity =
get_validity (ctrl, new_keyblock, &new->key, uid, NULL, 0) & TRUST_MASK;
new->valid = 1;
if (! old->valid)
return -1; /* No OLD key. */
if (! uid_is_ok (&old->key, old->uid) && uid_is_ok (&new->key, uid))
return -1; /* Validity of the NEW key is better. */
if (old->validity < new->validity)
return -1; /* Validity of the NEW key is better. */
if (old->validity == new->validity && uid_is_ok (&new->key, uid)
&& old->creation_time < new->creation_time)
return -1; /* Both keys are of the same validity, but the
NEW key is newer. */
}
/* Stick with the OLD key. */
return 1;
}
/* This function works like get_pubkey_byname, but if the name
* resembles a mail address, the results are ranked and only the best
* result is returned. */
gpg_error_t
get_best_pubkey_byname (ctrl_t ctrl, GETKEY_CTX *retctx, PKT_public_key *pk,
const char *name, KBNODE *ret_keyblock,
int include_unusable, int no_akl)
{
gpg_error_t err;
struct getkey_ctx_s *ctx = NULL;
if (retctx)
*retctx = NULL;
err = get_pubkey_byname (ctrl, &ctx, pk, name, ret_keyblock,
NULL, include_unusable, no_akl);
if (err)
{
getkey_end (ctrl, ctx);
return err;
}
if (is_valid_mailbox (name) && ctx)
{
/* Rank results and return only the most relevant key. */
struct pubkey_cmp_cookie best = { 0 };
struct pubkey_cmp_cookie new = { 0 };
kbnode_t new_keyblock;
while (getkey_next (ctrl, ctx, &new.key, &new_keyblock) == 0)
{
int diff = pubkey_cmp (ctrl, name, &best, &new, new_keyblock);
release_kbnode (new_keyblock);
if (diff < 0)
{
/* New key is better. */
release_public_key_parts (&best.key);
free_user_id (best.uid);
best = new;
}
else if (diff > 0)
{
/* Old key is better. */
release_public_key_parts (&new.key);
free_user_id (new.uid);
new.uid = NULL;
}
else
{
/* A tie. Keep the old key. */
release_public_key_parts (&new.key);
free_user_id (new.uid);
new.uid = NULL;
}
}
getkey_end (ctrl, ctx);
ctx = NULL;
free_user_id (best.uid);
best.uid = NULL;
if (best.valid)
{
if (retctx || ret_keyblock)
{
ctx = xtrycalloc (1, sizeof **retctx);
if (! ctx)
err = gpg_error_from_syserror ();
else
{
ctx->kr_handle = keydb_new ();
if (! ctx->kr_handle)
{
err = gpg_error_from_syserror ();
xfree (ctx);
ctx = NULL;
if (retctx)
*retctx = NULL;
}
else
{
u32 *keyid = pk_keyid (&best.key);
ctx->exact = 1;
ctx->nitems = 1;
ctx->items[0].mode = KEYDB_SEARCH_MODE_LONG_KID;
ctx->items[0].u.kid[0] = keyid[0];
ctx->items[0].u.kid[1] = keyid[1];
if (ret_keyblock)
{
release_kbnode (*ret_keyblock);
*ret_keyblock = NULL;
err = getkey_next (ctrl, ctx, NULL, ret_keyblock);
}
}
}
}
if (pk)
*pk = best.key;
else
release_public_key_parts (&best.key);
}
}
if (err && ctx)
{
getkey_end (ctrl, ctx);
ctx = NULL;
}
if (retctx && ctx)
*retctx = ctx;
else
getkey_end (ctrl, ctx);
return err;
}
/* Get a public key from a file.
*
* PK is the buffer to store the key. The caller needs to make sure
* that PK->REQ_USAGE is valid. PK->REQ_USAGE is passed through to
* the lookup function and is a mask of PUBKEY_USAGE_SIG,
* PUBKEY_USAGE_ENC and PUBKEY_USAGE_CERT. If this is non-zero, only
* keys with the specified usage will be returned.
*
* FNAME is the file name. That file should contain exactly one
* keyblock.
*
* This function returns 0 on success. Otherwise, an error code is
* returned. In particular, GPG_ERR_NO_PUBKEY is returned if the key
* is not found.
*
* The self-signed data has already been merged into the public key
* using merge_selfsigs. The caller must release the content of PK by
* calling release_public_key_parts (or, if PK was malloced, using
* free_public_key).
*/
gpg_error_t
get_pubkey_fromfile (ctrl_t ctrl, PKT_public_key *pk, const char *fname)
{
gpg_error_t err;
kbnode_t keyblock;
kbnode_t found_key;
unsigned int infoflags;
err = read_key_from_file (ctrl, fname, &keyblock);
if (!err)
{
/* Warning: node flag bits 0 and 1 should be preserved by
* merge_selfsigs. FIXME: Check whether this still holds. */
merge_selfsigs (ctrl, keyblock);
found_key = finish_lookup (keyblock, pk->req_usage, 0, 0, &infoflags);
print_status_key_considered (keyblock, infoflags);
if (found_key)
pk_from_block (pk, keyblock, found_key);
else
err = gpg_error (GPG_ERR_UNUSABLE_PUBKEY);
}
release_kbnode (keyblock);
return err;
}
/* Lookup a key with the specified fingerprint.
*
* If PK is not NULL, the public key of the first result is returned
* in *PK. Note: this function does an exact search and thus the
* returned public key may be a subkey rather than the primary key.
* Note: The self-signed data has already been merged into the public
* key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xfree, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* If PK->REQ_USAGE is set, it is used to filter the search results.
* (Thus, if PK is not NULL, PK->REQ_USAGE must be valid!!!) See the
* documentation for finish_lookup to understand exactly how this is
* used.
*
* If R_KEYBLOCK is not NULL, then the first result's keyblock is
* returned in *R_KEYBLOCK. This should be freed using
* release_kbnode().
*
* FPRINT is a byte array whose contents is the fingerprint to use as
* the search term. FPRINT_LEN specifies the length of the
* fingerprint (in bytes). Currently, only 16 and 20-byte
* fingerprints are supported.
*
* FIXME: We should replace this with the _byname function. This can
* be done by creating a userID conforming to the unified fingerprint
* style. */
int
get_pubkey_byfprint (ctrl_t ctrl, PKT_public_key *pk, kbnode_t *r_keyblock,
const byte * fprint, size_t fprint_len)
{
int rc;
if (r_keyblock)
*r_keyblock = NULL;
if (fprint_len == 20 || fprint_len == 16)
{
struct getkey_ctx_s ctx;
KBNODE kb = NULL;
KBNODE found_key = NULL;
memset (&ctx, 0, sizeof ctx);
ctx.exact = 1;
ctx.not_allocated = 1;
ctx.kr_handle = keydb_new ();
if (!ctx.kr_handle)
return gpg_error_from_syserror ();
ctx.nitems = 1;
ctx.items[0].mode = fprint_len == 16 ? KEYDB_SEARCH_MODE_FPR16
: KEYDB_SEARCH_MODE_FPR20;
memcpy (ctx.items[0].u.fpr, fprint, fprint_len);
rc = lookup (ctrl, &ctx, 0, &kb, &found_key);
if (!rc && pk)
pk_from_block (pk, kb, found_key);
if (!rc && r_keyblock)
{
*r_keyblock = kb;
kb = NULL;
}
release_kbnode (kb);
getkey_end (ctrl, &ctx);
}
else
rc = GPG_ERR_GENERAL; /* Oops */
return rc;
}
/* This function is similar to get_pubkey_byfprint, but it doesn't
* merge the self-signed data into the public key and subkeys or into
* the user ids. It also doesn't add the key to the user id cache.
* Further, this function ignores PK->REQ_USAGE.
*
* This function is intended to avoid recursion and, as such, should
* only be used in very specific situations.
*
* Like get_pubkey_byfprint, PK may be NULL. In that case, this
* function effectively just checks for the existence of the key. */
gpg_error_t
get_pubkey_byfprint_fast (PKT_public_key * pk,
const byte * fprint, size_t fprint_len)
{
gpg_error_t err;
KBNODE keyblock;
err = get_keyblock_byfprint_fast (&keyblock, NULL, fprint, fprint_len, 0);
if (!err)
{
if (pk)
copy_public_key (pk, keyblock->pkt->pkt.public_key);
release_kbnode (keyblock);
}
return err;
}
/* This function is similar to get_pubkey_byfprint_fast but returns a
* keydb handle at R_HD and the keyblock at R_KEYBLOCK. R_KEYBLOCK or
* R_HD may be NULL. If LOCK is set the handle has been opend in
* locked mode and keydb_disable_caching () has been called. On error
* R_KEYBLOCK is set to NULL but R_HD must be released by the caller;
* it may have a value of NULL, though. This allows to do an insert
* operation on a locked keydb handle. */
gpg_error_t
get_keyblock_byfprint_fast (kbnode_t *r_keyblock, KEYDB_HANDLE *r_hd,
const byte *fprint, size_t fprint_len, int lock)
{
gpg_error_t err;
KEYDB_HANDLE hd;
kbnode_t keyblock;
byte fprbuf[MAX_FINGERPRINT_LEN];
int i;
if (r_keyblock)
*r_keyblock = NULL;
if (r_hd)
*r_hd = NULL;
for (i = 0; i < MAX_FINGERPRINT_LEN && i < fprint_len; i++)
fprbuf[i] = fprint[i];
while (i < MAX_FINGERPRINT_LEN)
fprbuf[i++] = 0;
hd = keydb_new ();
if (!hd)
return gpg_error_from_syserror ();
if (lock)
{
err = keydb_lock (hd);
if (err)
{
/* If locking did not work, we better don't return a handle
* at all - there was a reason that locking has been
* requested. */
keydb_release (hd);
return err;
}
keydb_disable_caching (hd);
}
/* Fo all other errors we return the handle. */
if (r_hd)
*r_hd = hd;
err = keydb_search_fpr (hd, fprbuf);
if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
{
if (!r_hd)
keydb_release (hd);
return gpg_error (GPG_ERR_NO_PUBKEY);
}
err = keydb_get_keyblock (hd, &keyblock);
if (err)
{
log_error ("keydb_get_keyblock failed: %s\n", gpg_strerror (err));
if (!r_hd)
keydb_release (hd);
return gpg_error (GPG_ERR_NO_PUBKEY);
}
log_assert (keyblock->pkt->pkttype == PKT_PUBLIC_KEY
|| keyblock->pkt->pkttype == PKT_PUBLIC_SUBKEY);
/* Not caching key here since it won't have all of the fields
properly set. */
if (r_keyblock)
*r_keyblock = keyblock;
else
release_kbnode (keyblock);
if (!r_hd)
keydb_release (hd);
return 0;
}
const char *
parse_def_secret_key (ctrl_t ctrl)
{
KEYDB_HANDLE hd = NULL;
strlist_t t;
static int warned;
for (t = opt.def_secret_key; t; t = t->next)
{
gpg_error_t err;
KEYDB_SEARCH_DESC desc;
KBNODE kb;
KBNODE node;
err = classify_user_id (t->d, &desc, 1);
if (err)
{
log_error (_("secret key \"%s\" not found: %s\n"),
t->d, gpg_strerror (err));
if (!opt.quiet)
log_info (_("(check argument of option '%s')\n"), "--default-key");
continue;
}
if (! hd)
{
hd = keydb_new ();
if (!hd)
return NULL;
}
else
keydb_search_reset (hd);
err = keydb_search (hd, &desc, 1, NULL);
if (gpg_err_code (err) == GPG_ERR_NOT_FOUND)
continue;
if (err)
{
log_error (_("key \"%s\" not found: %s\n"), t->d, gpg_strerror (err));
t = NULL;
break;
}
err = keydb_get_keyblock (hd, &kb);
if (err)
{
log_error (_("error reading keyblock: %s\n"),
gpg_strerror (err));
continue;
}
merge_selfsigs (ctrl, kb);
err = gpg_error (GPG_ERR_NO_SECKEY);
node = kb;
do
{
PKT_public_key *pk = node->pkt->pkt.public_key;
/* Check that the key has the signing capability. */
if (! (pk->pubkey_usage & PUBKEY_USAGE_SIG))
continue;
/* Check if the key is valid. */
if (pk->flags.revoked)
{
if (DBG_LOOKUP)
log_debug ("not using %s as default key, %s",
keystr_from_pk (pk), "revoked");
continue;
}
if (pk->has_expired)
{
if (DBG_LOOKUP)
log_debug ("not using %s as default key, %s",
keystr_from_pk (pk), "expired");
continue;
}
if (pk_is_disabled (pk))
{
if (DBG_LOOKUP)
log_debug ("not using %s as default key, %s",
keystr_from_pk (pk), "disabled");
continue;
}
err = agent_probe_secret_key (ctrl, pk);
if (! err)
/* This is a valid key. */
break;
}
while ((node = find_next_kbnode (node, PKT_PUBLIC_SUBKEY)));
release_kbnode (kb);
if (err)
{
if (! warned && ! opt.quiet)
{
log_info (_("Warning: not using '%s' as default key: %s\n"),
t->d, gpg_strerror (GPG_ERR_NO_SECKEY));
print_reported_error (err, GPG_ERR_NO_SECKEY);
}
}
else
{
if (! warned && ! opt.quiet)
log_info (_("using \"%s\" as default secret key for signing\n"),
t->d);
break;
}
}
if (! warned && opt.def_secret_key && ! t)
log_info (_("all values passed to '%s' ignored\n"),
"--default-key");
warned = 1;
if (hd)
keydb_release (hd);
if (t)
return t->d;
return NULL;
}
/* Look up a secret key.
*
* If PK is not NULL, the public key of the first result is returned
* in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
* set, it is used to filter the search results. See the
* documentation for finish_lookup to understand exactly how this is
* used. Note: The self-signed data has already been merged into the
* public key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xfree, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* If --default-key was set, then the specified key is looked up. (In
* this case, the default key is returned even if it is considered
* unusable. See the documentation for skip_unusable for exactly what
* this means.)
*
* Otherwise, this initiates a DB scan that returns all keys that are
* usable (see previous paragraph for exactly what usable means) and
* for which a secret key is available.
*
* This function returns the first match. Additional results can be
* returned using getkey_next. */
gpg_error_t
get_seckey_default (ctrl_t ctrl, PKT_public_key *pk)
{
gpg_error_t err;
strlist_t namelist = NULL;
int include_unusable = 1;
const char *def_secret_key = parse_def_secret_key (ctrl);
if (def_secret_key)
add_to_strlist (&namelist, def_secret_key);
else
include_unusable = 0;
err = key_byname (ctrl, NULL, namelist, pk, 1, include_unusable, NULL, NULL);
free_strlist (namelist);
return err;
}
/* Search for keys matching some criteria.
*
* If RETCTX is not NULL, then the constructed context is returned in
* *RETCTX so that getpubkey_next can be used to get subsequent
* results. In this case, getkey_end() must be used to free the
* search context. If RETCTX is not NULL, then RET_KDBHD must be
* NULL.
*
* If PK is not NULL, the public key of the first result is returned
* in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
* set, it is used to filter the search results. See the
* documentation for finish_lookup to understand exactly how this is
* used. Note: The self-signed data has already been merged into the
* public key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xfree, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* If NAMES is not NULL, then a search query is constructed using
* classify_user_id on each of the strings in the list. (Recall: the
* database does an OR of the terms, not an AND.) If NAMES is
* NULL, then all results are returned.
*
* If WANT_SECRET is set, then only keys with an available secret key
* (either locally or via key registered on a smartcard) are returned.
*
* This function does not skip unusable keys (see the documentation
* for skip_unusable for an exact definition).
*
* If RET_KEYBLOCK is not NULL, the keyblock is returned in
* *RET_KEYBLOCK. This should be freed using release_kbnode().
*
* This function returns 0 on success. Otherwise, an error code is
* returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
* (if want_secret is set) is returned if the key is not found. */
gpg_error_t
getkey_bynames (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
strlist_t names, int want_secret, kbnode_t *ret_keyblock)
{
return key_byname (ctrl, retctx, names, pk, want_secret, 1,
ret_keyblock, NULL);
}
/* Search for one key matching some criteria.
*
* If RETCTX is not NULL, then the constructed context is returned in
* *RETCTX so that getpubkey_next can be used to get subsequent
* results. In this case, getkey_end() must be used to free the
* search context. If RETCTX is not NULL, then RET_KDBHD must be
* NULL.
*
* If PK is not NULL, the public key of the first result is returned
* in *PK. Note: PK->REQ_USAGE must be valid!!! If PK->REQ_USAGE is
* set, it is used to filter the search results. See the
* documentation for finish_lookup to understand exactly how this is
* used. Note: The self-signed data has already been merged into the
* public key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xfree, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* If NAME is not NULL, then a search query is constructed using
* classify_user_id on the string. In this case, even unusable keys
* (see the documentation for skip_unusable for an exact definition of
* unusable) are returned. Otherwise, if --default-key was set, then
* that key is returned (even if it is unusable). If neither of these
* conditions holds, then the first usable key is returned.
*
* If WANT_SECRET is set, then only keys with an available secret key
* (either locally or via key registered on a smartcard) are returned.
*
* This function does not skip unusable keys (see the documentation
* for skip_unusable for an exact definition).
*
* If RET_KEYBLOCK is not NULL, the keyblock is returned in
* *RET_KEYBLOCK. This should be freed using release_kbnode().
*
* This function returns 0 on success. Otherwise, an error code is
* returned. In particular, GPG_ERR_NO_PUBKEY or GPG_ERR_NO_SECKEY
* (if want_secret is set) is returned if the key is not found.
*
* FIXME: We also have the get_pubkey_byname function which has a
* different semantic. Should be merged with this one. */
gpg_error_t
getkey_byname (ctrl_t ctrl, getkey_ctx_t *retctx, PKT_public_key *pk,
const char *name, int want_secret, kbnode_t *ret_keyblock)
{
gpg_error_t err;
strlist_t namelist = NULL;
int with_unusable = 1;
const char *def_secret_key = NULL;
if (want_secret && !name)
def_secret_key = parse_def_secret_key (ctrl);
if (want_secret && !name && def_secret_key)
add_to_strlist (&namelist, def_secret_key);
else if (name)
add_to_strlist (&namelist, name);
else
with_unusable = 0;
err = key_byname (ctrl, retctx, namelist, pk, want_secret, with_unusable,
ret_keyblock, NULL);
/* FIXME: Check that we really return GPG_ERR_NO_SECKEY if
WANT_SECRET has been used. */
free_strlist (namelist);
return err;
}
/* Return the next search result.
*
* If PK is not NULL, the public key of the next result is returned in
* *PK. Note: The self-signed data has already been merged into the
* public key using merge_selfsigs. Free *PK by calling
* release_public_key_parts (or, if PK was allocated using xmalloc, you
* can use free_public_key, which calls release_public_key_parts(PK)
* and then xfree(PK)).
*
* RET_KEYBLOCK can be given as NULL; if it is not NULL it the entire
* found keyblock is returned which must be released with
* release_kbnode. If the function returns an error NULL is stored at
* RET_KEYBLOCK.
*
* The self-signed data has already been merged into the public key
* using merge_selfsigs. */
gpg_error_t
getkey_next (ctrl_t ctrl, getkey_ctx_t ctx,
PKT_public_key *pk, kbnode_t *ret_keyblock)
{
int rc; /* Fixme: Make sure this is proper gpg_error */
KBNODE keyblock = NULL;
KBNODE found_key = NULL;
/* We need to disable the caching so that for an exact key search we
won't get the result back from the cache and thus end up in an
endless loop. The endless loop can occur, because the cache is
used without respecting the current file pointer! */
keydb_disable_caching (ctx->kr_handle);
/* FOUND_KEY is only valid as long as RET_KEYBLOCK is. If the
* caller wants PK, but not RET_KEYBLOCK, we need hand in our own
* keyblock. */
if (pk && ret_keyblock == NULL)
ret_keyblock = &keyblock;
rc = lookup (ctrl, ctx, ctx->want_secret,
ret_keyblock, pk ? &found_key : NULL);
if (!rc && pk)
{
log_assert (found_key);
pk_from_block (pk, NULL, found_key);
release_kbnode (keyblock);
}
return rc;
}
/* Release any resources used by a key listing context. This must be
* called on the context returned by, e.g., getkey_byname. */
void
getkey_end (ctrl_t ctrl, getkey_ctx_t ctx)
{
if (ctx)
{
#ifdef HAVE_W32_SYSTEM
/* FIXME: This creates a big regression for Windows because the
* keyring is only released after the global ctrl is released.
* So if an operation does a getkey and then tries to modify the
* keyring it will fail on Windows with a sharing violation. We
* need to modify all keyring write operations to also take the
* ctrl and close the cached_getkey_kdb handle to make writing
* work. See: GnuPG-bug-id: 3097 */
(void)ctrl;
keydb_release (ctx->kr_handle);
#else /*!HAVE_W32_SYSTEM*/
if (ctrl && !ctrl->cached_getkey_kdb)
ctrl->cached_getkey_kdb = ctx->kr_handle;
else
keydb_release (ctx->kr_handle);
#endif /*!HAVE_W32_SYSTEM*/
free_strlist (ctx->extra_list);
if (!ctx->not_allocated)
xfree (ctx);
}
}
/************************************************
************* Merging stuff ********************
************************************************/
/* Set the mainkey_id fields for all keys in KEYBLOCK. This is
* usually done by merge_selfsigs but at some places we only need the
* main_kid not a full merge. The function also guarantees that all
* pk->keyids are computed. */
void
setup_main_keyids (kbnode_t keyblock)
{
u32 kid[2], mainkid[2];
kbnode_t kbctx, node;
PKT_public_key *pk;
if (keyblock->pkt->pkttype != PKT_PUBLIC_KEY)
BUG ();
pk = keyblock->pkt->pkt.public_key;
keyid_from_pk (pk, mainkid);
for (kbctx=NULL; (node = walk_kbnode (keyblock, &kbctx, 0)); )
{
if (!(node->pkt->pkttype == PKT_PUBLIC_KEY
|| node->pkt->pkttype == PKT_PUBLIC_SUBKEY))
continue;
pk = node->pkt->pkt.public_key;
keyid_from_pk (pk, kid); /* Make sure pk->keyid is set. */
if (!pk->main_keyid[0] && !pk->main_keyid[1])
{
pk->main_keyid[0] = mainkid[0];
pk->main_keyid[1] = mainkid[1];
}
}
}
/* KEYBLOCK corresponds to a public key block. This function merges
* much of the information from the self-signed data into the public
* key, public subkey and user id data structures. If you use the
* high-level search API (e.g., get_pubkey) for looking up key blocks,
* then you don't need to call this function. This function is
* useful, however, if you change the keyblock, e.g., by adding or
* removing a self-signed data packet. */
void
merge_keys_and_selfsig (ctrl_t ctrl, kbnode_t keyblock)
{
if (!keyblock)
;
else if (keyblock->pkt->pkttype == PKT_PUBLIC_KEY)
merge_selfsigs (ctrl, keyblock);
else
log_debug ("FIXME: merging secret key blocks is not anymore available\n");
}
static int
parse_key_usage (PKT_signature * sig)
{
int key_usage = 0;
const byte *p;
size_t n;
byte flags;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_FLAGS, &n);
if (p && n)
{
/* First octet of the keyflags. */
flags = *p;
if (flags & 1)
{
key_usage |= PUBKEY_USAGE_CERT;
flags &= ~1;
}
if (flags & 2)
{
key_usage |= PUBKEY_USAGE_SIG;
flags &= ~2;
}
/* We do not distinguish between encrypting communications and
encrypting storage. */
if (flags & (0x04 | 0x08))
{
key_usage |= PUBKEY_USAGE_ENC;
flags &= ~(0x04 | 0x08);
}
if (flags & 0x20)
{
key_usage |= PUBKEY_USAGE_AUTH;
flags &= ~0x20;
}
if (flags)
key_usage |= PUBKEY_USAGE_UNKNOWN;
if (!key_usage)
key_usage |= PUBKEY_USAGE_NONE;
}
else if (p) /* Key flags of length zero. */
key_usage |= PUBKEY_USAGE_NONE;
/* We set PUBKEY_USAGE_UNKNOWN to indicate that this key has a
capability that we do not handle. This serves to distinguish
between a zero key usage which we handle as the default
capabilities for that algorithm, and a usage that we do not
handle. Likewise we use PUBKEY_USAGE_NONE to indicate that
key_flags have been given but they do not specify any usage. */
return key_usage;
}
/* Apply information from SIGNODE (which is the valid self-signature
* associated with that UID) to the UIDNODE:
* - weather the UID has been revoked
* - assumed creation date of the UID
* - temporary store the keyflags here
* - temporary store the key expiration time here
* - mark whether the primary user ID flag hat been set.
* - store the preferences
*/
static void
fixup_uidnode (KBNODE uidnode, KBNODE signode, u32 keycreated)
{
PKT_user_id *uid = uidnode->pkt->pkt.user_id;
PKT_signature *sig = signode->pkt->pkt.signature;
const byte *p, *sym, *hash, *zip;
size_t n, nsym, nhash, nzip;
sig->flags.chosen_selfsig = 1;/* We chose this one. */
uid->created = 0; /* Not created == invalid. */
if (IS_UID_REV (sig))
{
uid->flags.revoked = 1;
return; /* Has been revoked. */
}
else
uid->flags.revoked = 0;
uid->expiredate = sig->expiredate;
if (sig->flags.expired)
{
uid->flags.expired = 1;
return; /* Has expired. */
}
else
uid->flags.expired = 0;
uid->created = sig->timestamp; /* This one is okay. */
uid->selfsigversion = sig->version;
/* If we got this far, it's not expired :) */
uid->flags.expired = 0;
/* Store the key flags in the helper variable for later processing. */
uid->help_key_usage = parse_key_usage (sig);
/* Ditto for the key expiration. */
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_EXPIRE, NULL);
if (p && buf32_to_u32 (p))
uid->help_key_expire = keycreated + buf32_to_u32 (p);
else
uid->help_key_expire = 0;
/* Set the primary user ID flag - we will later wipe out some
* of them to only have one in our keyblock. */
uid->flags.primary = 0;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_PRIMARY_UID, NULL);
if (p && *p)
uid->flags.primary = 2;
/* We could also query this from the unhashed area if it is not in
* the hased area and then later try to decide which is the better
* there should be no security problem with this.
* For now we only look at the hashed one. */
/* Now build the preferences list. These must come from the
hashed section so nobody can modify the ciphers a key is
willing to accept. */
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_PREF_SYM, &n);
sym = p;
nsym = p ? n : 0;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_PREF_HASH, &n);
hash = p;
nhash = p ? n : 0;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_PREF_COMPR, &n);
zip = p;
nzip = p ? n : 0;
if (uid->prefs)
xfree (uid->prefs);
n = nsym + nhash + nzip;
if (!n)
uid->prefs = NULL;
else
{
uid->prefs = xmalloc (sizeof (*uid->prefs) * (n + 1));
n = 0;
for (; nsym; nsym--, n++)
{
uid->prefs[n].type = PREFTYPE_SYM;
uid->prefs[n].value = *sym++;
}
for (; nhash; nhash--, n++)
{
uid->prefs[n].type = PREFTYPE_HASH;
uid->prefs[n].value = *hash++;
}
for (; nzip; nzip--, n++)
{
uid->prefs[n].type = PREFTYPE_ZIP;
uid->prefs[n].value = *zip++;
}
uid->prefs[n].type = PREFTYPE_NONE; /* End of list marker */
uid->prefs[n].value = 0;
}
/* See whether we have the MDC feature. */
uid->flags.mdc = 0;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_FEATURES, &n);
if (p && n && (p[0] & 0x01))
uid->flags.mdc = 1;
/* And the keyserver modify flag. */
uid->flags.ks_modify = 1;
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KS_FLAGS, &n);
if (p && n && (p[0] & 0x80))
uid->flags.ks_modify = 0;
}
static void
sig_to_revoke_info (PKT_signature * sig, struct revoke_info *rinfo)
{
rinfo->date = sig->timestamp;
rinfo->algo = sig->pubkey_algo;
rinfo->keyid[0] = sig->keyid[0];
rinfo->keyid[1] = sig->keyid[1];
}
/* Given a keyblock, parse the key block and extract various pieces of
* information and save them with the primary key packet and the user
* id packets. For instance, some information is stored in signature
* packets. We find the latest such valid packet (since the user can
* change that information) and copy its contents into the
* PKT_public_key.
*
* Note that R_REVOKED may be set to 0, 1 or 2.
*
* This function fills in the following fields in the primary key's
* keyblock:
*
* main_keyid (computed)
* revkey / numrevkeys (derived from self signed key data)
* flags.valid (whether we have at least 1 self-sig)
* flags.maybe_revoked (whether a designed revoked the key, but
* we are missing the key to check the sig)
* selfsigversion (highest version of any valid self-sig)
* pubkey_usage (derived from most recent self-sig or most
* recent user id)
* has_expired (various sources)
* expiredate (various sources)
*
* See the documentation for fixup_uidnode for how the user id packets
* are modified. In addition to that the primary user id's is_primary
* field is set to 1 and the other user id's is_primary are set to 0.
*/
static void
merge_selfsigs_main (ctrl_t ctrl, kbnode_t keyblock, int *r_revoked,
struct revoke_info *rinfo)
{
PKT_public_key *pk = NULL;
KBNODE k;
u32 kid[2];
u32 sigdate, uiddate, uiddate2;
KBNODE signode, uidnode, uidnode2;
u32 curtime = make_timestamp ();
unsigned int key_usage = 0;
u32 keytimestamp = 0;
u32 key_expire = 0;
int key_expire_seen = 0;
byte sigversion = 0;
*r_revoked = 0;
memset (rinfo, 0, sizeof (*rinfo));
/* Section 11.1 of RFC 4880 determines the order of packets within a
* message. There are three sections, which must occur in the
* following order: the public key, the user ids and user attributes
* and the subkeys. Within each section, each primary packet (e.g.,
* a user id packet) is followed by one or more signature packets,
* which modify that packet. */
/* According to Section 11.1 of RFC 4880, the public key must be the
first packet. Note that parse_keyblock_image ensures that the
first packet is the public key. */
if (keyblock->pkt->pkttype != PKT_PUBLIC_KEY)
BUG ();
pk = keyblock->pkt->pkt.public_key;
keytimestamp = pk->timestamp;
keyid_from_pk (pk, kid);
pk->main_keyid[0] = kid[0];
pk->main_keyid[1] = kid[1];
if (pk->version < 4)
{
/* Before v4 the key packet itself contains the expiration date
* and there was no way to change it, so we start with the one
* from the key packet. */
key_expire = pk->max_expiredate;
key_expire_seen = 1;
}
/* First pass:
*
* - Find the latest direct key self-signature. We assume that the
* newest one overrides all others.
*
* - Determine whether the key has been revoked.
*
* - Gather all revocation keys (unlike other data, we don't just
* take them from the latest self-signed packet).
*
* - Determine max (sig[...]->version).
*/
/* Reset this in case this key was already merged. */
xfree (pk->revkey);
pk->revkey = NULL;
pk->numrevkeys = 0;
signode = NULL;
sigdate = 0; /* Helper variable to find the latest signature. */
/* According to Section 11.1 of RFC 4880, the public key comes first
* and is immediately followed by any signature packets that modify
* it. */
for (k = keyblock;
k && k->pkt->pkttype != PKT_USER_ID
&& k->pkt->pkttype != PKT_ATTRIBUTE
&& k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_SIGNATURE)
{
PKT_signature *sig = k->pkt->pkt.signature;
if (sig->keyid[0] == kid[0] && sig->keyid[1] == kid[1])
{ /* Self sig. */
if (check_key_signature (ctrl, keyblock, k, NULL))
; /* Signature did not verify. */
else if (IS_KEY_REV (sig))
{
/* Key has been revoked - there is no way to
* override such a revocation, so we theoretically
* can stop now. We should not cope with expiration
* times for revocations here because we have to
* assume that an attacker can generate all kinds of
* signatures. However due to the fact that the key
* has been revoked it does not harm either and by
* continuing we gather some more info on that
* key. */
*r_revoked = 1;
sig_to_revoke_info (sig, rinfo);
}
else if (IS_KEY_SIG (sig))
{
/* Add the indicated revocations keys from all
* signatures not just the latest. We do this
* because you need multiple 1F sigs to properly
* handle revocation keys (PGP does it this way, and
* a revocation key could be sensitive and hence in
* a different signature). */
if (sig->revkey)
{
int i;
pk->revkey =
xrealloc (pk->revkey, sizeof (struct revocation_key) *
(pk->numrevkeys + sig->numrevkeys));
for (i = 0; i < sig->numrevkeys; i++)
memcpy (&pk->revkey[pk->numrevkeys++],
&sig->revkey[i],
sizeof (struct revocation_key));
}
if (sig->timestamp >= sigdate)
{ /* This is the latest signature so far. */
if (sig->flags.expired)
; /* Signature has expired - ignore it. */
else
{
sigdate = sig->timestamp;
signode = k;
if (sig->version > sigversion)
sigversion = sig->version;
}
}
}
}
}
}
/* Remove dupes from the revocation keys. */
if (pk->revkey)
{
int i, j, x, changed = 0;
for (i = 0; i < pk->numrevkeys; i++)
{
for (j = i + 1; j < pk->numrevkeys; j++)
{
if (memcmp (&pk->revkey[i], &pk->revkey[j],
sizeof (struct revocation_key)) == 0)
{
/* remove j */
for (x = j; x < pk->numrevkeys - 1; x++)
pk->revkey[x] = pk->revkey[x + 1];
pk->numrevkeys--;
j--;
changed = 1;
}
}
}
if (changed)
pk->revkey = xrealloc (pk->revkey,
pk->numrevkeys *
sizeof (struct revocation_key));
}
/* SIGNODE is the 1F signature packet with the latest creation time.
* Extract some information from it. */
if (signode)
{
/* Some information from a direct key signature take precedence
* over the same information given in UID sigs. */
PKT_signature *sig = signode->pkt->pkt.signature;
const byte *p;
key_usage = parse_key_usage (sig);
p = parse_sig_subpkt (sig->hashed, SIGSUBPKT_KEY_EXPIRE, NULL);
if (p && buf32_to_u32 (p))
{
key_expire = keytimestamp + buf32_to_u32 (p);
key_expire_seen = 1;
}
/* Mark that key as valid: One direct key signature should
* render a key as valid. */
pk->flags.valid = 1;
}
/* Pass 1.5: Look for key revocation signatures that were not made
* by the key (i.e. did a revocation key issue a revocation for
* us?). Only bother to do this if there is a revocation key in the
* first place and we're not revoked already. */
if (!*r_revoked && pk->revkey)
for (k = keyblock; k && k->pkt->pkttype != PKT_USER_ID; k = k->next)
{
if (k->pkt->pkttype == PKT_SIGNATURE)
{
PKT_signature *sig = k->pkt->pkt.signature;
if (IS_KEY_REV (sig) &&
(sig->keyid[0] != kid[0] || sig->keyid[1] != kid[1]))
{
int rc = check_revocation_keys (ctrl, pk, sig);
if (rc == 0)
{
*r_revoked = 2;
sig_to_revoke_info (sig, rinfo);
/* Don't continue checking since we can't be any
* more revoked than this. */
break;
}
else if (gpg_err_code (rc) == GPG_ERR_NO_PUBKEY)
pk->flags.maybe_revoked = 1;
/* A failure here means the sig did not verify, was
* not issued by a revocation key, or a revocation
* key loop was broken. If a revocation key isn't
* findable, however, the key might be revoked and
* we don't know it. */
/* Fixme: In the future handle subkey and cert
* revocations? PGP doesn't, but it's in 2440. */
}
}
}
/* Second pass: Look at the self-signature of all user IDs. */
/* According to RFC 4880 section 11.1, user id and attribute packets
* are in the second section, after the public key packet and before
* the subkey packets. */
signode = uidnode = NULL;
sigdate = 0; /* Helper variable to find the latest signature in one UID. */
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY; k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID || k->pkt->pkttype == PKT_ATTRIBUTE)
{ /* New user id packet. */
/* Apply the data from the most recent self-signed packet to
* the preceding user id packet. */
if (uidnode && signode)
{
fixup_uidnode (uidnode, signode, keytimestamp);
pk->flags.valid = 1;
}
/* Clear SIGNODE. The only relevant self-signed data for
* UIDNODE follows it. */
if (k->pkt->pkttype == PKT_USER_ID)
uidnode = k;
else
uidnode = NULL;
signode = NULL;
sigdate = 0;
}
else if (k->pkt->pkttype == PKT_SIGNATURE && uidnode)
{
PKT_signature *sig = k->pkt->pkt.signature;
if (sig->keyid[0] == kid[0] && sig->keyid[1] == kid[1])
{
if (check_key_signature (ctrl, keyblock, k, NULL))
; /* signature did not verify */
else if ((IS_UID_SIG (sig) || IS_UID_REV (sig))
&& sig->timestamp >= sigdate)
{
/* Note: we allow invalidation of cert revocations
* by a newer signature. An attacker can't use this
* because a key should be revoked with a key revocation.
* The reason why we have to allow for that is that at
* one time an email address may become invalid but later
* the same email address may become valid again (hired,
* fired, hired again). */
sigdate = sig->timestamp;
signode = k;
signode->pkt->pkt.signature->flags.chosen_selfsig = 0;
if (sig->version > sigversion)
sigversion = sig->version;
}
}
}
}
if (uidnode && signode)
{
fixup_uidnode (uidnode, signode, keytimestamp);
pk->flags.valid = 1;
}
/* If the key isn't valid yet, and we have
* --allow-non-selfsigned-uid set, then force it valid. */
if (!pk->flags.valid && opt.allow_non_selfsigned_uid)
{
if (opt.verbose)
log_info (_("Invalid key %s made valid by"
" --allow-non-selfsigned-uid\n"), keystr_from_pk (pk));
pk->flags.valid = 1;
}
/* The key STILL isn't valid, so try and find an ultimately
* trusted signature. */
if (!pk->flags.valid)
{
uidnode = NULL;
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID)
uidnode = k;
else if (k->pkt->pkttype == PKT_SIGNATURE && uidnode)
{
PKT_signature *sig = k->pkt->pkt.signature;
if (sig->keyid[0] != kid[0] || sig->keyid[1] != kid[1])
{
PKT_public_key *ultimate_pk;
ultimate_pk = xmalloc_clear (sizeof (*ultimate_pk));
/* We don't want to use the full get_pubkey to avoid
* infinite recursion in certain cases. There is no
* reason to check that an ultimately trusted key is
* still valid - if it has been revoked the user
* should also remove the ultimate trust flag. */
if (get_pubkey_fast (ultimate_pk, sig->keyid) == 0
&& check_key_signature2 (ctrl,
keyblock, k, ultimate_pk,
NULL, NULL, NULL, NULL) == 0
&& get_ownertrust (ctrl, ultimate_pk) == TRUST_ULTIMATE)
{
free_public_key (ultimate_pk);
pk->flags.valid = 1;
break;
}
free_public_key (ultimate_pk);
}
}
}
}
/* Record the highest selfsig version so we know if this is a v3 key
* through and through, or a v3 key with a v4 selfsig somewhere.
* This is useful in a few places to know if the key must be treated
* as PGP2-style or OpenPGP-style. Note that a selfsig revocation
* with a higher version number will also raise this value. This is
* okay since such a revocation must be issued by the user (i.e. it
* cannot be issued by someone else to modify the key behavior.) */
pk->selfsigversion = sigversion;
/* Now that we had a look at all user IDs we can now get some
* information from those user IDs. */
if (!key_usage)
{
/* Find the latest user ID with key flags set. */
uiddate = 0; /* Helper to find the latest user ID. */
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID)
{
PKT_user_id *uid = k->pkt->pkt.user_id;
if (uid->help_key_usage && uid->created > uiddate)
{
key_usage = uid->help_key_usage;
uiddate = uid->created;
}
}
}
}
if (!key_usage)
{
/* No key flags at all: get it from the algo. */
key_usage = openpgp_pk_algo_usage (pk->pubkey_algo);
}
else
{
/* Check that the usage matches the usage as given by the algo. */
int x = openpgp_pk_algo_usage (pk->pubkey_algo);
if (x) /* Mask it down to the actual allowed usage. */
key_usage &= x;
}
/* Whatever happens, it's a primary key, so it can certify. */
pk->pubkey_usage = key_usage | PUBKEY_USAGE_CERT;
if (!key_expire_seen)
{
/* Find the latest valid user ID with a key expiration set
* Note, that this may be a different one from the above because
* some user IDs may have no expiration date set. */
uiddate = 0;
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID)
{
PKT_user_id *uid = k->pkt->pkt.user_id;
if (uid->help_key_expire && uid->created > uiddate)
{
key_expire = uid->help_key_expire;
uiddate = uid->created;
}
}
}
}
/* Currently only v3 keys have a maximum expiration date, but I'll
* bet v5 keys get this feature again. */
if (key_expire == 0
|| (pk->max_expiredate && key_expire > pk->max_expiredate))
key_expire = pk->max_expiredate;
pk->has_expired = key_expire >= curtime ? 0 : key_expire;
pk->expiredate = key_expire;
/* Fixme: we should see how to get rid of the expiretime fields but
* this needs changes at other places too. */
/* And now find the real primary user ID and delete all others. */
uiddate = uiddate2 = 0;
uidnode = uidnode2 = NULL;
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY; k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID && !k->pkt->pkt.user_id->attrib_data)
{
PKT_user_id *uid = k->pkt->pkt.user_id;
if (uid->flags.primary)
{
if (uid->created > uiddate)
{
uiddate = uid->created;
uidnode = k;
}
else if (uid->created == uiddate && uidnode)
{
/* The dates are equal, so we need to do a different
* (and arbitrary) comparison. This should rarely,
* if ever, happen. It's good to try and guarantee
* that two different GnuPG users with two different
* keyrings at least pick the same primary. */
if (cmp_user_ids (uid, uidnode->pkt->pkt.user_id) > 0)
uidnode = k;
}
}
else
{
if (uid->created > uiddate2)
{
uiddate2 = uid->created;
uidnode2 = k;
}
else if (uid->created == uiddate2 && uidnode2)
{
if (cmp_user_ids (uid, uidnode2->pkt->pkt.user_id) > 0)
uidnode2 = k;
}
}
}
}
if (uidnode)
{
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID &&
!k->pkt->pkt.user_id->attrib_data)
{
PKT_user_id *uid = k->pkt->pkt.user_id;
if (k != uidnode)
uid->flags.primary = 0;
}
}
}
else if (uidnode2)
{
/* None is flagged primary - use the latest user ID we have,
* and disambiguate with the arbitrary packet comparison. */
uidnode2->pkt->pkt.user_id->flags.primary = 1;
}
else
{
/* None of our uids were self-signed, so pick the one that
* sorts first to be the primary. This is the best we can do
* here since there are no self sigs to date the uids. */
uidnode = NULL;
for (k = keyblock; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_USER_ID
&& !k->pkt->pkt.user_id->attrib_data)
{
if (!uidnode)
{
uidnode = k;
uidnode->pkt->pkt.user_id->flags.primary = 1;
continue;
}
else
{
if (cmp_user_ids (k->pkt->pkt.user_id,
uidnode->pkt->pkt.user_id) > 0)
{
uidnode->pkt->pkt.user_id->flags.primary = 0;
uidnode = k;
uidnode->pkt->pkt.user_id->flags.primary = 1;
}
else
{
/* just to be safe: */
k->pkt->pkt.user_id->flags.primary = 0;
}
}
}
}
}
}
/* Convert a buffer to a signature. Useful for 0x19 embedded sigs.
* Caller must free the signature when they are done. */
static PKT_signature *
buf_to_sig (const byte * buf, size_t len)
{
PKT_signature *sig = xmalloc_clear (sizeof (PKT_signature));
IOBUF iobuf = iobuf_temp_with_content (buf, len);
int save_mode = set_packet_list_mode (0);
if (parse_signature (iobuf, PKT_SIGNATURE, len, sig) != 0)
{
xfree (sig);
sig = NULL;
}
set_packet_list_mode (save_mode);
iobuf_close (iobuf);
return sig;
}
/* Use the self-signed data to fill in various fields in subkeys.
*
* KEYBLOCK is the whole keyblock. SUBNODE is the subkey to fill in.
*
* Sets the following fields on the subkey:
*
* main_keyid
* flags.valid if the subkey has a valid self-sig binding
* flags.revoked
* flags.backsig
* pubkey_usage
* has_expired
* expired_date
*
* On this subkey's most revent valid self-signed packet, the
* following field is set:
*
* flags.chosen_selfsig
*/
static void
merge_selfsigs_subkey (ctrl_t ctrl, kbnode_t keyblock, kbnode_t subnode)
{
PKT_public_key *mainpk = NULL, *subpk = NULL;
PKT_signature *sig;
KBNODE k;
u32 mainkid[2];
u32 sigdate = 0;
KBNODE signode;
u32 curtime = make_timestamp ();
unsigned int key_usage = 0;
u32 keytimestamp = 0;
u32 key_expire = 0;
const byte *p;
if (subnode->pkt->pkttype != PKT_PUBLIC_SUBKEY)
BUG ();
mainpk = keyblock->pkt->pkt.public_key;
if (mainpk->version < 4)
return;/* (actually this should never happen) */
keyid_from_pk (mainpk, mainkid);
subpk = subnode->pkt->pkt.public_key;
keytimestamp = subpk->timestamp;
subpk->flags.valid = 0;
subpk->flags.exact = 0;
subpk->main_keyid[0] = mainpk->main_keyid[0];
subpk->main_keyid[1] = mainpk->main_keyid[1];
/* Find the latest key binding self-signature. */
signode = NULL;
sigdate = 0; /* Helper to find the latest signature. */
for (k = subnode->next; k && k->pkt->pkttype != PKT_PUBLIC_SUBKEY;
k = k->next)
{
if (k->pkt->pkttype == PKT_SIGNATURE)
{
sig = k->pkt->pkt.signature;
if (sig->keyid[0] == mainkid[0] && sig->keyid[1] == mainkid[1])
{
if (check_key_signature (ctrl, keyblock, k, NULL))
; /* Signature did not verify. */
else if (IS_SUBKEY_REV (sig))
{
/* Note that this means that the date on a
* revocation sig does not matter - even if the
* binding sig is dated after the revocation sig,
* the