--- /dev/null
+ -*- text -*-
+Format of colon listings
+========================
+First an example:
+
+$ gpg --fixed-list-mode --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:
+
+The double --with-fingerprint prints the fingerprint for the subkeys
+too, --fixed-list-mode is themodern listing way printing dates in
+seconds since Epoch and does not merge the first userID with the pub
+record.
+
+
+ 1. Field: 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 (special field format, see below)
+ grp = reserved for gpgsm
+ rvk = revocation key
+ tru = trust database information
+ spk = signature subpacket
+
+ 2. Field: A letter describing the calculated trust. This is a single
+ letter, but be prepared that additional information may follow
+ in some future versions. (not used for secret keys)
+ 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 trust (i.e. no value assigned)
+ q = Undefined trust
+ '-' and 'q' may safely be treated as the same
+ value for most purposes
+ n = Don't trust this key at all
+ m = There is marginal trust in this key
+ f = The key is fully trusted
+ u = The key is ultimately trusted. This often means
+ that the secret key is available, but any key may
+ be marked as ultimately trusted.
+ 3. Field: length of key in bits.
+ 4. Field: Algorithm: 1 = RSA
+ 16 = Elgamal (encrypt only)
+ 17 = DSA (sometimes called DH, sign only)
+ 20 = Elgamal (sign and encrypt - don't use them!)
+ (for other id's see include/cipher.h)
+ 5. Field: KeyID
+ 6. Field: Creation Date (in UTC). For UID and UAT records, this is the
+ self-signature date. Note that the dae 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 format
+ is be scannning for the 'T'.
+ 7. Field: Key or user ID/user attribute expiration date or empty if none.
+ 8. Field: Used for serial number in crt records (used to be the Local-ID).
+ 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.
+ 9. Field: Ownertrust (primary public keys only)
+ This is a single letter, but be prepared that additional
+ information may follow in some future versions. For trust
+ signatures with a regular expression, this is the regular
+ expression value, quoted as in field 10.
+10. Field: User-ID. The value is quoted like a C string to avoid
+ control characters (the colon is quoted "\x3a").
+ This is not used with --fixed-list-mode in gpg.
+ 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
+ An FPR record stores the fingerprint here.
+ The fingerprint of an revocation key is stored here.
+11. Field: Signature class. 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' ist used the same way.
+12. Field: Key capabilities:
+ e = encrypt
+ s = sign
+ c = certify
+ a = authentication
+ 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.
+13. Field: 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
+ keyDB; it is only filled if the issue certificate is
+ available. 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" recods this lists the preferences n the sameway the
+ -edit 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.
+
+14. Field Flag field used in the --edit menu output:
+
+15. Field 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)
+
+All dates are displayed in the format yyyy-mm-dd unless you use the
+option --fixed-list-mode in which case they are displayed as seconds
+since Epoch. More fields may be added later, so parsers should be
+prepared for this. When parsing a number the parser should stop at the
+first non-number character so that additional information can later be
+added.
+
+If field 1 has the tag "pkd", a listing looks like this:
+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)
+
+
+The "tru" trust database records have the fields:
+
+ 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.
+
+ 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.
+
+ 4: Date trustdb was created in seconds since 1/1/1970.
+ 5: Date trustdb will expire in seconds since 1/1/1970.
+
+The "spk" signature subpacket records have the fields:
+
+ 2: Subpacket number as per RFC-2440 and later.
+ 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.
+ 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.
+ 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.
+
+
+Format of the "--status-fd" output
+==================================
+Every line is prefixed with "[GNUPG:] ", followed by a keyword with
+the type of the status line and a some arguments depending on the
+type (maybe none); an application should always be prepared to see
+more arguments in future versions.
+
+
+ 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> <username>
+ The signature with the keyid is good. For each signature only
+ one of the three codes GOODSIG, BADSIG or ERRSIG will be
+ emitted and they may be used as a marker for a new signature.
+ The username is the primary one encoded in UTF-8 and %XX
+ escaped.
+
+ EXPSIG <long keyid> <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.
+
+ EXPKEYSIG <long keyid> <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.
+
+ REVKEYSIG <long keyid> <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.
+
+ BADSIG <long keyid> <username>
+ The signature with the keyid has not been verified okay.
+ The username is the primary one encoded in UTF-8 and %XX
+ escaped.
+
+ ERRSIG <long keyid> <pubkey_algo> <hash_algo> \
+ <sig_class> <timestamp> <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.
+
+ Note, that TIMESTAMP may either be a number with seconds since
+ epoch or an ISO 8601 string which can be detected by the
+ presence of the letter 'T' inside.
+
+ VALIDSIG <fingerprint in hex> <sig_creation_date> <sig-timestamp>
+ <expire-timestamp> <sig-version> <reserved> <pubkey-algo>
+ <hash-algo> <sig-class> <primary-key-fpr>
+
+ The signature with the keyid 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.
+
+ Note, that *-TIMESTAMP may either be a number with seconds
+ since epoch or an ISO 8601 string which can be detected by the
+ presence of the letter 'T' inside.
+
+ 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 with seconds
+ since epoch or an ISO 8601 string which can be detected by the
+ presence of the letter 'T' inside.
+
+
+ ENC_TO <long keyid> <keytype> <keylength>
+ The message is encrypted to this keyid.
+ keytype is the numerical value of the public key algorithm,
+ keylength is the length of the key or 0 if it is not known
+ (which is currently always the case).
+
+ 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.
+ You may see more than one of these status lines.
+
+ UNEXPECTED <what>
+ Unexpected data has been encountered
+ 0 - not further specified 1
+
+
+ TRUST_UNDEFINED <error token>
+ TRUST_NEVER <error token>
+ TRUST_MARGINAL
+ TRUST_FULLY
+ TRUST_ULTIMATE
+ For good signatures one of these status lines are emitted
+ to indicate how trustworthy the signature is. The error token
+ values are currently only emiited by gpgsm.
+
+ SIGEXPIRED
+ This is deprecated in favor of KEYEXPIRED.
+
+ KEYEXPIRED <expire-timestamp>
+ The key has expired. expire-timestamp is the expiration time
+ in seconds after the epoch.
+
+ Note, that TIMESTAMP may either be a number with seconds since
+ epoch or an ISO 8601 string which can be detected by the
+ presence of the letter 'T' inside.
+
+ KEYREVOKED
+ The used key has been revoked by its owner. No arguments yet.
+
+ BADARMOR
+ The ASCII armor is corrupted. No arguments yet.
+
+ RSA_OR_IDEA
+ The IDEA algorithms has been used in the data. A
+ program might want to fallback to another program to handle
+ the data if GnuPG failed. This status message used to be emitted
+ also for RSA but this has been dropped after the RSA patent expired.
+ However we can't change the name of the message.
+
+ SHM_INFO
+ SHM_GET
+ SHM_GET_BOOL
+ SHM_GET_HIDDEN
+
+ GET_BOOL
+ GET_LINE
+ GET_HIDDEN
+ GOT_IT
+
+ NEED_PASSPHRASE <long main keyid> <long 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>
+ 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.
+
+ BAD_PASSPHRASE_PIN
+ Reserved for future use.
+
+ 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.
+
+ NO_PUBKEY <long keyid>
+ NO_SECKEY <long keyid>
+ The key is not available
+
+ 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:
+ 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 <count> <no_user_id> <imported> <imported_rsa> <unchanged>
+ <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported>
+ Final statistics on import process (this is one long line)
+
+ 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_DECRYPTION
+ END_DECRYPTION
+ Mark the start and end of the actual decryption process. These
+ are also emitted when in --list-only mode.
+
+ BEGIN_ENCRYPTION <mdc_method> <sym_algo>
+ END_ENCRYPTION
+ Mark the start and end of the actual encryption process.
+
+ 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. 100/100 may be used to detect the
+ end of operation.
+ Well known values for WHAT:
+ "pk_dsa" - DSA key generation
+ "pk_elg" - Elgamal key generation
+ "primegen" - Prime generation
+ "need_entropy" - Waiting for new entropy in the RNG
+ "file:XXX" - processing file XXX
+ (note that current gpg versions leave out the
+ "file:" prefix).
+ "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.
+
+
+ SIG_CREATED <type> <pubkey algo> <hash algo> <class> <timestamp> <key fpr>
+ A signature has been created using these parameters.
+ type: 'D' = detached
+ 'C' = cleartext
+ 'S' = standard
+ (only the first character should be checked)
+ class: 2 hex digits with the signature class
+
+ Note, that TIMESTAMP may either be a number with seconds since
+ epoch or an ISO 8601 string which can be detected by the
+ presence of the letter 'T' inside.
+
+ KEY_CREATED <type> <fingerprint> [<handle>]
+ A key has been created
+ type: '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.
+
+
+ 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
+
+ NOTATION_NAME <name>
+ NOTATION_DATA <string>
+ name and string are %XX escaped; the data may be splitted
+ among several notation_data lines.
+
+ USERID_HINT <long main keyid> <string>
+ Give a hint about the user ID for a certain keyID.
+
+ POLICY_URL <string>
+ string is %XX escaped
+
+ BEGIN_STREAM
+ END_STREAM
+ Issued by pipemode.
+
+ INV_RECP <reason> <requested_recipient>
+ Issued for each unusable recipient. 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"
+
+ Note that this status is also used for gpgsm's SIGNER command
+ where it relates to signer's of course.
+
+ NO_RECP <reserved>
+ Issued when no recipients are usable.
+
+ ALREADY_SIGNED <long-keyid>
+ Warning: This is experimental and might be removed at any time.
+
+ TRUNCATED <maxno>
+ The output was truncated to MAXNO items. This status code is issued
+ for certain external requests
+
+ ERROR <error location> <error code>
+
+ This is a generic error status message, it might be followed
+ by error location specific data. <error token> and
+ <error_location> should not contain a space. The error code
+ is a either a string commencing with a letter or such string
+ prefix with a numerical error code and an underscore; e.g.:
+ "151011327_EOF"
+
+ ATTRIBUTE <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
+ (1==image). <index>/<count> indicates that this is the Nth
+ 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
+
+ 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.
+ 2 = Request removal of a card.
+ 3 = Card with serialnumber detected
+ 4 = No card available.
+
+
+ PLAINTEXT <format> <timestamp>
+ 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.
+
+ 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.
+
+ SIG_SUBPACKET <type> <flags> <len> <data>
+ This indicates that a signature subpacket was seen. The
+ format is the same as the "spk" record above.
+
+ SC_OP_FAILURE
+ 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.
+
+ 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.
+
+ BACKUP_KEY_CREATED fingerprint fname
+ A backup key named FNAME has been created for the key wityh
+ KEYID.
+
+
+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 2440bis, but 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.
+
+
+Format of the "--list-config" output
+====================================
+
+--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 algorithmdcaiphers
+ this version of GnuPG supports, separated by semicolons. The
+ algorithm numbers are as specified in RFC-2440.
+
+ 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-2440.
+
+ 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-2440.
+
+ 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-2440.
+
+ 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
+
+
+Key generation
+==============
+ Key generation shows progress by printing different characters to
+ stderr:
+ "." Last 10 Miller-Rabin tests failed
+ "+" Miller-Rabin test succeeded
+ "!" Reloading the pool with fresh prime numbers
+ "^" Checking a new value for the generator
+ "<" Size of one factor decreased
+ ">" Size of one factor increased
+
+ The prime number for Elgamal is generated this way:
+
+ 1) Make a prime number q of 160, 200, 240 bits (depending on the keysize)
+ 2) Select the length of the other prime factors to be at least the size
+ of q and calculate the number of prime factors needed
+ 3) Make a pool of prime numbers, each of the length determined in step 2
+ 4) Get a new permutation out of the pool or continue with step 3
+ if we have tested all permutations.
+ 5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1
+ 6) Check that this prime has the correct length (this may change q if
+ it seems not to be possible to make a prime of the desired length)
+ 7) Check whether this is a prime using trial divisions and the
+ Miller-Rabin test.
+ 8) Continue with step 4 if we did not find a prime in step 7.
+ 9) Find a generator for that prime.
+
+ This algorithm is based on Lim and Lee's suggestion from the
+ Crypto '97 proceedings p. 260.
+
+
+Unattended key generation
+=========================
+This feature allows unattended generation of keys controlled by a
+parameter file. To use this feature, you use --gen-key together with
+--batch and feed the parameters either from stdin or from a file given
+on the commandline.
+
+The format of this file is as follows:
+ o Text only, line length is limited to about 1000 chars.
+ o You must use UTF-8 encoding to specify non-ascii characters.
+ o Empty lines are ignored.
+ o Leading and trailing spaces are ignored.
+ o A hash sign as the first non white space character indicates a comment line.
+ o Control statements are indicated by a leading percent sign, the
+ arguments are separated by white space from the keyword.
+ o Parameters are specified by a keyword, followed by a colon. Arguments
+ are separated by white space.
+ o The first parameter must be "Key-Type", control statements
+ may be placed anywhere.
+ o Key generation takes place when either the end of the parameter file
+ is reached, the next "Key-Type" parameter is encountered or at the
+ control statement "%commit"
+ o Control statements:
+ %echo <text>
+ Print <text>.
+ %dry-run
+ Suppress actual key generation (useful for syntax checking).
+ %commit
+ Perform the key generation. An implicit commit is done
+ at the next "Key-Type" parameter.
+ %pubring <filename>
+ %secring <filename>
+ Do not write the key to the default or commandline given
+ keyring but to <filename>. This must be given before the first
+ commit to take place, duplicate specification of the same filename
+ is ignored, the last filename before a commit is used.
+ The filename is used until a new filename is used (at commit points)
+ and all keys are written to that file. If a new filename is given,
+ this file is created (and overwrites an existing one).
+ Both control statements must be given.
+ o The order of the parameters does not matter except for "Key-Type"
+ which must be the first parameter. The parameters are only for the
+ generated keyblock and parameters from previous key generations are not
+ used. Some syntactically checks may be performed.
+ The currently defined parameters are:
+ Key-Type: <algo-number>|<algo-string>
+ Starts a new parameter block by giving the type of the
+ primary key. The algorithm must be capable of signing.
+ This is a required parameter.
+ Key-Length: <length-in-bits>
+ Length of the key in bits. Default is 1024.
+ Key-Usage: <usage-list>
+ Space or comma delimited list of key usage, allowed values are
+ "encrypt" and "sign". This is used to generate the key flags.
+ Please make sure that the algorithm is capable of this usage.
+ Subkey-Type: <algo-number>|<algo-string>
+ This generates a secondary key. Currently only one subkey
+ can be handled.
+ Subkey-Length: <length-in-bits>
+ Length of the subkey in bits. Default is 1024.
+ Subkey-Usage: <usage-list>
+ Similar to Key-Usage.
+ Passphrase: <string>
+ If you want to specify a passphrase for the secret key,
+ enter it here. Default is not to use any passphrase.
+ Name-Real: <string>
+ Name-Comment: <string>
+ Name-Email: <string>
+ The 3 parts of a key. Remember to use UTF-8 here.
+ If you don't give any of them, no user ID is created.
+ Expire-Date: <iso-date>|(<number>[d|w|m|y])
+ Set the expiration date for the key (and the subkey). It
+ may either be entered in ISO date format (2000-08-15) or as
+ number of days, weeks, month or years. Without a letter days
+ are assumed.
+ Preferences: <string>
+ Set the cipher, hash, and compression preference values for
+ this key. This expects the same type of string as "setpref"
+ in the --edit menu.
+ Revoker: <algo>:<fpr> [sensitive]
+ Add a designated revoker to the generated key. Algo is the
+ public key algorithm of the designated revoker (i.e. RSA=1,
+ DSA=17, etc.) Fpr is the fingerprint of the designated
+ revoker. The optional "sensitive" flag marks the designated
+ revoker as sensitive information. Only v4 keys may be
+ designated revokers.
+ Handle: <string>
+ This is an optional parameter only used with the status lines
+ KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100
+ characters and should not contauin spaces. It is useful for
+ batch key generation to associate a key parameter block with a
+ status line.
+
+
+Here is an example:
+$ cat >foo <<EOF
+ %echo Generating a standard key
+ Key-Type: DSA
+ Key-Length: 1024
+ Subkey-Type: ELG-E
+ Subkey-Length: 1024
+ Name-Real: Joe Tester
+ Name-Comment: with stupid passphrase
+ Name-Email: joe@foo.bar
+ Expire-Date: 0
+ Passphrase: abc
+ %pubring foo.pub
+ %secring foo.sec
+ # Do a commit here, so that we can later print "done" :-)
+ %commit
+ %echo done
+EOF
+$ gpg --batch --gen-key foo
+ [...]
+$ gpg --no-default-keyring --secret-keyring ./foo.sec \
+ --keyring ./foo.pub --list-secret-keys
+/home/wk/work/gnupg-stable/scratch/foo.sec
+------------------------------------------
+sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
+ssb 1024g/8F70E2C0 2000-03-09
+
+
+
+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.
+
+ 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
+
+
+
+Packet Headers
+===============
+
+GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header.
+There is one enhancement used with the old style packet headers:
+
+ CTB bits 10, the "packet-length length bits", have values listed in
+ the following table:
+
+ 00 - 1-byte packet-length field
+ 01 - 2-byte packet-length field
+ 10 - 4-byte packet-length field
+ 11 - no packet length supplied, unknown packet length
+
+ As indicated in this table, depending on the packet-length length
+ bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field
+ are a "packet-length field". The packet-length field is a whole
+ number field. The value of the packet-length field is defined to be
+ the value of the whole number field.
+
+ A value of 11 is currently used in one place: on compressed data.
+ That is, a compressed data block currently looks like <A3 01 . . .>,
+ where <A3>, binary 10 1000 11, is an indefinite-length packet. The
+ proper interpretation is "until the end of the enclosing structure",
+ although it should never appear outermost (where the enclosing
+ structure is a file).
+
++ This will be changed with another version, where the new meaning of
++ the value 11 (see below) will also take place.
++
++ A value of 11 for other packets enables a special length encoding,
++ which is used in case, where the length of the following packet can
++ not be determined prior to writing the packet; especially this will
++ be used if large amounts of data are processed in filter mode.
++
++ It works like this: After the CTB (with a length field of 11) a
++ marker field is used, which gives the length of the following datablock.
++ This is a simple 2 byte field (MSB first) containing the amount of data
++ following this field, not including this length field. After this datablock
++ another length field follows, which gives the size of the next datablock.
++ A value of 0 indicates the end of the packet. The maximum size of a
++ data block is limited to 65534, thereby reserving a value of 0xffff for
++ future extensions. These length markers must be inserted into the data
++ stream just before writing the data out.
++
++ This 2 byte field is large enough, because the application must buffer
++ this amount of data to prepend the length marker before writing it out.
++ Data block sizes larger than about 32k doesn't make any sense. Note
++ that this may also be used for compressed data streams, but we must use
++ another packet version to tell the application that it can not assume,
++ that this is the last packet.
+
+
+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)
+
+
+Pipemode
+========
+NOTE: This is deprecated and will be removed in future versions.
+
+This mode can be used to perform multiple operations with one call to
+gpg. It comes handy in cases where you have to verify a lot of
+signatures. Currently we support only detached signatures. This mode
+is a kludge to avoid running gpg n daemon mode and using Unix Domain
+Sockets to pass the data to it. There is no easy portable way to do
+this under Windows, so we use plain old pipes which do work well under
+Windows. Because there is no way to signal multiple EOFs in a pipe we
+have to embed control commands in the data stream: We distinguish
+between a data state and a control state. Initially the system is in
+data state but it won't accept any data. Instead it waits for
+transition to control state which is done by sending a single '@'
+character. While in control state the control command os expected and
+this command is just a single byte after which the system falls back
+to data state (but does not necesary accept data now). The simplest
+control command is a '@' which just inserts this character into the
+data stream.
+
+Here is the format we use for detached signatures:
+"@<" - Begin of new stream
+"@B" - Detached signature follows.
+ This emits a control packet (1,'B')
+<detached_signature>
+"@t" - Signed text follows.
+ This emits the control packet (2, 'B')
+<signed_text>
+"@." - End of operation. The final control packet forces signature
+ verification
+"@>" - End of stream
+
+
+
+
+
+
+Other Notes
+===========
+ * 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.
+
+ * Revocation certificates consist only of the signature packet;
+ "import" knows how to handle this. The rationale behind it is
+ to keep them small.
+
+
+
+
+
+
+
+Keyserver Message Format
+=========================
+
+The keyserver may be contacted by a Unix Domain socket or via TCP.
+
+The format of a request is:
+
+====
+command-tag
+"Content-length:" digits
+CRLF
+=======
+
+Where command-tag is
+
+NOOP
+GET <user-name>
+PUT
+DELETE <user-name>
+
+
+The format of a response is:
+
+======
+"GNUPG/1.0" status-code status-text
+"Content-length:" digits
+CRLF
+============
+followed by <digits> bytes of data
+
+
+Status codes are:
+
+ o 1xx: Informational - Request received, continuing process
+
+ o 2xx: Success - The action was successfully received, understood,
+ and accepted
+
+ o 4xx: Client Error - The request contains bad syntax or cannot be
+ fulfilled
+
+ o 5xx: Server Error - The server failed to fulfill an apparently
+ valid request
+
+
+
+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.
+
projects / firma.git / commitdiff