diff options
Diffstat (limited to 'docs/DETAILS')
| -rw-r--r-- | docs/DETAILS | 1225 |
1 files changed, 0 insertions, 1225 deletions
diff --git a/docs/DETAILS b/docs/DETAILS deleted file mode 100644 index d5c5cea..0000000 --- a/docs/DETAILS +++ /dev/null @@ -1,1225 +0,0 @@ -# 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 - -The double =--with-fingerprint= prints the fingerprint for the subkeys -too. Old versions of gpg used a lighly different format and required -the use of the option =--fixed-list-mode= to conform to 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 (only field 10 is used). - - 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 - - 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 sytem. - - 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 usally 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 - seperated 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 been build 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/sbb 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) - -*** Field 16 - Hash algorithm - - For sig records, this is the used hash algorithm. For example: - 2 = SHA-1, 8 = SHA-256. - -** 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 - -*** 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. - - : 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. - - : 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. - - : 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 - - -* 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 prepared to see more - arguments in future versions. - -** General status codes -*** NEWSIG - May be issued right before a signature verification starts. This - is useful to define a context for parsing ERROR status messages. - No arguments are currently defined. - -*** 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 - the letter 'T'. - an ISO 8601 string. The latter can be detected by the presence of - -*** 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 good. This is the same - as GOODSIG but has the fingerprint as the argument. Both status - lines are emitted for a good 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 - class is not defined for CMS and currently set to 0 and 00. - available for CMS signatures. The sig-version as well as the sig - - 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_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 - conventional 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 when the special option --show-session-key is - used. The format is suitable to be passed to the option - --override-session-key - -*** 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 two related status codes to convey notation - data: - - - NOTATION_NAME <name> - - NOTATION_DATA <string> - - <name> and <string> are %XX escaped; the data may be split among - several NOTATION_DATA lines. - -*** 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 argemnts 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. - -** 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 - - 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. - -*** 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 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. - - Note that the term =TRUST_= in the status names is used for - historic reasons; we now speak of validity. - -*** PKA_TRUST_ - This is is one: - - - PKA_TRUST_GOOD <mailbox> - - PKA_TRUST_BAD <mailbox> - - 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> - - <imported_rsa> - - <unchanged> - - <n_uids> - - <n_subk> - - <n_sigs> - - <n_revoc> - - <sec_read> - - <sec_imported> - - <sec_dups> - - <skipped_new_keys> - - <not_imported> - -** 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 - -*** 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 - -*** 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". - -*** SUCCESS [<location>] - Postive confirimation that an operation succeeded. <location> is - optional but if given should not contain spaces. Used only with a - few commands. - -*** 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 - -*** PROGRESS <what> <char> <cur> <total> - 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 - : 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 - -*** 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 - choosen by g13. - -*** PINENTRY_LAUNCHED <pid> - 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. - - -* Unattended key generation - - Please see the GnuPG manual for a description. - - -* 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. - - FIXME: The layout changed, document it here. -#+begin_example - Record type 0: - -------------- - Unused record, can be reused for any purpose. - - Record type 1: - -------------- - Version information for this TrustDB. This is always the first - record of the DB and the only one with type 1. - 1 byte value 1 - 3 bytes 'gpg' magic value - 1 byte Version of the TrustDB (2) - 1 byte marginals needed - 1 byte completes needed - 1 byte max_cert_depth - The three items are used to check whether the cached - validity value from the dir record can be used. - 1 u32 locked flags [not used] - 1 u32 timestamp of trustdb creation - 1 u32 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 timestamp of last validation [currently not used] - (Used to keep track of the time, when this TrustDB was checked - against the pubring) - 1 u32 record number of keyhashtable [currently not used] - 1 u32 first free record - 1 u32 record number of shadow directory hash table [currently not used] - It does not make sense to combine this table with the key table - because the keyid is not in every case a part of the fingerprint. - 1 u32 record number of the trusthashtbale - - - Record type 2: (directory record) - -------------- - Informations about a public key certificate. - These are static values which are never changed without user interaction. - - 1 byte value 2 - 1 byte reserved - 1 u32 LID . (This is simply the record number of this record.) - 1 u32 List of key-records (the first one is the primary key) - 1 u32 List of uid-records - 1 u32 cache record - 1 byte ownertrust - 1 byte dirflag - 1 byte maximum validity of all the user ids - 1 u32 time of last validity check. - 1 u32 Must check when this time has been reached. - (0 = no check required) - - - Record type 3: (key record) - -------------- - Informations about a primary public key. - (This is mainly used to lookup a trust record) - - 1 byte value 3 - 1 byte reserved - 1 u32 LID - 1 u32 next - next key record - 7 bytes reserved - 1 byte keyflags - 1 byte pubkey algorithm - 1 byte length of the fingerprint (in bytes) - 20 bytes fingerprint of the public key - (This is the value we use to identify a key) - - Record type 4: (uid record) - -------------- - Informations about a userid - We do not store the userid but the hash value of the userid because that - is sufficient. - - 1 byte value 4 - 1 byte reserved - 1 u32 LID points to the directory record. - 1 u32 next next userid - 1 u32 pointer to preference record - 1 u32 siglist list of valid signatures - 1 byte uidflags - 1 byte validity of the key calculated over this user id - 20 bytes ripemd160 hash of the username. - - - Record type 5: (pref record) - -------------- - This record type is not anymore used. - - 1 byte value 5 - 1 byte reserved - 1 u32 LID; points to the directory record (and not to the uid record!). - (or 0 for standard preference record) - 1 u32 next - 30 byte preference data - - Record type 6 (sigrec) - ------------- - Used to keep track of key signatures. Self-signatures are not - stored. If a public key is not in the DB, the signature points to - a shadow dir record, which in turn has a list of records which - might be interested in this key (and the signature record here - is one). - - 1 byte value 6 - 1 byte reserved - 1 u32 LID points back to the dir record - 1 u32 next next sigrec of this uid or 0 to indicate the - last sigrec. - 6 times - 1 u32 Local_id of signatures dir or shadow dir record - 1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real - directory record for this) - 1 = valid is set (but may be revoked) - - - - Record type 8: (shadow directory record) - -------------- - This record is used to reserve a LID for a public key. We - need this to create the sig records of other keys, even if we - do not yet have the public key of the signature. - This record (the record number to be more precise) will be reused - as the dir record when we import the real public key. - - 1 byte value 8 - 1 byte reserved - 1 u32 LID (This is simply the record number of this record.) - 2 u32 keyid - 1 byte pubkey algorithm - 3 byte reserved - 1 u32 hintlist A list of records which have references to - this key. This is used for fast access to - signature records which are not yet checked. - Note, that this is only a hint and the actual records - may not anymore hold signature records for that key - but that the code cares about this. - 18 byte reserved - - - - Record Type 10 (hash table) - -------------- - 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. (They can be considered as strong - random numbers.) - What we use is a dynamic multilevel architecture, which combines - hashtables, record lists, and linked lists. - - This record is a hashtable of 256 entries; a special property - is 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). - - When used to hash shadow directory records, a different table is used - and indexed by the keyid. - - 1 byte value 10 - 1 byte reserved - n u32 recnum; n depends on the record length: - n = (reclen-2)/4 which yields 9 for the current record length - of 40 bytes. - - the total number of such record which makes up the table is: - m = (256+n-1) / n - which is 29 for a record length of 40. - - To look up a key we use the first byte of the fingerprint to get - the recnum from this hashtable and look up the addressed record: - - If this record is another hashtable, we use 2nd byte - to index this hash table and so on. - - if this record is a hashlist, we walk all entries - until we found one a matching one. - - if this record is a key record, we compare the - fingerprint and to decide whether it is the requested key; - - - Record type 11 (hash list) - -------------- - see hash table for an explanation. - This is also used for other purposes. - - 1 byte value 11 - 1 byte reserved - 1 u32 next next hash list record - n times n = (reclen-5)/5 - 1 u32 recnum - - For the current record length of 40, n is 7 - - - - Record type 254 (free record) - --------------- - All these records form a linked list of unused records. - 1 byte value 254 - 1 byte reserved (0) - 1 u32 next_free -#+end_example - - -* GNU extensions to the S2K algorithm - - S2K mode 101 is used to identify these extensions. - After the hash algorithm the 3 bytes "GNU" are used to make - clear that these are extensions for GNU, the next bytes gives the - GNU protection mode - 1000. Defined modes are: - - 1001 :: Do not store the secret part at all. - - 1002 :: A stub to access smartcards (not used in 1.2.x) - -* Keyserver helper message format - - 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 - - - -* 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 key server stuff has to be re-thought; - I have some ideas and probably create a white paper. |