7 * OpenPGP constants and structures from RFC-2440.
9 * Text from RFC-2440 in comments is
10 * Copyright (C) The Internet Society (1998). All Rights Reserved.
16 #include <rpm/rpmtypes.h>
17 #include <rpm/rpmstring.h>
25 typedef struct DIGEST_CTX_s * DIGEST_CTX;
26 typedef struct rpmDigestBundle_s * rpmDigestBundle;
30 typedef struct pgpDig_s * pgpDig;
34 typedef struct pgpDigParams_s * pgpDigParams;
36 typedef uint8_t pgpKeyID_t[8];
37 typedef uint8_t pgpTime_t[4];
42 * The packet tag denotes what type of packet the body holds. Note that
43 * old format headers can only have tags less than 16, whereas new
44 * format headers can have tags as great as 63.
46 typedef enum pgpTag_e {
47 PGPTAG_RESERVED = 0, /*!< Reserved/Invalid */
48 PGPTAG_PUBLIC_SESSION_KEY = 1, /*!< Public-Key Encrypted Session Key */
49 PGPTAG_SIGNATURE = 2, /*!< Signature */
50 PGPTAG_SYMMETRIC_SESSION_KEY= 3, /*!< Symmetric-Key Encrypted Session Key*/
51 PGPTAG_ONEPASS_SIGNATURE = 4, /*!< One-Pass Signature */
52 PGPTAG_SECRET_KEY = 5, /*!< Secret Key */
53 PGPTAG_PUBLIC_KEY = 6, /*!< Public Key */
54 PGPTAG_SECRET_SUBKEY = 7, /*!< Secret Subkey */
55 PGPTAG_COMPRESSED_DATA = 8, /*!< Compressed Data */
56 PGPTAG_SYMMETRIC_DATA = 9, /*!< Symmetrically Encrypted Data */
57 PGPTAG_MARKER = 10, /*!< Marker */
58 PGPTAG_LITERAL_DATA = 11, /*!< Literal Data */
59 PGPTAG_TRUST = 12, /*!< Trust */
60 PGPTAG_USER_ID = 13, /*!< User ID */
61 PGPTAG_PUBLIC_SUBKEY = 14, /*!< Public Subkey */
62 PGPTAG_COMMENT_OLD = 16, /*!< Comment (from OpenPGP draft) */
63 PGPTAG_PHOTOID = 17, /*!< PGP's photo ID */
64 PGPTAG_ENCRYPTED_MDC = 18, /*!< Integrity protected encrypted data */
65 PGPTAG_MDC = 19, /*!< Manipulaion detection code packet */
66 PGPTAG_PRIVATE_60 = 60, /*!< Private or Experimental Values */
67 PGPTAG_COMMENT = 61, /*!< Comment */
68 PGPTAG_PRIVATE_62 = 62, /*!< Private or Experimental Values */
69 PGPTAG_CONTROL = 63 /*!< Control (GPG) */
73 * 5.1. Public-Key Encrypted Session Key Packets (Tag 1)
75 * A Public-Key Encrypted Session Key packet holds the session key used
76 * to encrypt a message. Zero or more Encrypted Session Key packets
77 * (either Public-Key or Symmetric-Key) may precede a Symmetrically
78 * Encrypted Data Packet, which holds an encrypted message. The message
79 * is encrypted with the session key, and the session key is itself
80 * encrypted and stored in the Encrypted Session Key packet(s). The
81 * Symmetrically Encrypted Data Packet is preceded by one Public-Key
82 * Encrypted Session Key packet for each OpenPGP key to which the
83 * message is encrypted. The recipient of the message finds a session
84 * key that is encrypted to their public key, decrypts the session key,
85 * and then uses the session key to decrypt the message.
87 * The body of this packet consists of:
88 * - A one-octet number giving the version number of the packet type.
89 * The currently defined value for packet version is 3. An
90 * implementation should accept, but not generate a version of 2,
91 * which is equivalent to V3 in all other respects.
92 * - An eight-octet number that gives the key ID of the public key
93 * that the session key is encrypted to.
94 * - A one-octet number giving the public key algorithm used.
95 * - A string of octets that is the encrypted session key. This string
96 * takes up the remainder of the packet, and its contents are
97 * dependent on the public key algorithm used.
99 * Algorithm Specific Fields for RSA encryption
100 * - multiprecision integer (MPI) of RSA encrypted value m**e mod n.
102 * Algorithm Specific Fields for Elgamal encryption:
103 * - MPI of Elgamal (Diffie-Hellman) value g**k mod p.
104 * - MPI of Elgamal (Diffie-Hellman) value m * y**k mod p.
106 typedef struct pgpPktPubkey_s {
107 uint8_t version; /*!< version number (generate 3, accept 2). */
108 pgpKeyID_t keyid; /*!< key ID of the public key for session key. */
109 uint8_t algo; /*!< public key algorithm used. */
114 * 5.2.1. Signature Types
116 * There are a number of possible meanings for a signature, which are
117 * specified in a signature type octet in any given signature.
119 typedef enum pgpSigType_e {
120 PGPSIGTYPE_BINARY = 0x00, /*!< Binary document */
121 PGPSIGTYPE_TEXT = 0x01, /*!< Canonical text document */
122 PGPSIGTYPE_STANDALONE = 0x02, /*!< Standalone */
123 PGPSIGTYPE_GENERIC_CERT = 0x10,
124 /*!< Generic certification of a User ID & Public Key */
125 PGPSIGTYPE_PERSONA_CERT = 0x11,
126 /*!< Persona certification of a User ID & Public Key */
127 PGPSIGTYPE_CASUAL_CERT = 0x12,
128 /*!< Casual certification of a User ID & Public Key */
129 PGPSIGTYPE_POSITIVE_CERT = 0x13,
130 /*!< Positive certification of a User ID & Public Key */
131 PGPSIGTYPE_SUBKEY_BINDING = 0x18, /*!< Subkey Binding */
132 PGPSIGTYPE_SIGNED_KEY = 0x1F, /*!< Signature directly on a key */
133 PGPSIGTYPE_KEY_REVOKE = 0x20, /*!< Key revocation */
134 PGPSIGTYPE_SUBKEY_REVOKE = 0x28, /*!< Subkey revocation */
135 PGPSIGTYPE_CERT_REVOKE = 0x30, /*!< Certification revocation */
136 PGPSIGTYPE_TIMESTAMP = 0x40 /*!< Timestamp */
140 * 9.1. Public Key Algorithms
145 1 - RSA (Encrypt or Sign)
148 16 - Elgamal (Encrypt-Only), see [ELGAMAL]
149 17 - DSA (Digital Signature Standard)
150 18 - Reserved for Elliptic Curve
151 19 - Reserved for ECDSA
152 20 - Elgamal (Encrypt or Sign)
153 21 - Reserved for Diffie-Hellman (X9.42,
154 as defined for IETF-S/MIME)
155 100 to 110 - Private/Experimental algorithm.
158 * Implementations MUST implement DSA for signatures, and Elgamal for
159 * encryption. Implementations SHOULD implement RSA keys.
160 * Implementations MAY implement any other algorithm.
162 typedef enum pgpPubkeyAlgo_e {
163 PGPPUBKEYALGO_RSA = 1, /*!< RSA */
164 PGPPUBKEYALGO_RSA_ENCRYPT = 2, /*!< RSA(Encrypt-Only) */
165 PGPPUBKEYALGO_RSA_SIGN = 3, /*!< RSA(Sign-Only) */
166 PGPPUBKEYALGO_ELGAMAL_ENCRYPT = 16, /*!< Elgamal(Encrypt-Only) */
167 PGPPUBKEYALGO_DSA = 17, /*!< DSA */
168 PGPPUBKEYALGO_EC = 18, /*!< Elliptic Curve */
169 PGPPUBKEYALGO_ECDSA = 19, /*!< ECDSA */
170 PGPPUBKEYALGO_ELGAMAL = 20, /*!< Elgamal */
171 PGPPUBKEYALGO_DH = 21 /*!< Diffie-Hellman (X9.42) */
175 * 9.2. Symmetric Key Algorithms
180 0 - Plaintext or unencrypted data
182 2 - Triple-DES (DES-EDE, as per spec -
183 168 bit key derived from 192)
184 3 - CAST5 (128 bit key, as per RFC 2144)
185 4 - Blowfish (128 bit key, 16 rounds) [BLOWFISH]
186 5 - SAFER-SK128 (13 rounds) [SAFER]
187 6 - Reserved for DES/SK
188 7 - Reserved for AES with 128-bit key
189 8 - Reserved for AES with 192-bit key
190 9 - Reserved for AES with 256-bit key
191 100 to 110 - Private/Experimental algorithm.
194 * Implementations MUST implement Triple-DES. Implementations SHOULD
195 * implement IDEA and CAST5. Implementations MAY implement any other
198 typedef enum pgpSymkeyAlgo_e {
199 PGPSYMKEYALGO_PLAINTEXT = 0, /*!< Plaintext */
200 PGPSYMKEYALGO_IDEA = 1, /*!< IDEA */
201 PGPSYMKEYALGO_TRIPLE_DES = 2, /*!< 3DES */
202 PGPSYMKEYALGO_CAST5 = 3, /*!< CAST5 */
203 PGPSYMKEYALGO_BLOWFISH = 4, /*!< BLOWFISH */
204 PGPSYMKEYALGO_SAFER = 5, /*!< SAFER */
205 PGPSYMKEYALGO_DES_SK = 6, /*!< DES/SK */
206 PGPSYMKEYALGO_AES_128 = 7, /*!< AES(128-bit key) */
207 PGPSYMKEYALGO_AES_192 = 8, /*!< AES(192-bit key) */
208 PGPSYMKEYALGO_AES_256 = 9, /*!< AES(256-bit key) */
209 PGPSYMKEYALGO_TWOFISH = 10, /*!< TWOFISH(256-bit key) */
210 PGPSYMKEYALGO_NOENCRYPT = 110 /*!< no encryption */
214 * 9.3. Compression Algorithms
222 100 to 110 - Private/Experimental algorithm.
225 * Implementations MUST implement uncompressed data. Implementations
226 * SHOULD implement ZIP. Implementations MAY implement ZLIB.
228 typedef enum pgpCompressAlgo_e {
229 PGPCOMPRESSALGO_NONE = 0, /*!< Uncompressed */
230 PGPCOMPRESSALGO_ZIP = 1, /*!< ZIP */
231 PGPCOMPRESSALGO_ZLIB = 2, /*!< ZLIB */
232 PGPCOMPRESSALGO_BZIP2 = 3 /*!< BZIP2 */
236 * 9.4. Hash Algorithms
239 ID Algorithm Text Name
240 -- --------- ---- ----
243 3 - RIPE-MD/160 "RIPEMD160"
244 4 - Reserved for double-width SHA (experimental)
246 6 - Reserved for TIGER/192 "TIGER192"
247 7 - Reserved for HAVAL (5 pass, 160-bit)
249 100 to 110 - Private/Experimental algorithm.
252 * Implementations MUST implement SHA-1. Implementations SHOULD
256 typedef enum pgpHashAlgo_e {
257 PGPHASHALGO_MD5 = 1, /*!< MD5 */
258 PGPHASHALGO_SHA1 = 2, /*!< SHA1 */
259 PGPHASHALGO_RIPEMD160 = 3, /*!< RIPEMD160 */
260 PGPHASHALGO_MD2 = 5, /*!< MD2 */
261 PGPHASHALGO_TIGER192 = 6, /*!< TIGER192 */
262 PGPHASHALGO_HAVAL_5_160 = 7, /*!< HAVAL-5-160 */
263 PGPHASHALGO_SHA256 = 8, /*!< SHA256 */
264 PGPHASHALGO_SHA384 = 9, /*!< SHA384 */
265 PGPHASHALGO_SHA512 = 10, /*!< SHA512 */
266 PGPHASHALGO_SHA224 = 11, /*!< SHA224 */
270 * 5.2.2. Version 3 Signature Packet Format
272 * The body of a version 3 Signature Packet contains:
273 * - One-octet version number (3).
274 * - One-octet length of following hashed material. MUST be 5.
275 * - One-octet signature type.
276 * - Four-octet creation time.
277 * - Eight-octet key ID of signer.
278 * - One-octet public key algorithm.
279 * - One-octet hash algorithm.
280 * - Two-octet field holding left 16 bits of signed hash value.
281 * - One or more multi-precision integers comprising the signature.
283 * Algorithm Specific Fields for RSA signatures:
284 * - multiprecision integer (MPI) of RSA signature value m**d.
286 * Algorithm Specific Fields for DSA signatures:
287 * - MPI of DSA value r.
288 * - MPI of DSA value s.
290 typedef struct pgpPktSigV3_s {
291 uint8_t version; /*!< version number (3). */
292 uint8_t hashlen; /*!< length of following hashed material. MUST be 5. */
293 uint8_t sigtype; /*!< signature type. */
294 pgpTime_t time; /*!< 4 byte creation time. */
295 pgpKeyID_t signid; /*!< key ID of signer. */
296 uint8_t pubkey_algo; /*!< public key algorithm. */
297 uint8_t hash_algo; /*!< hash algorithm. */
298 uint8_t signhash16[2]; /*!< left 16 bits of signed hash value. */
302 * 5.2.3. Version 4 Signature Packet Format
304 * The body of a version 4 Signature Packet contains:
305 * - One-octet version number (4).
306 * - One-octet signature type.
307 * - One-octet public key algorithm.
308 * - One-octet hash algorithm.
309 * - Two-octet scalar octet count for following hashed subpacket
310 * data. Note that this is the length in octets of all of the hashed
311 * subpackets; a pointer incremented by this number will skip over
312 * the hashed subpackets.
313 * - Hashed subpacket data. (zero or more subpackets)
314 * - Two-octet scalar octet count for following unhashed subpacket
315 * data. Note that this is the length in octets of all of the
316 * unhashed subpackets; a pointer incremented by this number will
317 * skip over the unhashed subpackets.
318 * - Unhashed subpacket data. (zero or more subpackets)
319 * - Two-octet field holding left 16 bits of signed hash value.
320 * - One or more multi-precision integers comprising the signature.
322 typedef struct pgpPktSigV4_s {
323 uint8_t version; /*!< version number (4). */
324 uint8_t sigtype; /*!< signature type. */
325 uint8_t pubkey_algo; /*!< public key algorithm. */
326 uint8_t hash_algo; /*!< hash algorithm. */
327 uint8_t hashlen[2]; /*!< length of following hashed material. */
331 * 5.2.3.1. Signature Subpacket Specification
333 * The subpacket fields consist of zero or more signature subpackets.
334 * Each set of subpackets is preceded by a two-octet scalar count of the
335 * length of the set of subpackets.
337 * Each subpacket consists of a subpacket header and a body. The header
339 * - the subpacket length (1, 2, or 5 octets)
340 * - the subpacket type (1 octet)
341 * and is followed by the subpacket specific data.
343 * The length includes the type octet but not this length. Its format is
344 * similar to the "new" format packet header lengths, but cannot have
345 * partial body lengths. That is:
347 if the 1st octet < 192, then
349 subpacketLen = 1st_octet
351 if the 1st octet >= 192 and < 255, then
353 subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192
355 if the 1st octet = 255, then
357 subpacket length = [four-octet scalar starting at 2nd_octet]
360 * The value of the subpacket type octet may be:
363 2 = signature creation time
364 3 = signature expiration time
365 4 = exportable certification
367 6 = regular expression
369 9 = key expiration time
370 10 = placeholder for backward compatibility
371 11 = preferred symmetric algorithms
375 21 = preferred hash algorithms
376 22 = preferred compression algorithms
377 23 = key server preferences
378 24 = preferred key server
382 28 = signer's user id
383 29 = reason for revocation
384 100 to 110 = internal or user-defined
387 * An implementation SHOULD ignore any subpacket of a type that it does
390 * Bit 7 of the subpacket type is the "critical" bit. If set, it
391 * denotes that the subpacket is one that is critical for the evaluator
392 * of the signature to recognize. If a subpacket is encountered that is
393 * marked critical but is unknown to the evaluating software, the
394 * evaluator SHOULD consider the signature to be in error.
396 typedef enum pgpSubType_e {
397 PGPSUBTYPE_NONE = 0, /*!< none */
398 PGPSUBTYPE_SIG_CREATE_TIME = 2, /*!< signature creation time */
399 PGPSUBTYPE_SIG_EXPIRE_TIME = 3, /*!< signature expiration time */
400 PGPSUBTYPE_EXPORTABLE_CERT = 4, /*!< exportable certification */
401 PGPSUBTYPE_TRUST_SIG = 5, /*!< trust signature */
402 PGPSUBTYPE_REGEX = 6, /*!< regular expression */
403 PGPSUBTYPE_REVOCABLE = 7, /*!< revocable */
404 PGPSUBTYPE_KEY_EXPIRE_TIME = 9, /*!< key expiration time */
405 PGPSUBTYPE_ARR = 10, /*!< additional recipient request */
406 PGPSUBTYPE_PREFER_SYMKEY = 11, /*!< preferred symmetric algorithms */
407 PGPSUBTYPE_REVOKE_KEY = 12, /*!< revocation key */
408 PGPSUBTYPE_ISSUER_KEYID = 16, /*!< issuer key ID */
409 PGPSUBTYPE_NOTATION = 20, /*!< notation data */
410 PGPSUBTYPE_PREFER_HASH = 21, /*!< preferred hash algorithms */
411 PGPSUBTYPE_PREFER_COMPRESS = 22, /*!< preferred compression algorithms */
412 PGPSUBTYPE_KEYSERVER_PREFERS= 23, /*!< key server preferences */
413 PGPSUBTYPE_PREFER_KEYSERVER = 24, /*!< preferred key server */
414 PGPSUBTYPE_PRIMARY_USERID = 25, /*!< primary user id */
415 PGPSUBTYPE_POLICY_URL = 26, /*!< policy URL */
416 PGPSUBTYPE_KEY_FLAGS = 27, /*!< key flags */
417 PGPSUBTYPE_SIGNER_USERID = 28, /*!< signer's user id */
418 PGPSUBTYPE_REVOKE_REASON = 29, /*!< reason for revocation */
419 PGPSUBTYPE_FEATURES = 30, /*!< feature flags (gpg) */
420 PGPSUBTYPE_EMBEDDED_SIG = 32, /*!< embedded signature (gpg) */
422 PGPSUBTYPE_INTERNAL_100 = 100, /*!< internal or user-defined */
423 PGPSUBTYPE_INTERNAL_101 = 101, /*!< internal or user-defined */
424 PGPSUBTYPE_INTERNAL_102 = 102, /*!< internal or user-defined */
425 PGPSUBTYPE_INTERNAL_103 = 103, /*!< internal or user-defined */
426 PGPSUBTYPE_INTERNAL_104 = 104, /*!< internal or user-defined */
427 PGPSUBTYPE_INTERNAL_105 = 105, /*!< internal or user-defined */
428 PGPSUBTYPE_INTERNAL_106 = 106, /*!< internal or user-defined */
429 PGPSUBTYPE_INTERNAL_107 = 107, /*!< internal or user-defined */
430 PGPSUBTYPE_INTERNAL_108 = 108, /*!< internal or user-defined */
431 PGPSUBTYPE_INTERNAL_109 = 109, /*!< internal or user-defined */
432 PGPSUBTYPE_INTERNAL_110 = 110, /*!< internal or user-defined */
434 PGPSUBTYPE_CRITICAL = 128 /*!< critical subpacket marker */
438 * 5.2. Signature Packet (Tag 2)
440 * A signature packet describes a binding between some public key and
441 * some data. The most common signatures are a signature of a file or a
442 * block of text, and a signature that is a certification of a user ID.
444 * Two versions of signature packets are defined. Version 3 provides
445 * basic signature information, while version 4 provides an expandable
446 * format with subpackets that can specify more information about the
447 * signature. PGP 2.6.x only accepts version 3 signatures.
449 * Implementations MUST accept V3 signatures. Implementations SHOULD
450 * generate V4 signatures. Implementations MAY generate a V3 signature
451 * that can be verified by PGP 2.6.x.
453 * Note that if an implementation is creating an encrypted and signed
454 * message that is encrypted to a V3 key, it is reasonable to create a
457 typedef union pgpPktSig_u {
458 struct pgpPktSigV3_s v3;
459 struct pgpPktSigV4_s v4;
463 * 5.3. Symmetric-Key Encrypted Session-Key Packets (Tag 3)
465 * The Symmetric-Key Encrypted Session Key packet holds the symmetric-
466 * key encryption of a session key used to encrypt a message. Zero or
467 * more Encrypted Session Key packets and/or Symmetric-Key Encrypted
468 * Session Key packets may precede a Symmetrically Encrypted Data Packet
469 * that holds an encrypted message. The message is encrypted with a
470 * session key, and the session key is itself encrypted and stored in
471 * the Encrypted Session Key packet or the Symmetric-Key Encrypted
472 * Session Key packet.
474 * If the Symmetrically Encrypted Data Packet is preceded by one or more
475 * Symmetric-Key Encrypted Session Key packets, each specifies a
476 * passphrase that may be used to decrypt the message. This allows a
477 * message to be encrypted to a number of public keys, and also to one
478 * or more pass phrases. This packet type is new, and is not generated
479 * by PGP 2.x or PGP 5.0.
481 * The body of this packet consists of:
482 * - A one-octet version number. The only currently defined version
484 * - A one-octet number describing the symmetric algorithm used.
485 * - A string-to-key (S2K) specifier, length as defined above.
486 * - Optionally, the encrypted session key itself, which is decrypted
487 * with the string-to-key object.
490 typedef struct pgpPktSymkey_s {
491 uint8_t version; /*!< version number (4). */
497 * 5.4. One-Pass Signature Packets (Tag 4)
499 * The One-Pass Signature packet precedes the signed data and contains
500 * enough information to allow the receiver to begin calculating any
501 * hashes needed to verify the signature. It allows the Signature
502 * Packet to be placed at the end of the message, so that the signer can
503 * compute the entire signed message in one pass.
505 * A One-Pass Signature does not interoperate with PGP 2.6.x or earlier.
507 * The body of this packet consists of:
508 * - A one-octet version number. The current version is 3.
509 * - A one-octet signature type. Signature types are described in
511 * - A one-octet number describing the hash algorithm used.
512 * - A one-octet number describing the public key algorithm used.
513 * - An eight-octet number holding the key ID of the signing key.
514 * - A one-octet number holding a flag showing whether the signature
515 * is nested. A zero value indicates that the next packet is
516 * another One-Pass Signature packet that describes another
517 * signature to be applied to the same message data.
519 * Note that if a message contains more than one one-pass signature,
520 * then the signature packets bracket the message; that is, the first
521 * signature packet after the message corresponds to the last one-pass
522 * packet and the final signature packet corresponds to the first one-
525 typedef struct pgpPktOnepass_s {
526 uint8_t version; /*!< version number (3). */
527 uint8_t sigtype; /*!< signature type. */
528 uint8_t hash_algo; /*!< hash algorithm. */
529 uint8_t pubkey_algo; /*!< public key algorithm. */
530 pgpKeyID_t signid; /*!< key ID of signer. */
535 * 5.5.1. Key Packet Variants
537 * 5.5.1.1. Public Key Packet (Tag 6)
539 * A Public Key packet starts a series of packets that forms an OpenPGP
540 * key (sometimes called an OpenPGP certificate).
542 * 5.5.1.2. Public Subkey Packet (Tag 14)
544 * A Public Subkey packet (tag 14) has exactly the same format as a
545 * Public Key packet, but denotes a subkey. One or more subkeys may be
546 * associated with a top-level key. By convention, the top-level key
547 * provides signature services, and the subkeys provide encryption
550 * Note: in PGP 2.6.x, tag 14 was intended to indicate a comment packet.
551 * This tag was selected for reuse because no previous version of PGP
552 * ever emitted comment packets but they did properly ignore them.
553 * Public Subkey packets are ignored by PGP 2.6.x and do not cause it to
554 * fail, providing a limited degree of backward compatibility.
556 * 5.5.1.3. Secret Key Packet (Tag 5)
558 * A Secret Key packet contains all the information that is found in a
559 * Public Key packet, including the public key material, but also
560 * includes the secret key material after all the public key fields.
562 * 5.5.1.4. Secret Subkey Packet (Tag 7)
564 * A Secret Subkey packet (tag 7) is the subkey analog of the Secret Key
565 * packet, and has exactly the same format.
567 * 5.5.2. Public Key Packet Formats
569 * There are two versions of key-material packets. Version 3 packets
570 * were first generated by PGP 2.6. Version 2 packets are identical in
571 * format to Version 3 packets, but are generated by PGP 2.5 or before.
572 * V2 packets are deprecated and they MUST NOT be generated. PGP 5.0
573 * introduced version 4 packets, with new fields and semantics. PGP
574 * 2.6.x will not accept key-material packets with versions greater than
577 * OpenPGP implementations SHOULD create keys with version 4 format. An
578 * implementation MAY generate a V3 key to ensure interoperability with
579 * old software; note, however, that V4 keys correct some security
580 * deficiencies in V3 keys. These deficiencies are described below. An
581 * implementation MUST NOT create a V3 key with a public key algorithm
584 * A version 3 public key or public subkey packet contains:
585 * - A one-octet version number (3).
586 * - A four-octet number denoting the time that the key was created.
587 * - A two-octet number denoting the time in days that this key is
588 * valid. If this number is zero, then it does not expire.
589 * - A one-octet number denoting the public key algorithm of this key
590 * - A series of multi-precision integers comprising the key
592 * - a multiprecision integer (MPI) of RSA public modulus n;
593 * - an MPI of RSA public encryption exponent e.
595 * V3 keys SHOULD only be used for backward compatibility because of
596 * three weaknesses in them. First, it is relatively easy to construct a
597 * V3 key that has the same key ID as any other key because the key ID
598 * is simply the low 64 bits of the public modulus. Secondly, because
599 * the fingerprint of a V3 key hashes the key material, but not its
600 * length, which increases the opportunity for fingerprint collisions.
601 * Third, there are minor weaknesses in the MD5 hash algorithm that make
602 * developers prefer other algorithms. See below for a fuller discussion
603 * of key IDs and fingerprints.
606 typedef struct pgpPktKeyV3_s {
607 uint8_t version; /*!< version number (3). */
608 pgpTime_t time; /*!< time that the key was created. */
609 uint8_t valid[2]; /*!< time in days that this key is valid. */
610 uint8_t pubkey_algo; /*!< public key algorithm. */
614 * The version 4 format is similar to the version 3 format except for
615 * the absence of a validity period. This has been moved to the
616 * signature packet. In addition, fingerprints of version 4 keys are
617 * calculated differently from version 3 keys, as described in section
618 * "Enhanced Key Formats."
620 * A version 4 packet contains:
621 * - A one-octet version number (4).
622 * - A four-octet number denoting the time that the key was created.
623 * - A one-octet number denoting the public key algorithm of this key
624 * - A series of multi-precision integers comprising the key
625 * material. This algorithm-specific portion is:
627 * Algorithm Specific Fields for RSA public keys:
628 * - multiprecision integer (MPI) of RSA public modulus n;
629 * - MPI of RSA public encryption exponent e.
631 * Algorithm Specific Fields for DSA public keys:
632 * - MPI of DSA prime p;
633 * - MPI of DSA group order q (q is a prime divisor of p-1);
634 * - MPI of DSA group generator g;
635 * - MPI of DSA public key value y (= g**x where x is secret).
637 * Algorithm Specific Fields for Elgamal public keys:
638 * - MPI of Elgamal prime p;
639 * - MPI of Elgamal group generator g;
640 * - MPI of Elgamal public key value y (= g**x where x is
644 typedef struct pgpPktKeyV4_s {
645 uint8_t version; /*!< version number (4). */
646 pgpTime_t time; /*!< time that the key was created. */
647 uint8_t pubkey_algo; /*!< public key algorithm. */
651 * 5.5.3. Secret Key Packet Formats
653 * The Secret Key and Secret Subkey packets contain all the data of the
654 * Public Key and Public Subkey packets, with additional algorithm-
655 * specific secret key data appended, in encrypted form.
657 * The packet contains:
658 * - A Public Key or Public Subkey packet, as described above
659 * - One octet indicating string-to-key usage conventions. 0
660 * indicates that the secret key data is not encrypted. 255
661 * indicates that a string-to-key specifier is being given. Any
662 * other value is a symmetric-key encryption algorithm specifier.
663 * - [Optional] If string-to-key usage octet was 255, a one-octet
664 * symmetric encryption algorithm.
665 * - [Optional] If string-to-key usage octet was 255, a string-to-key
666 * specifier. The length of the string-to-key specifier is implied
667 * by its type, as described above.
668 * - [Optional] If secret data is encrypted, eight-octet Initial
670 * - Encrypted multi-precision integers comprising the secret key
671 * data. These algorithm-specific fields are as described below.
672 * - Two-octet checksum of the plaintext of the algorithm-specific
673 * portion (sum of all octets, mod 65536).
675 * Algorithm Specific Fields for RSA secret keys:
676 * - multiprecision integer (MPI) of RSA secret exponent d.
677 * - MPI of RSA secret prime value p.
678 * - MPI of RSA secret prime value q (p < q).
679 * - MPI of u, the multiplicative inverse of p, mod q.
681 * Algorithm Specific Fields for DSA secret keys:
682 * - MPI of DSA secret exponent x.
684 * Algorithm Specific Fields for Elgamal secret keys:
685 * - MPI of Elgamal secret exponent x.
687 * Secret MPI values can be encrypted using a passphrase. If a string-
688 * to-key specifier is given, that describes the algorithm for
689 * converting the passphrase to a key, else a simple MD5 hash of the
690 * passphrase is used. Implementations SHOULD use a string-to-key
691 * specifier; the simple hash is for backward compatibility. The cipher
692 * for encrypting the MPIs is specified in the secret key packet.
694 * Encryption/decryption of the secret data is done in CFB mode using
695 * the key created from the passphrase and the Initial Vector from the
696 * packet. A different mode is used with V3 keys (which are only RSA)
697 * than with other key formats. With V3 keys, the MPI bit count prefix
698 * (i.e., the first two octets) is not encrypted. Only the MPI non-
699 * prefix data is encrypted. Furthermore, the CFB state is
700 * resynchronized at the beginning of each new MPI value, so that the
701 * CFB block boundary is aligned with the start of the MPI data.
703 * With V4 keys, a simpler method is used. All secret MPI values are
704 * encrypted in CFB mode, including the MPI bitcount prefix.
706 * The 16-bit checksum that follows the algorithm-specific portion is
707 * the algebraic sum, mod 65536, of the plaintext of all the algorithm-
708 * specific octets (including MPI prefix and data). With V3 keys, the
709 * checksum is stored in the clear. With V4 keys, the checksum is
710 * encrypted like the algorithm-specific data. This value is used to
711 * check that the passphrase was correct.
714 typedef union pgpPktKey_u {
715 struct pgpPktKeyV3_s v3;
716 struct pgpPktKeyV4_s v4;
720 * 5.6. Compressed Data Packet (Tag 8)
722 * The Compressed Data packet contains compressed data. Typically, this
723 * packet is found as the contents of an encrypted packet, or following
724 * a Signature or One-Pass Signature packet, and contains literal data
727 * The body of this packet consists of:
728 * - One octet that gives the algorithm used to compress the packet.
729 * - The remainder of the packet is compressed data.
731 * A Compressed Data Packet's body contains an block that compresses
732 * some set of packets. See section "Packet Composition" for details on
733 * how messages are formed.
735 * ZIP-compressed packets are compressed with raw RFC 1951 DEFLATE
736 * blocks. Note that PGP V2.6 uses 13 bits of compression. If an
737 * implementation uses more bits of compression, PGP V2.6 cannot
740 * ZLIB-compressed packets are compressed with RFC 1950 ZLIB-style
743 typedef struct pgpPktCdata_s {
744 uint8_t compressalgo;
749 * 5.7. Symmetrically Encrypted Data Packet (Tag 9)
751 * The Symmetrically Encrypted Data packet contains data encrypted with
752 * a symmetric-key algorithm. When it has been decrypted, it will
753 * typically contain other packets (often literal data packets or
754 * compressed data packets).
756 * The body of this packet consists of:
757 * - Encrypted data, the output of the selected symmetric-key cipher
758 * operating in PGP's variant of Cipher Feedback (CFB) mode.
760 * The symmetric cipher used may be specified in an Public-Key or
761 * Symmetric-Key Encrypted Session Key packet that precedes the
762 * Symmetrically Encrypted Data Packet. In that case, the cipher
763 * algorithm octet is prefixed to the session key before it is
764 * encrypted. If no packets of these types precede the encrypted data,
765 * the IDEA algorithm is used with the session key calculated as the MD5
766 * hash of the passphrase.
768 * The data is encrypted in CFB mode, with a CFB shift size equal to the
769 * cipher's block size. The Initial Vector (IV) is specified as all
770 * zeros. Instead of using an IV, OpenPGP prefixes a 10-octet string to
771 * the data before it is encrypted. The first eight octets are random,
772 * and the 9th and 10th octets are copies of the 7th and 8th octets,
773 * respectively. After encrypting the first 10 octets, the CFB state is
774 * resynchronized if the cipher block size is 8 octets or less. The
775 * last 8 octets of ciphertext are passed through the cipher and the
776 * block boundary is reset.
778 * The repetition of 16 bits in the 80 bits of random data prefixed to
779 * the message allows the receiver to immediately check whether the
780 * session key is incorrect.
782 typedef struct pgpPktEdata_s {
787 * 5.8. Marker Packet (Obsolete Literal Packet) (Tag 10)
789 * An experimental version of PGP used this packet as the Literal
790 * packet, but no released version of PGP generated Literal packets with
791 * this tag. With PGP 5.x, this packet has been re-assigned and is
792 * reserved for use as the Marker packet.
794 * The body of this packet consists of:
795 * - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8).
797 * Such a packet MUST be ignored when received. It may be placed at the
798 * beginning of a message that uses features not available in PGP 2.6.x
799 * in order to cause that version to report that newer software is
800 * necessary to process the message.
803 * 5.9. Literal Data Packet (Tag 11)
805 * A Literal Data packet contains the body of a message; data that is
806 * not to be further interpreted.
808 * The body of this packet consists of:
809 * - A one-octet field that describes how the data is formatted.
811 * If it is a 'b' (0x62), then the literal packet contains binary data.
812 * If it is a 't' (0x74), then it contains text data, and thus may need
813 * line ends converted to local form, or other text-mode changes. RFC
814 * 1991 also defined a value of 'l' as a 'local' mode for machine-local
815 * conversions. This use is now deprecated.
816 * - File name as a string (one-octet length, followed by file name),
817 * if the encrypted data should be saved as a file.
819 * If the special name "_CONSOLE" is used, the message is considered to
820 * be "for your eyes only". This advises that the message data is
821 * unusually sensitive, and the receiving program should process it more
822 * carefully, perhaps avoiding storing the received data to disk, for
824 * - A four-octet number that indicates the modification date of the
825 * file, or the creation time of the packet, or a zero that
826 * indicates the present time.
827 * - The remainder of the packet is literal data.
829 * Text data is stored with <CR><LF> text endings (i.e. network-normal
830 * line endings). These should be converted to native line endings by
831 * the receiving software.
833 typedef struct pgpPktLdata_s {
840 * 5.10. Trust Packet (Tag 12)
842 * The Trust packet is used only within keyrings and is not normally
843 * exported. Trust packets contain data that record the user's
844 * specifications of which key holders are trustworthy introducers,
845 * along with other information that implementing software uses for
848 * Trust packets SHOULD NOT be emitted to output streams that are
849 * transferred to other users, and they SHOULD be ignored on any input
850 * other than local keyring files.
852 typedef struct pgpPktTrust_s {
857 * 5.11. User ID Packet (Tag 13)
859 * A User ID packet consists of data that is intended to represent the
860 * name and email address of the key holder. By convention, it includes
861 * an RFC 822 mail name, but there are no restrictions on its content.
862 * The packet length in the header specifies the length of the user id.
863 * If it is text, it is encoded in UTF-8.
866 typedef struct pgpPktUid_s {
873 pgpPktPubkey pubkey; /*!< 5.1. Public-Key Encrypted Session Key */
874 pgpPktSig sig; /*!< 5.2. Signature */
875 pgpPktSymkey symkey; /*!< 5.3. Symmetric-Key Encrypted Session-Key */
876 pgpPktOnepass onepass; /*!< 5.4. One-Pass Signature */
877 pgpPktKey key; /*!< 5.5. Key Material */
878 pgpPktCdata cdata; /*!< 5.6. Compressed Data */
879 pgpPktEdata edata; /*!< 5.7. Symmetrically Encrypted Data */
880 /*!< 5.8. Marker (obsolete) */
881 pgpPktLdata ldata; /*!< 5.9. Literal Data */
882 pgpPktTrust tdata; /*!< 5.10. Trust */
883 pgpPktUid uid; /*!< 5.11. User ID */
888 typedef enum pgpArmor_e {
889 PGPARMOR_ERR_CRC_CHECK = -7,
890 PGPARMOR_ERR_BODY_DECODE = -6,
891 PGPARMOR_ERR_CRC_DECODE = -5,
892 PGPARMOR_ERR_NO_END_PGP = -4,
893 PGPARMOR_ERR_UNKNOWN_PREAMBLE_TAG = -3,
894 PGPARMOR_ERR_UNKNOWN_ARMOR_TYPE = -2,
895 PGPARMOR_ERR_NO_BEGIN_PGP = -1,
896 #define PGPARMOR_ERROR PGPARMOR_ERR_NO_BEGIN_PGP
898 PGPARMOR_MESSAGE = 1, /*!< MESSAGE */
899 PGPARMOR_PUBKEY = 2, /*!< PUBLIC KEY BLOCK */
900 PGPARMOR_SIGNATURE = 3, /*!< SIGNATURE */
901 PGPARMOR_SIGNED_MESSAGE = 4, /*!< SIGNED MESSAGE */
902 PGPARMOR_FILE = 5, /*!< ARMORED FILE */
903 PGPARMOR_PRIVKEY = 6, /*!< PRIVATE KEY BLOCK */
904 PGPARMOR_SECKEY = 7 /*!< SECRET KEY BLOCK */
909 typedef enum pgpArmorKey_e {
910 PGPARMORKEY_VERSION = 1, /*!< Version: */
911 PGPARMORKEY_COMMENT = 2, /*!< Comment: */
912 PGPARMORKEY_MESSAGEID = 3, /*!< MessageID: */
913 PGPARMORKEY_HASH = 4, /*!< Hash: */
914 PGPARMORKEY_CHARSET = 5 /*!< Charset: */
917 typedef enum pgpValType_e {
919 PGPVAL_ARMORBLOCK = 2,
923 PGPVAL_PUBKEYALGO = 6,
924 PGPVAL_SYMKEYALGO = 7,
925 PGPVAL_COMPRESSALGO = 8,
927 PGPVAL_SERVERPREFS = 10,
931 * Bit(s) to control digest operation.
933 enum rpmDigestFlags_e {
937 typedef rpmFlags rpmDigestFlags;
940 * Return string representation of am OpenPGP value.
941 * @param type type of value
942 * @param val byte value to lookup
943 * @return string value of byte
945 const char * pgpValString(pgpValType type, uint8_t val);
948 * Return (native-endian) integer from big-endian representation.
949 * @param s pointer to big-endian integer
950 * @param nbytes no. of bytes
951 * @return native-endian integer
954 unsigned int pgpGrab(const uint8_t *s, size_t nbytes)
957 size_t nb = (nbytes <= sizeof(i) ? nbytes : sizeof(i));
964 * Return hex formatted representation of bytes.
966 * @param plen no. of bytes
967 * @return hex formatted string (malloc'ed)
969 char * pgpHexStr(const uint8_t *p, size_t plen);
972 * Calculate OpenPGP public key fingerprint.
973 * @todo V3 non-RSA public keys not implemented.
974 * @param pkt OpenPGP packet (i.e. PGPTAG_PUBLIC_KEY)
975 * @param pktlen OpenPGP packet length (no. of bytes)
976 * @retval keyid public key fingerprint
977 * @return 0 on sucess, else -1
979 int pgpPubkeyFingerprint(const uint8_t * pkt, size_t pktlen,
983 * Extract OpenPGP public key fingerprint from base64 encoded packet.
984 * @todo V3 non-RSA public keys not implemented.
985 * @param b64pkt base64 encoded openpgp packet
986 * @retval keyid public key fingerprint
987 * @return 8 (no. of bytes) on success, < 0 on error
989 int pgpExtractPubkeyFingerprint(const char * b64pkt, pgpKeyID_t keyid);
992 * Parse a OpenPGP packet(s).
993 * @param pkts OpenPGP packet(s)
994 * @param pktlen OpenPGP packet(s) length (no. of bytes)
995 * @param pkttype Expected packet type (signature/key) or 0 for any
996 * @retval ret signature/pubkey packet parameters on success (alloced)
997 * @return -1 on error, 0 on success
999 int pgpPrtParams(const uint8_t *pkts, size_t pktlen, unsigned int pkttype,
1000 pgpDigParams * ret);
1003 * Print/parse a OpenPGP packet(s).
1004 * @param pkts OpenPGP packet(s)
1005 * @param pktlen OpenPGP packet(s) length (no. of bytes)
1006 * @retval dig parsed output of signature/pubkey packet parameters
1007 * @param printing should packets be printed?
1008 * @return -1 on error, 0 on success
1010 int pgpPrtPkts(const uint8_t *pkts, size_t pktlen, pgpDig dig, int printing);
1013 * Parse armored OpenPGP packets from a file.
1014 * @param fn file name
1015 * @retval pkt dearmored OpenPGP packet(s) (malloced)
1016 * @retval pktlen dearmored OpenPGP packet(s) length in bytes
1017 * @return type of armor found
1019 pgpArmor pgpReadPkts(const char * fn, uint8_t ** pkt, size_t * pktlen);
1022 * Parse armored OpenPGP packets from memory.
1023 * @param armor armored OpenPGP packet string
1024 * @retval pkt dearmored OpenPGP packet(s) (malloced)
1025 * @retval pktlen dearmored OpenPGP packet(s) length in bytes
1026 * @return type of armor found
1028 pgpArmor pgpParsePkts(const char *armor, uint8_t ** pkt, size_t * pktlen);
1031 * Wrap a OpenPGP packets in ascii armor for transport.
1032 * @param atype type of armor
1033 * @param s binary pkt data
1034 * @param ns binary pkt data length
1035 * @return formatted string
1037 char * pgpArmorWrap(int atype, const unsigned char * s, size_t ns);
1040 * Create a container for parsed OpenPGP packet(s).
1043 pgpDig pgpNewDig(void);
1046 * Release (malloc'd) data from container.
1047 * @param dig container
1049 void pgpCleanDig(pgpDig dig);
1052 * Destroy a container for parsed OpenPGP packet(s).
1053 * @param dig container
1054 * @return NULL always
1056 pgpDig pgpFreeDig(pgpDig dig);
1059 * Retrieve parameters for parsed OpenPGP packet(s).
1060 * @param dig container
1061 * @param pkttype type of params to retrieve (signature / pubkey)
1062 * @return pointer to OpenPGP parameters, NULL on error/not found
1064 pgpDigParams pgpDigGetParams(pgpDig dig, unsigned int pkttype);
1067 * Compare OpenPGP packet parameters
1068 * param p1 1st parameter container
1069 * param p2 2nd parameter container
1070 * return 1 if the parameters differ, 0 otherwise
1072 int pgpDigParamsCmp(pgpDigParams p1, pgpDigParams p2);
1075 * Retrieve OpenPGP algorithm parameters
1076 * param digp parameter container
1077 * param algotype PGPVAL_HASHALGO / PGPVAL_PUBKEYALGO
1078 * return algorithm value, 0 on error
1080 unsigned int pgpDigParamsAlgo(pgpDigParams digp, unsigned int algotype);
1083 * Destroy parsed OpenPGP packet parameter(s).
1084 * @param digp parameter container
1085 * @return NULL always
1087 pgpDigParams pgpDigParamsFree(pgpDigParams digp);
1090 * Verify a PGP signature.
1091 * @param key public key
1092 * @param sig signature
1093 * @param hashctx digest context
1094 * @return RPMRC_OK on success
1096 rpmRC pgpVerifySignature(pgpDigParams key, pgpDigParams sig, DIGEST_CTX hashctx);
1099 * Verify a PGP signature.
1100 * @deprecated use pgpVerifySignature() instead
1102 * @param dig container
1103 * @param hashctx digest context
1104 * @return RPMRC_OK on success
1106 rpmRC pgpVerifySig(pgpDig dig, DIGEST_CTX hashctx);
1109 * Return a string identification of a PGP signature/pubkey.
1110 * @param digp signature/pubkey container
1111 * @return string describing the item and parameters
1113 char *pgpIdentItem(pgpDigParams digp);
1116 * Perform cryptography initialization.
1117 * It must be called before any cryptography can be used within rpm.
1118 * It's not normally necessary to call it directly as it's called in
1119 * general rpm initialization routines.
1120 * @return 0 on success, -1 on failure
1122 int rpmInitCrypto(void);
1125 * Shutdown cryptography
1127 int rpmFreeCrypto(void);
1130 * Duplicate a digest context.
1131 * @param octx existing digest context
1132 * @return duplicated digest context
1134 DIGEST_CTX rpmDigestDup(DIGEST_CTX octx);
1137 * Obtain digest length in bytes.
1138 * @param hashalgo type of digest
1139 * @return digest length, zero on invalid algorithm
1141 size_t rpmDigestLength(int hashalgo);
1144 * Initialize digest.
1145 * Set bit count to 0 and buffer to mysterious initialization constants.
1146 * @param hashalgo type of digest
1147 * @param flags bit(s) to control digest operation
1148 * @return digest context
1150 DIGEST_CTX rpmDigestInit(int hashalgo, rpmDigestFlags flags);
1153 * Update context with next plain text buffer.
1154 * @param ctx digest context
1155 * @param data next data buffer
1156 * @param len no. bytes of data
1157 * @return 0 on success
1159 int rpmDigestUpdate(DIGEST_CTX ctx, const void * data, size_t len);
1162 * Return digest and destroy context.
1163 * Final wrapup - pad to 64-byte boundary with the bit pattern
1164 * 1 0* (64-bit count of bits processed, MSB-first)
1166 * @param ctx digest context
1167 * @retval datap address of returned digest
1168 * @retval lenp address of digest length
1169 * @param asAscii return digest as ascii string?
1170 * @return 0 on success
1172 int rpmDigestFinal(DIGEST_CTX ctx,
1174 size_t * lenp, int asAscii);
1177 * Create a new digest bundle.
1178 * @return New digest bundle
1180 rpmDigestBundle rpmDigestBundleNew(void);
1183 * Free a digest bundle and all contained digest contexts.
1184 * @param bundle digest bundle
1185 * @return NULL always
1187 rpmDigestBundle rpmDigestBundleFree(rpmDigestBundle bundle);
1190 * Add a new type of digest to a bundle.
1191 * @param bundle digest bundle
1192 * @param algo type of digest
1193 * @param flags bit(s) to control digest operation
1194 * @return 0 on success
1196 int rpmDigestBundleAdd(rpmDigestBundle bundle, int algo,
1197 rpmDigestFlags flags);
1200 * Update contexts within bundle with next plain text buffer.
1201 * @param bundle digest bundle
1202 * @param data next data buffer
1203 * @param len no. bytes of data
1204 * @return 0 on success
1206 int rpmDigestBundleUpdate(rpmDigestBundle bundle, const void *data, size_t len);
1209 * Return digest from a bundle and destroy context, see rpmDigestFinal().
1211 * @param bundle digest bundle
1212 * @param algo type of digest to return
1213 * @retval datap address of returned digest
1214 * @retval lenp address of digest length
1215 * @param asAscii return digest as ascii string?
1216 * @return 0 on success
1218 int rpmDigestBundleFinal(rpmDigestBundle bundle,
1219 int algo, void ** datap, size_t * lenp, int asAscii);
1222 * Duplicate a digest context from a bundle.
1223 * @param bundle digest bundle
1224 * @param algo type of digest to dup
1225 * @return duplicated digest context
1227 DIGEST_CTX rpmDigestBundleDupCtx(rpmDigestBundle bundle, int algo);
1233 #endif /* H_RPMPGP */