gpg-packet.h

   1 /*
   2  * Copyright (c) 2008, Dave Korn.
   3  *
   4  *     This program is free software; you can redistribute it and/or modify
   5  *     it under the terms of the GNU General Public License as published by
   6  *     the Free Software Foundation; either version 2 of the License, or
   7  *     (at your option) any later version.
   8  *
   9  *     A copy of the GNU General Public License can be found at
  10  *     http://www.gnu.org/
  11  *
  12  *   This module contains support utilities to assist in reading and
  13  * parsing RFC4880-compliant OpenPGP format signature and key files,
  14  * and related constant definitions.
  15  *
  16  *
  17  * Written by Dave Korn <dave.korn.cygwin@gmail.com>
  18  *
  19  */
  20
  21 #ifndef SETUP_GPG_PACKET_H
  22 #define SETUP_GPG_PACKET_H
  23
  24
  25 /*
  26
  27 4.3.  Packet Tags
  28
  29    The packet tag denotes what type of packet the body holds.  Note that
  30    old format headers can only have tags less than 16, whereas new
  31    format headers can have tags as great as 63.  The defined tags (in
  32    decimal) are as follows:
  33
  34        0        -- Reserved - a packet tag MUST NOT have this value
  35        1        -- Public-Key Encrypted Session Key Packet
  36        2        -- Signature Packet
  37        3        -- Symmetric-Key Encrypted Session Key Packet
  38        4        -- One-Pass Signature Packet
  39        5        -- Secret-Key Packet
  40        6        -- Public-Key Packet
  41        7        -- Secret-Subkey Packet
  42        8        -- Compressed Data Packet
  43        9        -- Symmetrically Encrypted Data Packet
  44        10       -- Marker Packet
  45        11       -- Literal Data Packet
  46        12       -- Trust Packet
  47        13       -- User ID Packet
  48        14       -- Public-Subkey Packet
  49        17       -- User Attribute Packet
  50        18       -- Sym. Encrypted and Integrity Protected Data Packet
  51        19       -- Modification Detection Code Packet
  52        60 to 63 -- Private or Experimental Values
  53
  54
  55 */
  56
  57 #define RFC4880_PT_SIGNATURE  2
  58 #define RFC4880_PT_PUBLIC_KEY 6
  59
  60
  61 /*
  62
  63 9.1.  Public-Key Algorithms
  64
  65       ID           Algorithm
  66       --           ---------
  67       1          - RSA (Encrypt or Sign) [HAC]
  68       2          - RSA Encrypt-Only [HAC]
  69       3          - RSA Sign-Only [HAC]
  70       16         - Elgamal (Encrypt-Only) [ELGAMAL] [HAC]
  71       17         - DSA (Digital Signature Algorithm) [FIPS186] [HAC]
  72       18         - Reserved for Elliptic Curve
  73       19         - Reserved for ECDSA
  74       20         - Reserved (formerly Elgamal Encrypt or Sign)
  75       21         - Reserved for Diffie-Hellman (X9.42,
  76                    as defined for IETF-S/MIME)
  77       100 to 110 - Private/Experimental algorithm
  78
  79    Implementations MUST implement DSA for signatures, and Elgamal for
  80    encryption.  Implementations SHOULD implement RSA keys (1).  RSA
  81    Encrypt-Only (2) and RSA Sign-Only are deprecated and SHOULD NOT be
  82    generated, but may be interpreted.  See Section 13.5.  See Section
  83    13.8 for notes on Elliptic Curve (18), ECDSA (19), Elgamal Encrypt or
  84    Sign (20), and X9.42 (21).  Implementations MAY implement any other
  85    algorithm.
  86
  87 */
  88
  89 #define RFC4880_PK_RSA        1
  90 #define RFC4880_PK_RSA_EO     2
  91 #define RFC4880_PK_RSA_SO     3
  92 #define RFC4880_PK_ELGAMAL    16
  93 #define RFC4880_PK_DSA        17
  94
  95
  96 /*
  97 5.2.1.  Signature Types
  98
  99    There are a number of possible meanings for a signature, which are
 100    indicated in a signature type octet in any given signature.  Please
 101    note that the vagueness of these meanings is not a flaw, but a
 102    feature of the system.  Because OpenPGP places final authority for
 103    validity upon the receiver of a signature, it may be that one
 104    signer's casual act might be more rigorous than some other
 105    authority's positive act.  See Section 5.2.4, "Computing Signatures",
 106    for detailed information on how to compute and verify signatures of
 107    each type.
 108
 109    These meanings are as follows:
 110
 111    0x00: Signature of a binary document.
 112        This means the signer owns it, created it, or certifies that it
 113        has not been modified.
 114
 115    0x01: Signature of a canonical text document.
 116        This means the signer owns it, created it, or certifies that it
 117        has not been modified.  The signature is calculated over the text
 118        data with its line endings converted to <CR><LF>.
 119
 120    0x02: Standalone signature.
 121    0x10: Generic certification of a User ID and Public-Key packet.
 122    0x11: Persona certification of a User ID and Public-Key packet.
 123    0x12: Casual certification of a User ID and Public-Key packet.
 124    0x13: Positive certification of a User ID and Public-Key packet.
 125    0x18: Subkey Binding Signature
 126    0x19: Primary Key Binding Signature
 127    0x1F: Signature directly on a key
 128    0x20: Key revocation signature
 129    0x28: Subkey revocation signature
 130    0x30: Certification revocation signature
 131    0x40: Timestamp signature.
 132    0x50: Third-Party Confirmation signature.
 133
 134 */
 135 #define RFC4880_ST_BINARY     0
 136 #define RFC4880_ST_CANONTEXT  1
 137
 138
 139 /*
 140 9.4.  Hash Algorithms
 141
 142       ID           Algorithm                             Text Name
 143       --           ---------                             ---------
 144       1          - MD5 [HAC]                             "MD5"
 145       2          - SHA-1 [FIPS180]                       "SHA1"
 146       3          - RIPE-MD/160 [HAC]                     "RIPEMD160"
 147       4          - Reserved
 148       5          - Reserved
 149       6          - Reserved
 150       7          - Reserved
 151       8          - SHA256 [FIPS180]                      "SHA256"
 152       9          - SHA384 [FIPS180]                      "SHA384"
 153       10         - SHA512 [FIPS180]                      "SHA512"
 154       11         - SHA224 [FIPS180]                      "SHA224"
 155       100 to 110 - Private/Experimental algorithm
 156
 157    Implementations MUST implement SHA-1.  Implementations MAY implement
 158    other algorithms.  MD5 is deprecated.
 159 */
 160
 161 #define RFC4880_HC_MD5        1
 162 #define RFC4880_HC_SHA1       2
 163 #define RFC4880_HC_RIPEMD160  3
 164 #define RFC4880_HC_SHA256     8
 165 #define RFC4880_HC_SHA384     9
 166 #define RFC4880_HC_SHA512     10
 167 #define RFC4880_HC_SHA224     11
 168
 169
 170 // This enum is returned by the callback function that is
 171 // invoked by the packet walker for every packet walked;
 172 // it tells it to continue or go home early.
 173 enum pkt_cb_resp
 174 {
 175   pktCONTINUE,
 176   pktHALT
 177 };
 178
 179 // Forward declaration of context data struct.
 180 struct packet_walker;
 181
 182 // The type of callback function that can be called for every
 183 // packet walked.
 184 typedef enum pkt_cb_resp (*packet_walk_cb)
 185         (struct packet_walker *wlk, unsigned char tag, size_t packetsize,
 186         size_t hdrpos);
 187
 188 // This struct is used to wrap the context data for a packet walk.
 189 struct packet_walker
 190 {
 191   io_stream *pfile;
 192   packet_walk_cb func;
 193   HWND owner;
 194   void *userdata;
 195   size_t startpos;
 196   size_t size_to_walk;
 197   bool is_subpackets;
 198 };
 199
 200 /*
 201
 202 3.  Data Element Formats
 203
 204    This section describes the data elements used by OpenPGP.
 205
 206 3.1.  Scalar Numbers
 207
 208    Scalar numbers are unsigned and are always stored in big-endian
 209    format.  Using n[k] to refer to the kth octet being interpreted, the
 210    value of a two-octet scalar is ((n[0] << 8) + n[1]).  The value of a
 211    four-octet scalar is ((n[0] << 24) + (n[1] << 16) + (n[2] << 8) +
 212    n[3]).
 213
 214 */
 215
 216 /*  Extract a byte/char from file.  Returns EOF if none left. */
 217 static inline int
 218 pkt_getch (io_stream *file)
 219 {
 220   unsigned char ch;
 221   if (file->read (&ch, 1) != 1)
 222     return EOF;
 223   return ch;
 224 }
 225
 226 /*  Extract a 16-bit BE int from file.  Returns EOF if none left. */
 227 static inline long
 228 pkt_getword (io_stream *file)
 229 {
 230   unsigned char ch[2];
 231   if (file->read (&ch, 2) != 2)
 232     return EOF;
 233   return (ch[0] << 8) | ch[1];
 234 }
 235
 236 /*  Extract a 32-bit BE int from file.  Returns EOF if none left.
 237   Determining the difference between EOF and 0xffffffff is left
 238   as an exercise for the caller - in the contexts where we need
 239   a dword (packet len, timestamp, signer id), we wouldn't expect
 240   to find ~0 anyway and so may safely leave it as a false positive.
 241   Note that this would cause problems with setup.ini files signed
 242   in the last second before the epoch rolls over.  Workaround: WDDTT.  */
 243 static inline long
 244 pkt_getdword (io_stream *file)
 245 {
 246   unsigned char ch[4];
 247   if (file->read (&ch, 4) != 4)
 248     return EOF;
 249   return (ch[0] << 24) | (ch[1] << 16) | (ch[2] << 8) | ch[3];
 250 }
 251
 252 /*  Extract an RFC4880 variable-length length field from file.
 253    Returns EOF if none left or negative if invalid format. */
 254 extern long pkt_getlen (io_stream *file);
 255
 256 /*  Extract an RFC4880 MPI field from file.
 257    Returns EOF if none left or negative if invalid format. */
 258 extern int pkt_get_mpi (gcry_mpi_t *mpiptr, io_stream *file);
 259
 260 /*  Converts from RFC4880 hash codes (9.4 above) to the hash
 261    algorithm constants used in libgcrypt and the rest of the code.  */
 262 extern char pkt_convert_hashcode (char rfc_hash);
 263
 264 /*  Two functions for walking the (sub)packets found within a
 265    seleected region of an io_stream, calling a hook for each one.  */
 266 extern void *pkt_walk_packets (io_stream *packet_file, packet_walk_cb func,
 267         HWND owner, size_t startpos, size_t size_to_walk, void *userdata);
 268
 269 extern void *pkt_walk_subpackets (io_stream *packet_file, packet_walk_cb func,
 270         HWND owner, size_t startpos, size_t size_to_walk, void *userdata);
 271
 272
 273
 274 #endif /* SETUP_GPG_PACKET_H */