diff options
Diffstat (limited to 'doc/DETAILS')
| -rw-r--r-- | doc/DETAILS | 1253 |
1 files changed, 1253 insertions, 0 deletions
diff --git a/doc/DETAILS b/doc/DETAILS new file mode 100644 index 0000000..986b908 --- /dev/null +++ b/doc/DETAILS @@ -0,0 +1,1253 @@ + -*- text -*- + +NOTE: The definitive reference is the file from the SVN trunk. + +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. + 4 - signature expected but not found + 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. + + 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. + Without PKA info available or + + 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> [<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. + + 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. + + 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. + + 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. + 5 = No card reader available + + + 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. + + 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 [<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. + + BACKUP_KEY_CREATED fingerprint fname + A backup key named FNAME has been created for the key with + 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", "sign", and "auth". This is used to generate the + key flags. Please make sure that the algorithm is capable of + this usage. Note that OpenPGP requires that all primary keys + are capable of certification, so no matter what usage is given + here, the "cert" flag will be on. If no Key-Usage is + specified, all the allowed usages for that particular + algorithm are used. + 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 contain spaces. It is useful for + batch key generation to associate a key parameter block with a + status line. + Keyserver: <string> + This is an optional parameter that specifies the preferred + keyserver URL for the key. + + +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. + |