diff options
Diffstat (limited to 'doc/DETAILS')
| -rw-r--r-- | doc/DETAILS | 1617 |
1 files changed, 1617 insertions, 0 deletions
diff --git a/doc/DETAILS b/doc/DETAILS new file mode 100644 index 0000000..420f67d --- /dev/null +++ b/doc/DETAILS @@ -0,0 +1,1617 @@ +# 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 + - rvs :: Recocation signature (standalone) [since 2.2.9] + - fpr :: Fingerprint (fingerprint is in field 10) + - fp2 :: SHA-256 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. + + In "sig" records, this field may have one of these values as first + character: + + - ! :: Signature is good. + - - :: Signature is bad. + - ? :: No public key to verify signature or public key is not usable. + - % :: Other error verifying a signature + + More values may be added later. The field may also be empty if + gpg has been invoked in a non-checking mode (--list-sigs) or in a + fast checking mode. Since 2.2.7 '?' will also be printed by the + command --list-sigs if the key is not in the local keyring. + +*** 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. The FPR and FP2 + records store the fingerprints 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. + + "rev" and "rvs" may be followed by a comma and a 2 digit hexnumber + with the revocation reason. + +*** 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", "rev" and "rvs" records, this is the fingerprint of the + key that issued the signature. Note that this may only be filled + if the signature verified correctly. Note also that for various + technical reasons, this fingerprint is only available if + --no-sig-cache is used. Since 2.2.7 this field will also be set + if the key is missing but the signature carries an issuer + fingerprint as meta data. + +*** 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 for this key. + + Valid values are: + + - 8 :: The key is compliant with RFC4880bis + - 23 :: The key is compliant with compliance mode "de-vs". + +*** 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. + +*** Field 21 - Comment + + This is currently only used in "rev" and "rvs" records to carry + the the comment field of the recocation reason. The value 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. + 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> <fpr> + 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 long_keyid_or_fpr if it is available. This is the + case with gpgsm and might eventually also be available for + OpenPGP. The ERRSIG line has FPR filed which is only available + since 2.2.7; that FPR may either be missing or - if the signature + has no fingerprint as meta data. + + 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> [<aead_algo>] + Print information about the symmetric encryption algorithm and the + MDC method. This will be emitted even if the decryption fails. + For an AEAD algorithm AEAD_ALGO is not 0. + +*** 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. The length is only + exact for binary formats; other formats ('t', 'u') may do post + processing like line ending conversion so that the actual number + of bytes written may be differ. + +*** 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 explain 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. Note the arg should in general + not be used because it is better to take it from the ERRSIG + status line which is printed right before this one. + +*** 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. <location> and <error code> may not + contain spaces. The <location> may be used to indicate a class of + warnings. 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". +*** NOTE <location> <error code> [<text>] + This is a generic info status message the same syntax as for + WARNING messages is used. +*** 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 + 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. 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: + + - 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 + - scd_locked :: Waiting for other clients to unlock the scdaemon + + 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. + +** Inter-component codes + Status codes are also used between the components of the GnuPG + system via the Assuan S lines. Some of them are documented here: + +*** PUBKEY_INFO <n> <ubid> + The type of the public key in the following D-lines or + communicated via a pipe. <n> is the value of =enum pubkey_types= + and <ubid> the Unique Blob ID (UBID) which is the fingerprint of + the primary key truncated to 20 octets and formatted in hex. Note + that the keyboxd SEARCH command can be used to lookup the public + key using the <ubid> prefixed with a caret (^). + +*** KEYPAIRINFO <grip> <keyref> [<usage>] [<keytime>] + + This status is emitted by scdaemon and gpg-agent to convey brief + information about keypairs stored on tokens. <grip> is the + hexified keygrip of the key or, if no key is stored, an "X". + <keyref> is the ID of a card's key; for example "OPENPGP.2" for + the second key slot of an OpenPGP card. <usage> is optional and + returns technically possible key usages, this is a string of + single letters describing the usage ('c' for certify, 'e' for + encryption, 's' for signing, 'a' for authentication). A '-' can be + used to tell that usage flags are not conveyed. <keytime> is used + by OpenPGP cards for the stored key creation time. A '-' means no + info available. The format is the usual ISO string are a number + with the seconds since Epoch. +*** MANUFACTURER <n> [<string>] + + This status returns the Manufactorer ID as the unsigned number N. + For OpenPGP this is weel defined; for other cards this is 0. The + name of the manufacturer is also given as <string>; spaces are not + escaped. For PKCS#15 cards <string> is TokenInfo.manufactorerID. + +* 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 :: =flags=. + - 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 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 | + | cardkey | 14 | Existing key from card | + + 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). |