rpmio/rpmpgp.h

   1 #ifndef H_RPMPGP
   2 #define H_RPMPGP
   3
   4 /** \ingroup rpmpgp
   5  * \file rpmio/rpmpgp.h
   6  *
   7  * OpenPGP constants and structures from RFC-2440.
   8  *
   9  * Text from RFC-2440 in comments is
  10  *      Copyright (C) The Internet Society (1998).  All Rights Reserved.
  11  */
  12
  13 #include <string.h>
  14 #include <stdio.h>
  15 #include <stdlib.h>
  16 #include <rpm/rpmtypes.h>
  17 #include <rpm/rpmstring.h>
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /** \ingroup rpmpgp
  24  */
  25 typedef struct DIGEST_CTX_s * DIGEST_CTX;
  26 typedef struct rpmDigestBundle_s * rpmDigestBundle;
  27
  28 /** \ingroup rpmpgp
  29  */
  30 typedef struct pgpDig_s * pgpDig;
  31
  32 /** \ingroup rpmpgp
  33  */
  34 typedef struct pgpDigParams_s * pgpDigParams;
  35
  36 typedef uint8_t pgpKeyID_t[8];
  37 typedef uint8_t pgpTime_t[4];
  38
  39 /** \ingroup rpmpgp
  40  * 4.3. Packet Tags
  41  *
  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.
  45  */
  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) */
  70 } pgpTag;
  71
  72 /** \ingroup rpmpgp
  73  * 5.1. Public-Key Encrypted Session Key Packets (Tag 1)
  74  *
  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.
  86  *
  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.
  98  *
  99  * Algorithm Specific Fields for RSA encryption
 100  *   - multiprecision integer (MPI) of RSA encrypted value m**e mod n.
 101  *
 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.
 105  */
 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. */
 110 } pgpPktPubkey;
 111
 112
 113 /** \ingroup rpmpgp
 114  * 5.2.1. Signature Types
 115  *
 116  * There are a number of possible meanings for a signature, which are
 117  * specified in a signature type octet in any given signature.
 118  */
 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 */
 137 } pgpSigType;
 138
 139 /** \ingroup rpmpgp
 140  * 9.1. Public Key Algorithms
 141  *
 142 \verbatim
 143        ID           Algorithm
 144        --           ---------
 145        1          - RSA (Encrypt or Sign)
 146        2          - RSA Encrypt-Only
 147        3          - RSA Sign-Only
 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.
 156 \endverbatim
 157  *
 158  * Implementations MUST implement DSA for signatures, and Elgamal for
 159  * encryption. Implementations SHOULD implement RSA keys.
 160  * Implementations MAY implement any other algorithm.
 161  */
 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) */
 172 } pgpPubkeyAlgo;
 173
 174 /** \ingroup rpmpgp
 175  * 9.2. Symmetric Key Algorithms
 176  *
 177 \verbatim
 178        ID           Algorithm
 179        --           ---------
 180        0          - Plaintext or unencrypted data
 181        1          - IDEA [IDEA]
 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.
 192 \endverbatim
 193  *
 194  * Implementations MUST implement Triple-DES. Implementations SHOULD
 195  * implement IDEA and CAST5. Implementations MAY implement any other
 196  * algorithm.
 197  */
 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 */
 211 } pgpSymkeyAlgo;
 212
 213 /** \ingroup rpmpgp
 214  * 9.3. Compression Algorithms
 215  *
 216 \verbatim
 217        ID           Algorithm
 218        --           ---------
 219        0          - Uncompressed
 220        1          - ZIP (RFC 1951)
 221        2          - ZLIB (RFC 1950)
 222        100 to 110 - Private/Experimental algorithm.
 223 \endverbatim
 224  *
 225  * Implementations MUST implement uncompressed data. Implementations
 226  * SHOULD implement ZIP. Implementations MAY implement ZLIB.
 227  */
 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 */
 233 } pgpCompressAlgo;
 234
 235 /** \ingroup rpmpgp
 236  * 9.4. Hash Algorithms
 237  *
 238 \verbatim
 239        ID           Algorithm                              Text Name
 240        --           ---------                              ---- ----
 241        1          - MD5                                    "MD5"
 242        2          - SHA-1                                  "SHA1"
 243        3          - RIPE-MD/160                            "RIPEMD160"
 244        4          - Reserved for double-width SHA (experimental)
 245        5          - MD2                                    "MD2"
 246        6          - Reserved for TIGER/192                 "TIGER192"
 247        7          - Reserved for HAVAL (5 pass, 160-bit)    "HAVAL-5-160"
 248        8          - SHA-256                                "SHA256"
 249        9          - SHA-384                                "SHA384"
 250        10         - SHA-512                                "SHA512"
 251        11         - SHA-224                                "SHA224"
 252        100 to 110 - Private/Experimental algorithm.
 253 \endverbatim
 254  *
 255  * Implementations MUST implement SHA-1. Implementations SHOULD
 256  * implement MD5.
 257  */
 258 typedef enum pgpHashAlgo_e {
 259     PGPHASHALGO_MD5             =  1,   /*!< MD5 */
 260     PGPHASHALGO_SHA1            =  2,   /*!< SHA1 */
 261     PGPHASHALGO_RIPEMD160       =  3,   /*!< RIPEMD160 */
 262     PGPHASHALGO_MD2             =  5,   /*!< MD2 */
 263     PGPHASHALGO_TIGER192        =  6,   /*!< TIGER192 */
 264     PGPHASHALGO_HAVAL_5_160     =  7,   /*!< HAVAL-5-160 */
 265     PGPHASHALGO_SHA256          =  8,   /*!< SHA256 */
 266     PGPHASHALGO_SHA384          =  9,   /*!< SHA384 */
 267     PGPHASHALGO_SHA512          = 10,   /*!< SHA512 */
 268     PGPHASHALGO_SHA224          = 11,   /*!< SHA224 */
 269 } pgpHashAlgo;
 270
 271 /** \ingroup rpmpgp
 272  * 5.2.2. Version 3 Signature Packet Format
 273  *
 274  * The body of a version 3 Signature Packet contains:
 275  *   - One-octet version number (3).
 276  *   - One-octet length of following hashed material.  MUST be 5.
 277  *       - One-octet signature type.
 278  *       - Four-octet creation time.
 279  *   - Eight-octet key ID of signer.
 280  *   - One-octet public key algorithm.
 281  *   - One-octet hash algorithm.
 282  *   - Two-octet field holding left 16 bits of signed hash value.
 283  *   - One or more multi-precision integers comprising the signature.
 284  *
 285  * Algorithm Specific Fields for RSA signatures:
 286  *   - multiprecision integer (MPI) of RSA signature value m**d.
 287  *
 288  * Algorithm Specific Fields for DSA signatures:
 289  *   - MPI of DSA value r.
 290  *   - MPI of DSA value s.
 291  */
 292 typedef struct pgpPktSigV3_s {
 293     uint8_t version;    /*!< version number (3). */
 294     uint8_t hashlen;    /*!< length of following hashed material. MUST be 5. */
 295     uint8_t sigtype;    /*!< signature type. */
 296     pgpTime_t time;     /*!< 4 byte creation time. */
 297     pgpKeyID_t signid;  /*!< key ID of signer. */
 298     uint8_t pubkey_algo;        /*!< public key algorithm. */
 299     uint8_t hash_algo;  /*!< hash algorithm. */
 300     uint8_t signhash16[2];      /*!< left 16 bits of signed hash value. */
 301 } * pgpPktSigV3;
 302
 303 /** \ingroup rpmpgp
 304  * 5.2.3. Version 4 Signature Packet Format
 305  *
 306  * The body of a version 4 Signature Packet contains:
 307  *   - One-octet version number (4).
 308  *   - One-octet signature type.
 309  *   - One-octet public key algorithm.
 310  *   - One-octet hash algorithm.
 311  *   - Two-octet scalar octet count for following hashed subpacket
 312  *     data. Note that this is the length in octets of all of the hashed
 313  *     subpackets; a pointer incremented by this number will skip over
 314  *     the hashed subpackets.
 315  *   - Hashed subpacket data. (zero or more subpackets)
 316  *   - Two-octet scalar octet count for following unhashed subpacket
 317  *     data. Note that this is the length in octets of all of the
 318  *     unhashed subpackets; a pointer incremented by this number will
 319  *     skip over the unhashed subpackets.
 320  *   - Unhashed subpacket data. (zero or more subpackets)
 321  *   - Two-octet field holding left 16 bits of signed hash value.
 322  *   - One or more multi-precision integers comprising the signature.
 323  */
 324 typedef struct pgpPktSigV4_s {
 325     uint8_t version;    /*!< version number (4). */
 326     uint8_t sigtype;    /*!< signature type. */
 327     uint8_t pubkey_algo;        /*!< public key algorithm. */
 328     uint8_t hash_algo;  /*!< hash algorithm. */
 329     uint8_t hashlen[2]; /*!< length of following hashed material. */
 330 } * pgpPktSigV4;
 331
 332 /** \ingroup rpmpgp
 333  * 5.2.3.1. Signature Subpacket Specification
 334  *
 335  * The subpacket fields consist of zero or more signature subpackets.
 336  * Each set of subpackets is preceded by a two-octet scalar count of the
 337  * length of the set of subpackets.
 338  *
 339  * Each subpacket consists of a subpacket header and a body.  The header
 340  * consists of:
 341  *   - the subpacket length (1,  2, or 5 octets)
 342  *   - the subpacket type (1 octet)
 343  * and is followed by the subpacket specific data.
 344  *
 345  * The length includes the type octet but not this length. Its format is
 346  * similar to the "new" format packet header lengths, but cannot have
 347  * partial body lengths. That is:
 348 \verbatim
 349        if the 1st octet <  192, then
 350            lengthOfLength = 1
 351            subpacketLen = 1st_octet
 352
 353        if the 1st octet >= 192 and < 255, then
 354            lengthOfLength = 2
 355            subpacketLen = ((1st_octet - 192) << 8) + (2nd_octet) + 192
 356
 357        if the 1st octet = 255, then
 358            lengthOfLength = 5
 359            subpacket length = [four-octet scalar starting at 2nd_octet]
 360 \endverbatim
 361  *
 362  * The value of the subpacket type octet may be:
 363  *
 364 \verbatim
 365        2 = signature creation time
 366        3 = signature expiration time
 367        4 = exportable certification
 368        5 = trust signature
 369        6 = regular expression
 370        7 = revocable
 371        9 = key expiration time
 372        10 = placeholder for backward compatibility
 373        11 = preferred symmetric algorithms
 374        12 = revocation key
 375        16 = issuer key ID
 376        20 = notation data
 377        21 = preferred hash algorithms
 378        22 = preferred compression algorithms
 379        23 = key server preferences
 380        24 = preferred key server
 381        25 = primary user id
 382        26 = policy URL
 383        27 = key flags
 384        28 = signer's user id
 385        29 = reason for revocation
 386        100 to 110 = internal or user-defined
 387 \endverbatim
 388  *
 389  * An implementation SHOULD ignore any subpacket of a type that it does
 390  * not recognize.
 391  *
 392  * Bit 7 of the subpacket type is the "critical" bit.  If set, it
 393  * denotes that the subpacket is one that is critical for the evaluator
 394  * of the signature to recognize.  If a subpacket is encountered that is
 395  * marked critical but is unknown to the evaluating software, the
 396  * evaluator SHOULD consider the signature to be in error.
 397  */
 398 typedef enum pgpSubType_e {
 399     PGPSUBTYPE_NONE             =   0, /*!< none */
 400     PGPSUBTYPE_SIG_CREATE_TIME  =   2, /*!< signature creation time */
 401     PGPSUBTYPE_SIG_EXPIRE_TIME  =   3, /*!< signature expiration time */
 402     PGPSUBTYPE_EXPORTABLE_CERT  =   4, /*!< exportable certification */
 403     PGPSUBTYPE_TRUST_SIG        =   5, /*!< trust signature */
 404     PGPSUBTYPE_REGEX            =   6, /*!< regular expression */
 405     PGPSUBTYPE_REVOCABLE        =   7, /*!< revocable */
 406     PGPSUBTYPE_KEY_EXPIRE_TIME  =   9, /*!< key expiration time */
 407     PGPSUBTYPE_ARR              =  10, /*!< additional recipient request */
 408     PGPSUBTYPE_PREFER_SYMKEY    =  11, /*!< preferred symmetric algorithms */
 409     PGPSUBTYPE_REVOKE_KEY       =  12, /*!< revocation key */
 410     PGPSUBTYPE_ISSUER_KEYID     =  16, /*!< issuer key ID */
 411     PGPSUBTYPE_NOTATION         =  20, /*!< notation data */
 412     PGPSUBTYPE_PREFER_HASH      =  21, /*!< preferred hash algorithms */
 413     PGPSUBTYPE_PREFER_COMPRESS  =  22, /*!< preferred compression algorithms */
 414     PGPSUBTYPE_KEYSERVER_PREFERS=  23, /*!< key server preferences */
 415     PGPSUBTYPE_PREFER_KEYSERVER =  24, /*!< preferred key server */
 416     PGPSUBTYPE_PRIMARY_USERID   =  25, /*!< primary user id */
 417     PGPSUBTYPE_POLICY_URL       =  26, /*!< policy URL */
 418     PGPSUBTYPE_KEY_FLAGS        =  27, /*!< key flags */
 419     PGPSUBTYPE_SIGNER_USERID    =  28, /*!< signer's user id */
 420     PGPSUBTYPE_REVOKE_REASON    =  29, /*!< reason for revocation */
 421     PGPSUBTYPE_FEATURES         =  30, /*!< feature flags (gpg) */
 422     PGPSUBTYPE_EMBEDDED_SIG     =  32, /*!< embedded signature (gpg) */
 423
 424     PGPSUBTYPE_INTERNAL_100     = 100, /*!< internal or user-defined */
 425     PGPSUBTYPE_INTERNAL_101     = 101, /*!< internal or user-defined */
 426     PGPSUBTYPE_INTERNAL_102     = 102, /*!< internal or user-defined */
 427     PGPSUBTYPE_INTERNAL_103     = 103, /*!< internal or user-defined */
 428     PGPSUBTYPE_INTERNAL_104     = 104, /*!< internal or user-defined */
 429     PGPSUBTYPE_INTERNAL_105     = 105, /*!< internal or user-defined */
 430     PGPSUBTYPE_INTERNAL_106     = 106, /*!< internal or user-defined */
 431     PGPSUBTYPE_INTERNAL_107     = 107, /*!< internal or user-defined */
 432     PGPSUBTYPE_INTERNAL_108     = 108, /*!< internal or user-defined */
 433     PGPSUBTYPE_INTERNAL_109     = 109, /*!< internal or user-defined */
 434     PGPSUBTYPE_INTERNAL_110     = 110, /*!< internal or user-defined */
 435
 436     PGPSUBTYPE_CRITICAL         = 128  /*!< critical subpacket marker */
 437 } pgpSubType;
 438
 439 /** \ingroup rpmpgp
 440  * 5.2. Signature Packet (Tag 2)
 441  *
 442  * A signature packet describes a binding between some public key and
 443  * some data. The most common signatures are a signature of a file or a
 444  * block of text, and a signature that is a certification of a user ID.
 445  *
 446  * Two versions of signature packets are defined.  Version 3 provides
 447  * basic signature information, while version 4 provides an expandable
 448  * format with subpackets that can specify more information about the
 449  * signature. PGP 2.6.x only accepts version 3 signatures.
 450  *
 451  * Implementations MUST accept V3 signatures. Implementations SHOULD
 452  * generate V4 signatures.  Implementations MAY generate a V3 signature
 453  * that can be verified by PGP 2.6.x.
 454  *
 455  * Note that if an implementation is creating an encrypted and signed
 456  * message that is encrypted to a V3 key, it is reasonable to create a
 457  * V3 signature.
 458  */
 459 typedef union pgpPktSig_u {
 460     struct pgpPktSigV3_s v3;
 461     struct pgpPktSigV4_s v4;
 462 } * pgpPktSig;
 463
 464 /**
 465  * 5.3. Symmetric-Key Encrypted Session-Key Packets (Tag 3)
 466  *
 467  * The Symmetric-Key Encrypted Session Key packet holds the symmetric-
 468  * key encryption of a session key used to encrypt a message.  Zero or
 469  * more Encrypted Session Key packets and/or Symmetric-Key Encrypted
 470  * Session Key packets may precede a Symmetrically Encrypted Data Packet
 471  * that holds an encrypted message.  The message is encrypted with a
 472  * session key, and the session key is itself encrypted and stored in
 473  * the Encrypted Session Key packet or the Symmetric-Key Encrypted
 474  * Session Key packet.
 475  *
 476  * If the Symmetrically Encrypted Data Packet is preceded by one or more
 477  * Symmetric-Key Encrypted Session Key packets, each specifies a
 478  * passphrase that may be used to decrypt the message.  This allows a
 479  * message to be encrypted to a number of public keys, and also to one
 480  * or more pass phrases. This packet type is new, and is not generated
 481  * by PGP 2.x or PGP 5.0.
 482  *
 483  * The body of this packet consists of:
 484  *   - A one-octet version number. The only currently defined version
 485  *     is 4.
 486  *   - A one-octet number describing the symmetric algorithm used.
 487  *   - A string-to-key (S2K) specifier, length as defined above.
 488  *   - Optionally, the encrypted session key itself, which is decrypted
 489  *     with the string-to-key object.
 490  *
 491  */
 492 typedef struct pgpPktSymkey_s {
 493     uint8_t version;    /*!< version number (4). */
 494     uint8_t symkey_algo;
 495     uint8_t s2k[1];
 496 } pgpPktSymkey;
 497
 498 /** \ingroup rpmpgp
 499  * 5.4. One-Pass Signature Packets (Tag 4)
 500  *
 501  * The One-Pass Signature packet precedes the signed data and contains
 502  * enough information to allow the receiver to begin calculating any
 503  * hashes needed to verify the signature.  It allows the Signature
 504  * Packet to be placed at the end of the message, so that the signer can
 505  * compute the entire signed message in one pass.
 506  *
 507  * A One-Pass Signature does not interoperate with PGP 2.6.x or earlier.
 508  *
 509  * The body of this packet consists of:
 510  *   - A one-octet version number. The current version is 3.
 511  *   - A one-octet signature type. Signature types are described in
 512  *     section 5.2.1.
 513  *   - A one-octet number describing the hash algorithm used.
 514  *   - A one-octet number describing the public key algorithm used.
 515  *   - An eight-octet number holding the key ID of the signing key.
 516  *   - A one-octet number holding a flag showing whether the signature
 517  *     is nested.  A zero value indicates that the next packet is
 518  *     another One-Pass Signature packet that describes another
 519  *     signature to be applied to the same message data.
 520  *
 521  * Note that if a message contains more than one one-pass signature,
 522  * then the signature packets bracket the message; that is, the first
 523  * signature packet after the message corresponds to the last one-pass
 524  * packet and the final signature packet corresponds to the first one-
 525  * pass packet.
 526  */
 527 typedef struct pgpPktOnepass_s {
 528     uint8_t version;    /*!< version number (3). */
 529     uint8_t sigtype;    /*!< signature type. */
 530     uint8_t hash_algo;  /*!< hash algorithm. */
 531     uint8_t pubkey_algo;        /*!< public key algorithm. */
 532     pgpKeyID_t signid;  /*!< key ID of signer. */
 533     uint8_t nested;
 534 } * pgpPktOnepass;
 535
 536 /** \ingroup rpmpgp
 537  * 5.5.1. Key Packet Variants
 538  *
 539  * 5.5.1.1. Public Key Packet (Tag 6)
 540  *
 541  * A Public Key packet starts a series of packets that forms an OpenPGP
 542  * key (sometimes called an OpenPGP certificate).
 543  *
 544  * 5.5.1.2. Public Subkey Packet (Tag 14)
 545  *
 546  * A Public Subkey packet (tag 14) has exactly the same format as a
 547  * Public Key packet, but denotes a subkey. One or more subkeys may be
 548  * associated with a top-level key.  By convention, the top-level key
 549  * provides signature services, and the subkeys provide encryption
 550  * services.
 551  *
 552  * Note: in PGP 2.6.x, tag 14 was intended to indicate a comment packet.
 553  * This tag was selected for reuse because no previous version of PGP
 554  * ever emitted comment packets but they did properly ignore them.
 555  * Public Subkey packets are ignored by PGP 2.6.x and do not cause it to
 556  * fail, providing a limited degree of backward compatibility.
 557  *
 558  * 5.5.1.3. Secret Key Packet (Tag 5)
 559  *
 560  * A Secret Key packet contains all the information that is found in a
 561  * Public Key packet, including the public key material, but also
 562  * includes the secret key material after all the public key fields.
 563  *
 564  * 5.5.1.4. Secret Subkey Packet (Tag 7)
 565  *
 566  * A Secret Subkey packet (tag 7) is the subkey analog of the Secret Key
 567  * packet, and has exactly the same format.
 568  *
 569  * 5.5.2. Public Key Packet Formats
 570  *
 571  * There are two versions of key-material packets. Version 3 packets
 572  * were first generated by PGP 2.6. Version 2 packets are identical in
 573  * format to Version 3 packets, but are generated by PGP 2.5 or before.
 574  * V2 packets are deprecated and they MUST NOT be generated.  PGP 5.0
 575  * introduced version 4 packets, with new fields and semantics.  PGP
 576  * 2.6.x will not accept key-material packets with versions greater than
 577  * 3.
 578  *
 579  * OpenPGP implementations SHOULD create keys with version 4 format. An
 580  * implementation MAY generate a V3 key to ensure interoperability with
 581  * old software; note, however, that V4 keys correct some security
 582  * deficiencies in V3 keys. These deficiencies are described below. An
 583  * implementation MUST NOT create a V3 key with a public key algorithm
 584  * other than RSA.
 585  *
 586  * A version 3 public key or public subkey packet contains:
 587  *   - A one-octet version number (3).
 588  *   - A four-octet number denoting the time that the key was created.
 589  *   - A two-octet number denoting the time in days that this key is
 590  *     valid. If this number is zero, then it does not expire.
 591  *   - A one-octet number denoting the public key algorithm of this key
 592  *   - A series of multi-precision integers comprising the key
 593  *     material:
 594  *       - a multiprecision integer (MPI) of RSA public modulus n;
 595  *       - an MPI of RSA public encryption exponent e.
 596  *
 597  * V3 keys SHOULD only be used for backward compatibility because of
 598  * three weaknesses in them. First, it is relatively easy to construct a
 599  * V3 key that has the same key ID as any other key because the key ID
 600  * is simply the low 64 bits of the public modulus. Secondly, because
 601  * the fingerprint of a V3 key hashes the key material, but not its
 602  * length, which increases the opportunity for fingerprint collisions.
 603  * Third, there are minor weaknesses in the MD5 hash algorithm that make
 604  * developers prefer other algorithms. See below for a fuller discussion
 605  * of key IDs and fingerprints.
 606  *
 607  */
 608 typedef struct pgpPktKeyV3_s {
 609     uint8_t version;    /*!< version number (3). */
 610     pgpTime_t time;     /*!< time that the key was created. */
 611     uint8_t valid[2];   /*!< time in days that this key is valid. */
 612     uint8_t pubkey_algo;        /*!< public key algorithm. */
 613 } * pgpPktKeyV3;
 614
 615 /** \ingroup rpmpgp
 616  * The version 4 format is similar to the version 3 format except for
 617  * the absence of a validity period.  This has been moved to the
 618  * signature packet.  In addition, fingerprints of version 4 keys are
 619  * calculated differently from version 3 keys, as described in section
 620  * "Enhanced Key Formats."
 621  *
 622  * A version 4 packet contains:
 623  *   - A one-octet version number (4).
 624  *   - A four-octet number denoting the time that the key was created.
 625  *   - A one-octet number denoting the public key algorithm of this key
 626  *   - A series of multi-precision integers comprising the key
 627  *     material.  This algorithm-specific portion is:
 628  *
 629  *     Algorithm Specific Fields for RSA public keys:
 630  *       - multiprecision integer (MPI) of RSA public modulus n;
 631  *       - MPI of RSA public encryption exponent e.
 632  *
 633  *     Algorithm Specific Fields for DSA public keys:
 634  *       - MPI of DSA prime p;
 635  *       - MPI of DSA group order q (q is a prime divisor of p-1);
 636  *       - MPI of DSA group generator g;
 637  *       - MPI of DSA public key value y (= g**x where x is secret).
 638  *
 639  *     Algorithm Specific Fields for Elgamal public keys:
 640  *       - MPI of Elgamal prime p;
 641  *       - MPI of Elgamal group generator g;
 642  *       - MPI of Elgamal public key value y (= g**x where x is
 643  *         secret).
 644  *
 645  */
 646 typedef struct pgpPktKeyV4_s {
 647     uint8_t version;    /*!< version number (4). */
 648     pgpTime_t time;     /*!< time that the key was created. */
 649     uint8_t pubkey_algo;        /*!< public key algorithm. */
 650 } * pgpPktKeyV4;
 651
 652 /** \ingroup rpmpgp
 653  * 5.5.3. Secret Key Packet Formats
 654  *
 655  * The Secret Key and Secret Subkey packets contain all the data of the
 656  * Public Key and Public Subkey packets, with additional algorithm-
 657  * specific secret key data appended, in encrypted form.
 658  *
 659  * The packet contains:
 660  *   - A Public Key or Public Subkey packet, as described above
 661  *   - One octet indicating string-to-key usage conventions.  0
 662  *     indicates that the secret key data is not encrypted.  255
 663  *     indicates that a string-to-key specifier is being given.  Any
 664  *     other value is a symmetric-key encryption algorithm specifier.
 665  *   - [Optional] If string-to-key usage octet was 255, a one-octet
 666  *     symmetric encryption algorithm.
 667  *   - [Optional] If string-to-key usage octet was 255, a string-to-key
 668  *     specifier.  The length of the string-to-key specifier is implied
 669  *     by its type, as described above.
 670  *   - [Optional] If secret data is encrypted, eight-octet Initial
 671  *     Vector (IV).
 672  *   - Encrypted multi-precision integers comprising the secret key
 673  *     data. These algorithm-specific fields are as described below.
 674  *   - Two-octet checksum of the plaintext of the algorithm-specific
 675  *     portion (sum of all octets, mod 65536).
 676  *
 677  *     Algorithm Specific Fields for RSA secret keys:
 678  *     - multiprecision integer (MPI) of RSA secret exponent d.
 679  *     - MPI of RSA secret prime value p.
 680  *     - MPI of RSA secret prime value q (p < q).
 681  *     - MPI of u, the multiplicative inverse of p, mod q.
 682  *
 683  *     Algorithm Specific Fields for DSA secret keys:
 684  *     - MPI of DSA secret exponent x.
 685  *
 686  *     Algorithm Specific Fields for Elgamal secret keys:
 687  *     - MPI of Elgamal secret exponent x.
 688  *
 689  * Secret MPI values can be encrypted using a passphrase.  If a string-
 690  * to-key specifier is given, that describes the algorithm for
 691  * converting the passphrase to a key, else a simple MD5 hash of the
 692  * passphrase is used.  Implementations SHOULD use a string-to-key
 693  * specifier; the simple hash is for backward compatibility. The cipher
 694  * for encrypting the MPIs is specified in the secret key packet.
 695  *
 696  * Encryption/decryption of the secret data is done in CFB mode using
 697  * the key created from the passphrase and the Initial Vector from the
 698  * packet. A different mode is used with V3 keys (which are only RSA)
 699  * than with other key formats. With V3 keys, the MPI bit count prefix
 700  * (i.e., the first two octets) is not encrypted.  Only the MPI non-
 701  * prefix data is encrypted.  Furthermore, the CFB state is
 702  * resynchronized at the beginning of each new MPI value, so that the
 703  * CFB block boundary is aligned with the start of the MPI data.
 704  *
 705  * With V4 keys, a simpler method is used.  All secret MPI values are
 706  * encrypted in CFB mode, including the MPI bitcount prefix.
 707  *
 708  * The 16-bit checksum that follows the algorithm-specific portion is
 709  * the algebraic sum, mod 65536, of the plaintext of all the algorithm-
 710  * specific octets (including MPI prefix and data).  With V3 keys, the
 711  * checksum is stored in the clear.  With V4 keys, the checksum is
 712  * encrypted like the algorithm-specific data.  This value is used to
 713  * check that the passphrase was correct.
 714  *
 715  */
 716 typedef union pgpPktKey_u {
 717     struct pgpPktKeyV3_s v3;
 718     struct pgpPktKeyV4_s v4;
 719 } pgpPktKey;
 720
 721 /* \ingroup rpmpgp
 722  * 5.6. Compressed Data Packet (Tag 8)
 723  *
 724  * The Compressed Data packet contains compressed data. Typically, this
 725  * packet is found as the contents of an encrypted packet, or following
 726  * a Signature or One-Pass Signature packet, and contains literal data
 727  * packets.
 728  *
 729  * The body of this packet consists of:
 730  *   - One octet that gives the algorithm used to compress the packet.
 731  *   - The remainder of the packet is compressed data.
 732  *
 733  * A Compressed Data Packet's body contains an block that compresses
 734  * some set of packets. See section "Packet Composition" for details on
 735  * how messages are formed.
 736  *
 737  * ZIP-compressed packets are compressed with raw RFC 1951 DEFLATE
 738  * blocks. Note that PGP V2.6 uses 13 bits of compression. If an
 739  * implementation uses more bits of compression, PGP V2.6 cannot
 740  * decompress it.
 741  *
 742  * ZLIB-compressed packets are compressed with RFC 1950 ZLIB-style
 743  * blocks.
 744  */
 745 typedef struct pgpPktCdata_s {
 746     uint8_t compressalgo;
 747     uint8_t data[1];
 748 } pgpPktCdata;
 749
 750 /* \ingroup rpmpgp
 751  * 5.7. Symmetrically Encrypted Data Packet (Tag 9)
 752  *
 753  * The Symmetrically Encrypted Data packet contains data encrypted with
 754  * a symmetric-key algorithm. When it has been decrypted, it will
 755  * typically contain other packets (often literal data packets or
 756  * compressed data packets).
 757  *
 758  * The body of this packet consists of:
 759  *   - Encrypted data, the output of the selected symmetric-key cipher
 760  *     operating in PGP's variant of Cipher Feedback (CFB) mode.
 761  *
 762  * The symmetric cipher used may be specified in an Public-Key or
 763  * Symmetric-Key Encrypted Session Key packet that precedes the
 764  * Symmetrically Encrypted Data Packet.  In that case, the cipher
 765  * algorithm octet is prefixed to the session key before it is
 766  * encrypted.  If no packets of these types precede the encrypted data,
 767  * the IDEA algorithm is used with the session key calculated as the MD5
 768  * hash of the passphrase.
 769  *
 770  * The data is encrypted in CFB mode, with a CFB shift size equal to the
 771  * cipher's block size.  The Initial Vector (IV) is specified as all
 772  * zeros.  Instead of using an IV, OpenPGP prefixes a 10-octet string to
 773  * the data before it is encrypted.  The first eight octets are random,
 774  * and the 9th and 10th octets are copies of the 7th and 8th octets,
 775  * respectively. After encrypting the first 10 octets, the CFB state is
 776  * resynchronized if the cipher block size is 8 octets or less.  The
 777  * last 8 octets of ciphertext are passed through the cipher and the
 778  * block boundary is reset.
 779  *
 780  * The repetition of 16 bits in the 80 bits of random data prefixed to
 781  * the message allows the receiver to immediately check whether the
 782  * session key is incorrect.
 783  */
 784 typedef struct pgpPktEdata_s {
 785     uint8_t data[1];
 786 } pgpPktEdata;
 787
 788 /* \ingroup rpmpgp
 789  * 5.8. Marker Packet (Obsolete Literal Packet) (Tag 10)
 790  *
 791  * An experimental version of PGP used this packet as the Literal
 792  * packet, but no released version of PGP generated Literal packets with
 793  * this tag. With PGP 5.x, this packet has been re-assigned and is
 794  * reserved for use as the Marker packet.
 795  *
 796  * The body of this packet consists of:
 797  *   - The three octets 0x50, 0x47, 0x50 (which spell "PGP" in UTF-8).
 798  *
 799  * Such a packet MUST be ignored when received.  It may be placed at the
 800  * beginning of a message that uses features not available in PGP 2.6.x
 801  * in order to cause that version to report that newer software is
 802  * necessary to process the message.
 803  */
 804 /* \ingroup rpmpgp
 805  * 5.9. Literal Data Packet (Tag 11)
 806  *
 807  * A Literal Data packet contains the body of a message; data that is
 808  * not to be further interpreted.
 809  *
 810  * The body of this packet consists of:
 811  *   - A one-octet field that describes how the data is formatted.
 812  *
 813  * If it is a 'b' (0x62), then the literal packet contains binary data.
 814  * If it is a 't' (0x74), then it contains text data, and thus may need
 815  * line ends converted to local form, or other text-mode changes.  RFC
 816  * 1991 also defined a value of 'l' as a 'local' mode for machine-local
 817  * conversions.  This use is now deprecated.
 818  *   - File name as a string (one-octet length, followed by file name),
 819  *     if the encrypted data should be saved as a file.
 820  *
 821  * If the special name "_CONSOLE" is used, the message is considered to
 822  * be "for your eyes only".  This advises that the message data is
 823  * unusually sensitive, and the receiving program should process it more
 824  * carefully, perhaps avoiding storing the received data to disk, for
 825  * example.
 826  *   - A four-octet number that indicates the modification date of the
 827  *     file, or the creation time of the packet, or a zero that
 828  *     indicates the present time.
 829  *   - The remainder of the packet is literal data.
 830  *
 831  * Text data is stored with <CR><LF> text endings (i.e. network-normal
 832  * line endings).  These should be converted to native line endings by
 833  * the receiving software.
 834  */
 835 typedef struct pgpPktLdata_s {
 836     uint8_t format;
 837     uint8_t filenamelen;
 838     uint8_t filename[1];
 839 } pgpPktLdata;
 840
 841 /* \ingroup rpmpgp
 842  * 5.10. Trust Packet (Tag 12)
 843  *
 844  * The Trust packet is used only within keyrings and is not normally
 845  * exported.  Trust packets contain data that record the user's
 846  * specifications of which key holders are trustworthy introducers,
 847  * along with other information that implementing software uses for
 848  * trust information.
 849  *
 850  * Trust packets SHOULD NOT be emitted to output streams that are
 851  * transferred to other users, and they SHOULD be ignored on any input
 852  * other than local keyring files.
 853  */
 854 typedef struct pgpPktTrust_s {
 855     uint8_t flag;
 856 } pgpPktTrust;
 857
 858 /* \ingroup rpmpgp
 859  * 5.11. User ID Packet (Tag 13)
 860  *
 861  * A User ID packet consists of data that is intended to represent the
 862  * name and email address of the key holder.  By convention, it includes
 863  * an RFC 822 mail name, but there are no restrictions on its content.
 864  * The packet length in the header specifies the length of the user id.
 865  * If it is text, it is encoded in UTF-8.
 866  *
 867  */
 868 typedef struct pgpPktUid_s {
 869     uint8_t userid[1];
 870 } pgpPktUid;
 871
 872 /** \ingroup rpmpgp
 873  */
 874 union pgpPktPre_u {
 875     pgpPktPubkey pubkey;        /*!< 5.1. Public-Key Encrypted Session Key */
 876     pgpPktSig sig;              /*!< 5.2. Signature */
 877     pgpPktSymkey symkey;        /*!< 5.3. Symmetric-Key Encrypted Session-Key */
 878     pgpPktOnepass onepass;      /*!< 5.4. One-Pass Signature */
 879     pgpPktKey key;              /*!< 5.5. Key Material */
 880     pgpPktCdata cdata;          /*!< 5.6. Compressed Data */
 881     pgpPktEdata edata;          /*!< 5.7. Symmetrically Encrypted Data */
 882                                 /*!< 5.8. Marker (obsolete) */
 883     pgpPktLdata ldata;          /*!< 5.9. Literal Data */
 884     pgpPktTrust tdata;          /*!< 5.10. Trust */
 885     pgpPktUid uid;              /*!< 5.11. User ID */
 886 };
 887
 888 /** \ingroup rpmpgp
 889  */
 890 typedef enum pgpArmor_e {
 891     PGPARMOR_ERR_CRC_CHECK              = -7,
 892     PGPARMOR_ERR_BODY_DECODE            = -6,
 893     PGPARMOR_ERR_CRC_DECODE             = -5,
 894     PGPARMOR_ERR_NO_END_PGP             = -4,
 895     PGPARMOR_ERR_UNKNOWN_PREAMBLE_TAG   = -3,
 896     PGPARMOR_ERR_UNKNOWN_ARMOR_TYPE     = -2,
 897     PGPARMOR_ERR_NO_BEGIN_PGP           = -1,
 898 #define PGPARMOR_ERROR  PGPARMOR_ERR_NO_BEGIN_PGP
 899     PGPARMOR_NONE               =  0,
 900     PGPARMOR_MESSAGE            =  1, /*!< MESSAGE */
 901     PGPARMOR_PUBKEY             =  2, /*!< PUBLIC KEY BLOCK */
 902     PGPARMOR_SIGNATURE          =  3, /*!< SIGNATURE */
 903     PGPARMOR_SIGNED_MESSAGE     =  4, /*!< SIGNED MESSAGE */
 904     PGPARMOR_FILE               =  5, /*!< ARMORED FILE */
 905     PGPARMOR_PRIVKEY            =  6, /*!< PRIVATE KEY BLOCK */
 906     PGPARMOR_SECKEY             =  7  /*!< SECRET KEY BLOCK */
 907 } pgpArmor;
 908
 909 /** \ingroup rpmpgp
 910  */
 911 typedef enum pgpArmorKey_e {
 912     PGPARMORKEY_VERSION         = 1, /*!< Version: */
 913     PGPARMORKEY_COMMENT         = 2, /*!< Comment: */
 914     PGPARMORKEY_MESSAGEID       = 3, /*!< MessageID: */
 915     PGPARMORKEY_HASH            = 4, /*!< Hash: */
 916     PGPARMORKEY_CHARSET         = 5  /*!< Charset: */
 917 } pgpArmorKey;
 918
 919 typedef enum pgpValType_e {
 920     PGPVAL_TAG                  = 1,
 921     PGPVAL_ARMORBLOCK           = 2,
 922     PGPVAL_ARMORKEY             = 3,
 923     PGPVAL_SIGTYPE              = 4,
 924     PGPVAL_SUBTYPE              = 5,
 925     PGPVAL_PUBKEYALGO           = 6,
 926     PGPVAL_SYMKEYALGO           = 7,
 927     PGPVAL_COMPRESSALGO         = 8,
 928     PGPVAL_HASHALGO             = 9,
 929     PGPVAL_SERVERPREFS          = 10,
 930 } pgpValType;
 931
 932 /** \ingroup rpmpgp
 933  * Bit(s) to control digest operation.
 934  */
 935 enum rpmDigestFlags_e {
 936     RPMDIGEST_NONE      = 0
 937 };
 938
 939 typedef rpmFlags rpmDigestFlags;
 940
 941 /** \ingroup rpmpgp
 942  * Return string representation of am OpenPGP value.
 943  * @param type          type of value
 944  * @param val           byte value to lookup
 945  * @return              string value of byte
 946  */
 947 const char * pgpValString(pgpValType type, uint8_t val);
 948
 949 /** \ingroup rpmpgp
 950  * Return (native-endian) integer from big-endian representation.
 951  * @param s             pointer to big-endian integer
 952  * @param nbytes        no. of bytes
 953  * @return              native-endian integer
 954  */
 955 static inline
 956 unsigned int pgpGrab(const uint8_t *s, size_t nbytes)
 957 {
 958     size_t i = 0;
 959     size_t nb = (nbytes <= sizeof(i) ? nbytes : sizeof(i));
 960     while (nb--)
 961         i = (i << 8) | *s++;
 962     return i;
 963 }
 964
 965 /** \ingroup rpmpgp
 966  * Return hex formatted representation of bytes.
 967  * @param p             bytes
 968  * @param plen          no. of bytes
 969  * @return              hex formatted string (malloc'ed)
 970  */
 971 char * pgpHexStr(const uint8_t *p, size_t plen);
 972
 973 /** \ingroup rpmpgp
 974  * Calculate OpenPGP public key fingerprint.
 975  * @param pkt           OpenPGP packet (i.e. PGPTAG_PUBLIC_KEY)
 976  * @param pktlen        OpenPGP packet length (no. of bytes)
 977  * @retval fp           public key fingerprint
 978  * @retval fplen        public key fingerprint length
 979  * @return              0 on success, else -1
 980  */
 981 int pgpPubkeyFingerprint(const uint8_t * pkt, size_t pktlen,
 982                          uint8_t **fp, size_t *fplen);
 983
 984 /** \ingroup rpmpgp
 985  * Calculate OpenPGP public key Key ID
 986  * @param pkt           OpenPGP packet (i.e. PGPTAG_PUBLIC_KEY)
 987  * @param pktlen        OpenPGP packet length (no. of bytes)
 988  * @retval keyid        public key Key ID
 989  * @return              0 on success, else -1
 990  */
 991 int pgpPubkeyKeyID(const uint8_t * pkt, size_t pktlen, pgpKeyID_t keyid);
 992
 993 /** \ingroup rpmpgp
 994  * Parse a OpenPGP packet(s).
 995  * @param pkts          OpenPGP packet(s)
 996  * @param pktlen        OpenPGP packet(s) length (no. of bytes)
 997  * @param pkttype       Expected packet type (signature/key) or 0 for any
 998  * @retval ret          signature/pubkey packet parameters on success (alloced)
 999  * @return              -1 on error, 0 on success
1000  */
1001 int pgpPrtParams(const uint8_t *pkts, size_t pktlen, unsigned int pkttype,
1002                  pgpDigParams * ret);
1003
1004 /** \ingroup rpmpgp
1005  * Parse subkey parameters from OpenPGP packet(s).
1006  * @param pkts          OpenPGP packet(s)
1007  * @param pktlen        OpenPGP packet(s) length (no. of bytes)
1008  * @param mainkey       parameters of main key
1009  * @param subkeys       array of subkey parameters (alloced)
1010  * @param subkeysCount  count of subkeys
1011  * @return              -1 on error, 0 on success
1012  */
1013 int pgpPrtParamsSubkeys(const uint8_t *pkts, size_t pktlen,
1014                         pgpDigParams mainkey, pgpDigParams **subkeys,
1015                         int *subkeysCount);
1016 /** \ingroup rpmpgp
1017  * Print/parse a OpenPGP packet(s).
1018  * @param pkts          OpenPGP packet(s)
1019  * @param pktlen        OpenPGP packet(s) length (no. of bytes)
1020  * @retval dig          parsed output of signature/pubkey packet parameters
1021  * @param printing      should packets be printed?
1022  * @return              -1 on error, 0 on success
1023  */
1024 int pgpPrtPkts(const uint8_t *pkts, size_t pktlen, pgpDig dig, int printing);
1025
1026 /** \ingroup rpmpgp
1027  * Parse armored OpenPGP packets from a file.
1028  * @param fn            file name
1029  * @retval pkt          dearmored OpenPGP packet(s) (malloced)
1030  * @retval pktlen       dearmored OpenPGP packet(s) length in bytes
1031  * @return              type of armor found
1032  */
1033 pgpArmor pgpReadPkts(const char * fn, uint8_t ** pkt, size_t * pktlen);
1034
1035 /** \ingroup rpmpgp
1036  * Parse armored OpenPGP packets from memory.
1037  * @param armor         armored OpenPGP packet string
1038  * @retval pkt          dearmored OpenPGP packet(s) (malloced)
1039  * @retval pktlen       dearmored OpenPGP packet(s) length in bytes
1040  * @return              type of armor found
1041  */
1042 pgpArmor pgpParsePkts(const char *armor, uint8_t ** pkt, size_t * pktlen);
1043
1044 /** \ingroup rpmpgp
1045  * Return a length of the first public key certificate in a buffer given
1046  * by pkts that contains one or more certificates. A public key certificate
1047  * consits of packets like Public key packet, User ID packet and so on.
1048  * In a buffer every certificate starts with Public key packet and it ends
1049  * with the start of the next certificate or with the end of the buffer.
1050  *
1051  * @param pkts          pointer to a buffer with certificates
1052  * @param pktslen       length of the buffer with certificates
1053  * @param certlen       length of the first certificate in the buffer
1054  * @return              0 on success
1055  */
1056 int pgpPubKeyCertLen(const uint8_t *pkts, size_t pktslen, size_t *certlen);
1057
1058 /** \ingroup rpmpgp
1059  * Wrap a OpenPGP packets in ascii armor for transport.
1060  * @param atype         type of armor
1061  * @param s             binary pkt data
1062  * @param ns            binary pkt data length
1063  * @return              formatted string
1064  */
1065 char * pgpArmorWrap(int atype, const unsigned char * s, size_t ns);
1066
1067 /** \ingroup rpmpgp
1068  * Create a container for parsed OpenPGP packet(s).
1069  * @return              container
1070  */
1071 pgpDig pgpNewDig(void);
1072
1073 /** \ingroup rpmpgp
1074  * Release (malloc'd) data from container.
1075  * @param dig           container
1076  */
1077 void pgpCleanDig(pgpDig dig);
1078
1079 /** \ingroup rpmpgp
1080  * Destroy a container for parsed OpenPGP packet(s).
1081  * @param dig           container
1082  * @return              NULL always
1083  */
1084 pgpDig pgpFreeDig(pgpDig dig);
1085
1086 /** \ingroup rpmpgp
1087  * Retrieve parameters for parsed OpenPGP packet(s).
1088  * @param dig           container
1089  * @param pkttype       type of params to retrieve (signature / pubkey)
1090  * @return              pointer to OpenPGP parameters, NULL on error/not found
1091  */
1092 pgpDigParams pgpDigGetParams(pgpDig dig, unsigned int pkttype);
1093
1094 /** \ingroup rpmpgp
1095  * Compare OpenPGP packet parameters
1096  * param p1             1st parameter container
1097  * param p2             2nd parameter container
1098  * return               1 if the parameters differ, 0 otherwise
1099  */
1100 int pgpDigParamsCmp(pgpDigParams p1, pgpDigParams p2);
1101
1102 /** \ingroup rpmpgp
1103  * Retrieve OpenPGP algorithm parameters
1104  * param digp           parameter container
1105  * param algotype       PGPVAL_HASHALGO / PGPVAL_PUBKEYALGO
1106  * return               algorithm value, 0 on error
1107  */
1108 unsigned int pgpDigParamsAlgo(pgpDigParams digp, unsigned int algotype);
1109
1110 /** \ingroup rpmpgp
1111  * Destroy parsed OpenPGP packet parameter(s).
1112  * @param digp          parameter container
1113  * @return              NULL always
1114  */
1115 pgpDigParams pgpDigParamsFree(pgpDigParams digp);
1116
1117 /** \ingroup rpmpgp
1118  * Verify a PGP signature.
1119  * @param key           public key
1120  * @param sig           signature
1121  * @param hashctx       digest context
1122  * @return              RPMRC_OK on success
1123  */
1124 rpmRC pgpVerifySignature(pgpDigParams key, pgpDigParams sig, DIGEST_CTX hashctx);
1125
1126 /** \ingroup rpmpgp
1127  * Verify a PGP signature.
1128  * @deprecated          use pgpVerifySignature() instead
1129  *
1130  * @param dig           container
1131  * @param hashctx       digest context
1132  * @return              RPMRC_OK on success
1133  */
1134 rpmRC pgpVerifySig(pgpDig dig, DIGEST_CTX hashctx);
1135
1136 /** \ingroup rpmpgp
1137  * Return a string identification of a PGP signature/pubkey.
1138  * @param digp          signature/pubkey container
1139  * @return              string describing the item and parameters
1140  */
1141 char *pgpIdentItem(pgpDigParams digp);
1142
1143 /** \ingroup rpmpgp
1144  * Perform cryptography initialization.
1145  * It must be called before any cryptography can be used within rpm.
1146  * It's not normally necessary to call it directly as it's called in
1147  * general rpm initialization routines.
1148  * @return              0 on success, -1 on failure
1149  */
1150 int rpmInitCrypto(void);
1151
1152 /** \ingroup rpmpgp
1153  * Shutdown cryptography
1154  */
1155 int rpmFreeCrypto(void);
1156
1157 /** \ingroup rpmpgp
1158  * Duplicate a digest context.
1159  * @param octx          existing digest context
1160  * @return              duplicated digest context
1161  */
1162 DIGEST_CTX rpmDigestDup(DIGEST_CTX octx);
1163
1164 /** \ingroup rpmpgp
1165  * Obtain digest length in bytes.
1166  * @param hashalgo      type of digest
1167  * @return              digest length, zero on invalid algorithm
1168  */
1169 size_t rpmDigestLength(int hashalgo);
1170
1171 /** \ingroup rpmpgp
1172  * Initialize digest.
1173  * Set bit count to 0 and buffer to mysterious initialization constants.
1174  * @param hashalgo      type of digest
1175  * @param flags         bit(s) to control digest operation
1176  * @return              digest context
1177  */
1178 DIGEST_CTX rpmDigestInit(int hashalgo, rpmDigestFlags flags);
1179
1180 /** \ingroup rpmpgp
1181  * Update context with next plain text buffer.
1182  * @param ctx           digest context
1183  * @param data          next data buffer
1184  * @param len           no. bytes of data
1185  * @return              0 on success
1186  */
1187 int rpmDigestUpdate(DIGEST_CTX ctx, const void * data, size_t len);
1188
1189 /** \ingroup rpmpgp
1190  * Return digest and destroy context.
1191  * Final wrapup - pad to 64-byte boundary with the bit pattern
1192  * 1 0* (64-bit count of bits processed, MSB-first)
1193  *
1194  * @param ctx           digest context
1195  * @retval datap        address of returned digest
1196  * @retval lenp         address of digest length
1197  * @param asAscii       return digest as ascii string?
1198  * @return              0 on success
1199  */
1200 int rpmDigestFinal(DIGEST_CTX ctx,
1201         void ** datap,
1202         size_t * lenp, int asAscii);
1203
1204 /** \ingroup rpmpgp
1205  * Create a new digest bundle.
1206  * @return              New digest bundle
1207  */
1208 rpmDigestBundle rpmDigestBundleNew(void);
1209
1210 /** \ingroup rpmpgp
1211  * Free a digest bundle and all contained digest contexts.
1212  * @param bundle        digest bundle
1213  * @return              NULL always
1214  */
1215 rpmDigestBundle rpmDigestBundleFree(rpmDigestBundle bundle);
1216
1217 /** \ingroup rpmpgp
1218  * Add a new type of digest to a bundle. Same as calling
1219  * rpmDigestBundleAddID() with algo == id value.
1220  * @param bundle        digest bundle
1221  * @param algo          type of digest
1222  * @param flags         bit(s) to control digest operation
1223  * @return              0 on success
1224  */
1225 int rpmDigestBundleAdd(rpmDigestBundle bundle, int algo,
1226                         rpmDigestFlags flags);
1227
1228 /** \ingroup rpmpgp
1229  * Add a new type of digest to a bundle.
1230  * @param bundle        digest bundle
1231  * @param algo          type of digest
1232  * @param id            id of digest (arbitrary, must be > 0)
1233  * @param flags         bit(s) to control digest operation
1234  * @return              0 on success
1235  */
1236 int rpmDigestBundleAddID(rpmDigestBundle bundle, int algo, int id,
1237                          rpmDigestFlags flags);
1238
1239 /** \ingroup rpmpgp
1240  * Update contexts within bundle with next plain text buffer.
1241  * @param bundle        digest bundle
1242  * @param data          next data buffer
1243  * @param len           no. bytes of data
1244  * @return              0 on success
1245  */
1246 int rpmDigestBundleUpdate(rpmDigestBundle bundle, const void *data, size_t len);
1247
1248 /** \ingroup rpmpgp
1249  * Return digest from a bundle and destroy context, see rpmDigestFinal().
1250  *
1251  * @param bundle        digest bundle
1252  * @param id            id of digest to return
1253  * @retval datap        address of returned digest
1254  * @retval lenp         address of digest length
1255  * @param asAscii       return digest as ascii string?
1256  * @return              0 on success
1257  */
1258 int rpmDigestBundleFinal(rpmDigestBundle bundle, int id,
1259                          void ** datap, size_t * lenp, int asAscii);
1260
1261 /** \ingroup rpmpgp
1262  * Duplicate a digest context from a bundle.
1263  * @param bundle        digest bundle
1264  * @param id            id of digest to dup
1265  * @return              duplicated digest context
1266  */
1267 DIGEST_CTX rpmDigestBundleDupCtx(rpmDigestBundle bundle, int id);
1268
1269 #ifdef __cplusplus
1270 }
1271 #endif
1272
1273 #endif  /* H_RPMPGP */