From a5d46a4e38985be540b9127ddcd3d8e21bbecb9a Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Mon, 8 Jun 2015 16:46:11 -0400 Subject: Imported Upstream version 2.0.2 --- docs/DETAILS | 1225 ---------------------------------------------------------- 1 file changed, 1225 deletions(-) delete mode 100644 docs/DETAILS (limited to 'docs/DETAILS') 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 : -uid:f::::::::Werner Koch : -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 - 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 - 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 - 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 - 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 - 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