g10/packet.h

   1 /* packet.h - OpenPGP packet definitions
   2  * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
   3  *               2007 Free Software Foundation, Inc.
   4  * Copyright (C) 2015 g10 Code GmbH
   5  *
   6  * This file is part of GnuPG.
   7  *
   8  * GnuPG is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 3 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * GnuPG is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, see <https://www.gnu.org/licenses/>.
  20  */
  21
  22 #ifndef G10_PACKET_H
  23 #define G10_PACKET_H
  24
  25 #include "types.h"
  26 #include "../common/iobuf.h"
  27 #include "../common/strlist.h"
  28 #include "dek.h"
  29 #include "filter.h"
  30 #include "../common/openpgpdefs.h"
  31 #include "../common/userids.h"
  32 #include "util.h"
  33
  34 #define DEBUG_PARSE_PACKET 1
  35
  36
  37 /* Constants to allocate static MPI arrays. */
  38 #define PUBKEY_MAX_NPKEY  5
  39 #define PUBKEY_MAX_NSKEY  7
  40 #define PUBKEY_MAX_NSIG   2
  41 #define PUBKEY_MAX_NENC   2
  42
  43 /* Usage flags */
  44 #define PUBKEY_USAGE_SIG     GCRY_PK_USAGE_SIGN  /* Good for signatures. */
  45 #define PUBKEY_USAGE_ENC     GCRY_PK_USAGE_ENCR  /* Good for encryption. */
  46 #define PUBKEY_USAGE_CERT    GCRY_PK_USAGE_CERT  /* Also good to certify keys.*/
  47 #define PUBKEY_USAGE_AUTH    GCRY_PK_USAGE_AUTH  /* Good for authentication. */
  48 #define PUBKEY_USAGE_UNKNOWN GCRY_PK_USAGE_UNKN  /* Unknown usage flag. */
  49 #define PUBKEY_USAGE_NONE    256                 /* No usage given. */
  50 #if  (GCRY_PK_USAGE_SIGN | GCRY_PK_USAGE_ENCR | GCRY_PK_USAGE_CERT \
  51       | GCRY_PK_USAGE_AUTH | GCRY_PK_USAGE_UNKN) >= 256
  52 # error Please choose another value for PUBKEY_USAGE_NONE
  53 #endif
  54
  55 /* Helper macros.  */
  56 #define is_RSA(a)     ((a)==PUBKEY_ALGO_RSA || (a)==PUBKEY_ALGO_RSA_E \
  57                        || (a)==PUBKEY_ALGO_RSA_S )
  58 #define is_ELGAMAL(a) ((a)==PUBKEY_ALGO_ELGAMAL_E)
  59 #define is_DSA(a)     ((a)==PUBKEY_ALGO_DSA)
  60
  61 /* A pointer to the packet object.  */
  62 typedef struct packet_struct PACKET;
  63
  64 /* PKT_GPG_CONTROL types */
  65 typedef enum {
  66     CTRLPKT_CLEARSIGN_START = 1,
  67     CTRLPKT_PIPEMODE = 2,
  68     CTRLPKT_PLAINTEXT_MARK =3
  69 } ctrlpkttype_t;
  70
  71 typedef enum {
  72     PREFTYPE_NONE = 0,
  73     PREFTYPE_SYM = 1,
  74     PREFTYPE_HASH = 2,
  75     PREFTYPE_ZIP = 3
  76 } preftype_t;
  77
  78 typedef struct {
  79     byte type;
  80     byte value;
  81 } prefitem_t;
  82
  83 /* A string-to-key specifier as defined in RFC 4880, Section 3.7.  */
  84 typedef struct
  85 {
  86   int  mode;      /* Must be an integer due to the GNU modes 1001 et al.  */
  87   byte hash_algo;
  88   byte salt[8];
  89   /* The *coded* (i.e., the serialized version) iteration count.  */
  90   u32  count;
  91 } STRING2KEY;
  92
  93 /* A symmetric-key encrypted session key packet as defined in RFC
  94    4880, Section 5.3.  All fields are serialized.  */
  95 typedef struct {
  96   /* RFC 4880: this must be 4.  */
  97   byte version;
  98   /* The cipher algorithm used to encrypt the session key.  (This may
  99      be different from the algorithm that is used to encrypt the SED
 100      packet.)  */
 101   byte cipher_algo;
 102   /* The string-to-key specifier.  */
 103   STRING2KEY s2k;
 104   /* The length of SESKEY in bytes or 0 if this packet does not
 105      encrypt a session key.  (In the latter case, the results of the
 106      S2K function on the password is the session key. See RFC 4880,
 107      Section 5.3.)  */
 108   byte seskeylen;
 109   /* The session key as encrypted by the S2K specifier.  */
 110   byte seskey[1];
 111 } PKT_symkey_enc;
 112
 113 /* A public-key encrypted session key packet as defined in RFC 4880,
 114    Section 5.1.  All fields are serialized.  */
 115 typedef struct {
 116   /* The 64-bit keyid.  */
 117   u32     keyid[2];
 118   /* The packet's version.  Currently, only version 3 is defined.  */
 119   byte    version;
 120   /* The algorithm used for the public key encryption scheme.  */
 121   byte    pubkey_algo;
 122   /* Whether to hide the key id.  This value is not directly
 123      serialized.  */
 124   byte    throw_keyid;
 125   /* The session key.  */
 126   gcry_mpi_t     data[PUBKEY_MAX_NENC];
 127 } PKT_pubkey_enc;
 128
 129
 130 /* A one-pass signature packet as defined in RFC 4880, Section
 131    5.4.  All fields are serialized.  */
 132 typedef struct {
 133     u32     keyid[2];       /* The 64-bit keyid */
 134     /* The signature's classification (RFC 4880, Section 5.2.1).  */
 135     byte    sig_class;
 136     byte    digest_algo;    /* algorithm used for digest */
 137     byte    pubkey_algo;    /* algorithm used for public key scheme */
 138     /* A message can be signed by multiple keys.  In this case, there
 139        are n one-pass signature packets before the message to sign and
 140        n signatures packets after the message.  It is conceivable that
 141        someone wants to not only sign the message, but all of the
 142        signatures.  Now we need to distinguish between signing the
 143        message and signing the message plus the surrounding
 144        signatures.  This is the point of this flag.  If set, it means:
 145        I sign all of the data starting at the next packet.  */
 146     byte    last;
 147 } PKT_onepass_sig;
 148
 149
 150 /* A v4 OpenPGP signature has a hashed and unhashed area containing
 151    co-called signature subpackets (RFC 4880, Section 5.2.3).  These
 152    areas are described by this data structure.  Use enum_sig_subpkt to
 153    parse this area.  */
 154 typedef struct {
 155     size_t size;  /* allocated */
 156     size_t len;   /* used (serialized) */
 157     byte data[1]; /* the serialized subpackes (serialized) */
 158 } subpktarea_t;
 159
 160 /* The in-memory representation of a designated revoker signature
 161    subpacket (RFC 4880, Section 5.2.3.15).  */
 162 struct revocation_key {
 163   /* A bit field.  0x80 must be set.  0x40 means this information is
 164      sensitive (and should not be uploaded to a keyserver by
 165      default).  */
 166   byte class;
 167   /* The public-key algorithm ID.  */
 168   byte algid;
 169   /* The fingerprint of the authorized key.  */
 170   byte fpr[MAX_FINGERPRINT_LEN];
 171 };
 172
 173
 174 /* Object to keep information about a PKA DNS record. */
 175 typedef struct
 176 {
 177   int valid;    /* An actual PKA record exists for EMAIL. */
 178   int checked;  /* Set to true if the FPR has been checked against the
 179                    actual key. */
 180   char *uri;    /* Malloced string with the URI. NULL if the URI is
 181                    not available.*/
 182   unsigned char fpr[20]; /* The fingerprint as stored in the PKA RR. */
 183   char email[1];/* The email address from the notation data. */
 184 } pka_info_t;
 185
 186
 187 /* A signature packet (RFC 4880, Section 5.2).  Only a subset of these
 188    fields are directly serialized (these are marked as such); the rest
 189    are read from the subpackets, which are not synthesized when
 190    serializing this data structure (i.e., when using build_packet()).
 191    Instead, the subpackets must be created by hand.  */
 192 typedef struct
 193 {
 194   struct
 195   {
 196     unsigned checked:1;         /* Signature has been checked. */
 197     unsigned valid:1;           /* Signature is good (if checked is set). */
 198     unsigned chosen_selfsig:1;  /* A selfsig that is the chosen one. */
 199     unsigned unknown_critical:1;
 200     unsigned exportable:1;
 201     unsigned revocable:1;
 202     unsigned policy_url:1;  /* At least one policy URL is present */
 203     unsigned notation:1;    /* At least one notation is present */
 204     unsigned pref_ks:1;     /* At least one preferred keyserver is present */
 205     unsigned expired:1;
 206     unsigned pka_tried:1;   /* Set if we tried to retrieve the PKA record. */
 207   } flags;
 208   /* The key that allegedly generated this signature.  (Directly
 209      serialized in v3 sigs; for v4 sigs, this must be explicitly added
 210      as an issuer subpacket (5.2.3.5.)  */
 211   u32     keyid[2];
 212   /* When the signature was made (seconds since the Epoch).  (Directly
 213      serialized in v3 sigs; for v4 sigs, this must be explicitly added
 214      as a signature creation time subpacket (5.2.3.4).)  */
 215   u32     timestamp;
 216   u32     expiredate;     /* Expires at this date or 0 if not at all. */
 217   /* The serialization format used / to use.  If 0, then defaults to
 218      version 3.  (Serialized.)  */
 219   byte    version;
 220   /* The signature type. (See RFC 4880, Section 5.2.1.)  */
 221   byte    sig_class;
 222   /* Algorithm used for public key scheme (e.g., PUBKEY_ALGO_RSA).
 223      (Serialized.)  */
 224   byte    pubkey_algo;
 225   /* Algorithm used for digest (e.g., DIGEST_ALGO_SHA1).
 226      (Serialized.)  */
 227   byte    digest_algo;
 228   byte    trust_depth;
 229   byte    trust_value;
 230   const byte *trust_regexp;
 231   struct revocation_key *revkey;
 232   int numrevkeys;
 233   pka_info_t *pka_info;      /* Malloced PKA data or NULL if not
 234                                 available.  See also flags.pka_tried. */
 235   char *signers_uid;         /* Malloced value of the SIGNERS_UID
 236                               * subpacket or NULL.  This string has
 237                               * already been sanitized.  */
 238   subpktarea_t *hashed;      /* All subpackets with hashed data (v4 only). */
 239   subpktarea_t *unhashed;    /* Ditto for unhashed data. */
 240   /* First 2 bytes of the digest.  (Serialized.  Note: this is not
 241      automatically filled in when serializing a signature!)  */
 242   byte digest_start[2];
 243   /* The signature.  (Serialized.)  */
 244   gcry_mpi_t  data[PUBKEY_MAX_NSIG];
 245   /* The message digest and its length (in bytes).  Note the maximum
 246      digest length is 512 bits (64 bytes).  If DIGEST_LEN is 0, then
 247      the digest's value has not been saved here.  */
 248   byte digest[512 / 8];
 249   int digest_len;
 250 } PKT_signature;
 251
 252 #define ATTRIB_IMAGE 1
 253
 254 /* This is the cooked form of attributes.  */
 255 struct user_attribute {
 256   byte type;
 257   const byte *data;
 258   u32 len;
 259 };
 260
 261
 262 /* A user id (RFC 4880, Section 5.11) or a user attribute packet (RFC
 263    4880, Section 5.12).  Only a subset of these fields are directly
 264    serialized (these are marked as such); the rest are read from the
 265    self-signatures in merge_keys_and_selfsig()).  */
 266 typedef struct
 267 {
 268   int ref;              /* reference counter */
 269   /* The length of NAME.  */
 270   int len;
 271   struct user_attribute *attribs;
 272   int numattribs;
 273   /* If this is not NULL, the packet is a user attribute rather than a
 274      user id (See RFC 4880 5.12).  (Serialized.)  */
 275   byte *attrib_data;
 276   /* The length of ATTRIB_DATA.  */
 277   unsigned long attrib_len;
 278   byte *namehash;
 279   int help_key_usage;
 280   u32 help_key_expire;
 281   int help_full_count;
 282   int help_marginal_count;
 283   int is_primary;       /* 2 if set via the primary flag, 1 if calculated */
 284   int is_revoked;
 285   int is_expired;
 286   u32 expiredate;       /* expires at this date or 0 if not at all */
 287   prefitem_t *prefs;    /* list of preferences (may be NULL)*/
 288   u32 created;          /* according to the self-signature */
 289   byte selfsigversion;
 290   struct
 291   {
 292     /* TODO: Move more flags here */
 293     unsigned int mdc:1;
 294     unsigned int ks_modify:1;
 295     unsigned int compacted:1;
 296   } flags;
 297   char *mbox;   /* NULL or the result of mailbox_from_userid.  */
 298   /* The text contained in the user id packet, which is normally the
 299      name and email address of the key holder (See RFC 4880 5.11).
 300      (Serialized.). For convenience an extra Nul is always appended.  */
 301   char name[1];
 302 } PKT_user_id;
 303
 304
 305
 306 struct revoke_info
 307 {
 308   /* revoked at this date */
 309   u32 date;
 310   /* the keyid of the revoking key (selfsig or designated revoker) */
 311   u32 keyid[2];
 312   /* the algo of the revoking key */
 313   byte algo;
 314 };
 315
 316
 317 /* Information pertaining to secret keys. */
 318 struct seckey_info
 319 {
 320   int is_protected:1;   /* The secret info is protected and must */
 321                         /* be decrypted before use, the protected */
 322                         /* MPIs are simply (void*) pointers to memory */
 323                         /* and should never be passed to a mpi_xxx() */
 324   int sha1chk:1;        /* SHA1 is used instead of a 16 bit checksum */
 325   u16 csum;             /* Checksum for old protection modes.  */
 326   byte algo;            /* Cipher used to protect the secret information. */
 327   STRING2KEY s2k;       /* S2K parameter.  */
 328   byte ivlen;           /* Used length of the IV.  */
 329   byte iv[16];          /* Initialization vector for CFB mode.  */
 330 };
 331
 332
 333 /****************
 334  * The in-memory representation of a public key (RFC 4880, Section
 335  * 5.5).  Note: this structure contains significantly more information
 336  * than is contained in an OpenPGP public key packet.  This
 337  * information is derived from the self-signed signatures (by
 338  * merge_keys_and_selfsig()) and is ignored when serializing the
 339  * packet.  The fields that are actually written out when serializing
 340  * this packet are marked as accordingly.
 341  *
 342  * We assume that secret keys have the same number of parameters as
 343  * the public key and that the public parameters are the first items
 344  * in the PKEY array.  Thus NPKEY is always less than NSKEY and it is
 345  * possible to compare the secret and public keys by comparing the
 346  * first NPKEY elements of the PKEY array.  Note that since GnuPG 2.1
 347  * we don't use secret keys anymore directly because they are managed
 348  * by gpg-agent.  However for parsing OpenPGP key files we need a way
 349  * to temporary store those secret keys.  We do this by putting them
 350  * into the public key structure and extending the PKEY field to NSKEY
 351  * elements; the extra secret key information are stored in the
 352  * SECKEY_INFO field.
 353  */
 354 typedef struct
 355 {
 356   /* When the key was created.  (Serialized.)  */
 357   u32     timestamp;
 358   u32     expiredate;     /* expires at this date or 0 if not at all */
 359   u32     max_expiredate; /* must not expire past this date */
 360   struct revoke_info revoked;
 361   /* An OpenPGP packet consists of a header and a body.  This is the
 362      size of the header.  If this is 0, an appropriate size is
 363      automatically chosen based on the size of the body.
 364      (Serialized.)  */
 365   byte    hdrbytes;
 366   /* The serialization format.  If 0, the default version (4) is used
 367      when serializing.  (Serialized.)  */
 368   byte    version;
 369   byte    selfsigversion; /* highest version of all of the self-sigs */
 370   /* The public key algorithm.  (Serialized.)  */
 371   byte    pubkey_algo;
 372   byte    pubkey_usage;   /* for now only used to pass it to getkey() */
 373   byte    req_usage;      /* hack to pass a request to getkey() */
 374   u32     has_expired;    /* set to the expiration date if expired */
 375   /* keyid of the primary key.  Never access this value directly.
 376      Instead, use pk_main_keyid().  */
 377   u32     main_keyid[2];
 378   /* keyid of this key.  Never access this value directly!  Instead,
 379      use pk_keyid().  */
 380   u32     keyid[2];
 381   prefitem_t *prefs;      /* list of preferences (may be NULL) */
 382   struct
 383   {
 384     unsigned int mdc:1;           /* MDC feature set.  */
 385     unsigned int disabled_valid:1;/* The next flag is valid.  */
 386     unsigned int disabled:1;      /* The key has been disabled.  */
 387     unsigned int primary:1;       /* This is a primary key.  */
 388     unsigned int revoked:2;       /* Key has been revoked.
 389                                      1 = revoked by the owner
 390                                      2 = revoked by designated revoker.  */
 391     unsigned int maybe_revoked:1; /* A designated revocation is
 392                                      present, but without the key to
 393                                      check it.  */
 394     unsigned int valid:1;         /* Key (especially subkey) is valid.  */
 395     unsigned int dont_cache:1;    /* Do not cache this key.  */
 396     unsigned int backsig:2;       /* 0=none, 1=bad, 2=good.  */
 397     unsigned int serialno_valid:1;/* SERIALNO below is valid.  */
 398     unsigned int exact:1;         /* Found via exact (!) search.  */
 399   } flags;
 400   PKT_user_id *user_id;   /* If != NULL: found by that uid. */
 401   struct revocation_key *revkey;
 402   int     numrevkeys;
 403   u32     trust_timestamp;
 404   byte    trust_depth;
 405   byte    trust_value;
 406   const byte *trust_regexp;
 407   char    *serialno;      /* Malloced hex string or NULL if it is
 408                              likely not on a card.  See also
 409                              flags.serialno_valid.  */
 410   /* If not NULL this malloced structure describes a secret key.
 411      (Serialized.)  */
 412   struct seckey_info *seckey_info;
 413   /* The public key.  Contains pubkey_get_npkey (pubkey_algo) +
 414      pubkey_get_nskey (pubkey_algo) MPIs.  (If pubkey_get_npkey
 415      returns 0, then the algorithm is not understood and the PKEY
 416      contains a single opaque MPI.)  (Serialized.)  */
 417   gcry_mpi_t  pkey[PUBKEY_MAX_NSKEY]; /* Right, NSKEY elements.  */
 418 } PKT_public_key;
 419
 420 /* Evaluates as true if the pk is disabled, and false if it isn't.  If
 421    there is no disable value cached, fill one in. */
 422 #define pk_is_disabled(a)                                       \
 423   (((a)->flags.disabled_valid)?                                 \
 424    ((a)->flags.disabled):(cache_disabled_value((a))))
 425
 426
 427 typedef struct {
 428     int  len;             /* length of data */
 429     char data[1];
 430 } PKT_comment;
 431
 432 /* A compression packet (RFC 4880, Section 5.6).  */
 433 typedef struct {
 434   /* Not used.  */
 435   u32 len;
 436   /* Whether the serialized version of the packet used / should use
 437      the new format.  */
 438   byte  new_ctb;
 439   /* The compression algorithm.  */
 440   byte  algorithm;
 441   /* An iobuf holding the data to be decompressed.  (This is not used
 442      for compression!)  */
 443   iobuf_t buf;
 444 } PKT_compressed;
 445
 446 /* A symmetrically encrypted data packet (RFC 4880, Section 5.7) or a
 447    symmetrically encrypted integrity protected data packet (Section
 448    5.13) */
 449 typedef struct {
 450   /* Remaining length of encrypted data. */
 451   u32  len;
 452   /* When encrypting, the first block size bytes of data are random
 453      data and the following 2 bytes are copies of the last two bytes
 454      of the random data (RFC 4880, Section 5.7).  This provides a
 455      simple check that the key is correct.  extralen is the size of
 456      this extra data.  This is used by build_packet when writing out
 457      the packet's header. */
 458   int  extralen;
 459   /* Whether the serialized version of the packet used / should use
 460      the new format.  */
 461   byte new_ctb;
 462   /* Whether the packet has an indeterminate length (old format) or
 463      was encoded using partial body length headers (new format).
 464      Note: this is ignored when encrypting.  */
 465   byte is_partial;
 466   /* If 0, MDC is disabled.  Otherwise, the MDC method that was used
 467      (currently, only DIGEST_ALGO_SHA1 is supported).  */
 468   byte mdc_method;
 469   /* An iobuf holding the data to be decrypted.  (This is not used for
 470      encryption!)  */
 471   iobuf_t buf;
 472 } PKT_encrypted;
 473
 474 typedef struct {
 475     byte hash[20];
 476 } PKT_mdc;
 477
 478 typedef struct {
 479     unsigned int trustval;
 480     unsigned int sigcache;
 481 } PKT_ring_trust;
 482
 483 /* A plaintext packet (see RFC 4880, 5.9).  */
 484 typedef struct {
 485   /* The length of data in BUF or 0 if unknown.  */
 486   u32  len;
 487   /* A buffer containing the data stored in the packet's body.  */
 488   iobuf_t buf;
 489   byte new_ctb;
 490   byte is_partial;      /* partial length encoded */
 491   /* The data's formatting.  This is either 'b', 't', 'u', 'l' or '1'
 492      (however, the last two are deprecated).  */
 493   int mode;
 494   u32 timestamp;
 495   /* The name of the file.  This can be at most 255 characters long,
 496      since namelen is just a byte in the serialized format.  */
 497   int  namelen;
 498   char name[1];
 499 } PKT_plaintext;
 500
 501 typedef struct {
 502     int  control;
 503     size_t datalen;
 504     char data[1];
 505 } PKT_gpg_control;
 506
 507 /* combine all packets into a union */
 508 struct packet_struct {
 509     pkttype_t pkttype;
 510     union {
 511         void *generic;
 512         PKT_symkey_enc  *symkey_enc;    /* PKT_SYMKEY_ENC */
 513         PKT_pubkey_enc  *pubkey_enc;    /* PKT_PUBKEY_ENC */
 514         PKT_onepass_sig *onepass_sig;   /* PKT_ONEPASS_SIG */
 515         PKT_signature   *signature;     /* PKT_SIGNATURE */
 516         PKT_public_key  *public_key;    /* PKT_PUBLIC_[SUB]KEY */
 517         PKT_public_key  *secret_key;    /* PKT_SECRET_[SUB]KEY */
 518         PKT_comment     *comment;       /* PKT_COMMENT */
 519         PKT_user_id     *user_id;       /* PKT_USER_ID */
 520         PKT_compressed  *compressed;    /* PKT_COMPRESSED */
 521         PKT_encrypted   *encrypted;     /* PKT_ENCRYPTED[_MDC] */
 522         PKT_mdc         *mdc;           /* PKT_MDC */
 523         PKT_ring_trust  *ring_trust;    /* PKT_RING_TRUST */
 524         PKT_plaintext   *plaintext;     /* PKT_PLAINTEXT */
 525         PKT_gpg_control *gpg_control;   /* PKT_GPG_CONTROL */
 526     } pkt;
 527 };
 528
 529 #define init_packet(a) do { (a)->pkttype = 0;           \
 530                             (a)->pkt.generic = NULL;    \
 531                        } while(0)
 532
 533
 534 /* A notation.  See RFC 4880, Section 5.2.3.16.  */
 535 struct notation
 536 {
 537   /* The notation's name.  */
 538   char *name;
 539   /* If the notation is human readable, then the value is stored here
 540      as a NUL-terminated string.  If it is not human readable a human
 541      readable approximation of the binary value _may_ be stored
 542      here.  */
 543   char *value;
 544   /* Sometimes we want to %-expand the value.  In these cases, we save
 545      that transformed value here.  */
 546   char *altvalue;
 547   /* If the notation is not human readable, then the value is stored
 548      here.  */
 549   unsigned char *bdat;
 550   /* The amount of data stored in BDAT.
 551
 552      Note: if this is 0 and BDAT is NULL, this does not necessarily
 553      mean that the value is human readable.  It could be that we have
 554      a 0-length value.  To determine whether the notation is human
 555      readable, always check if VALUE is not NULL.  This works, because
 556      if a human-readable value has a length of 0, we will still
 557      allocate space for the NUL byte.  */
 558   size_t blen;
 559   struct
 560   {
 561     /* The notation is critical.  */
 562     unsigned int critical:1;
 563     /* The notation is human readable.  */
 564     unsigned int human:1;
 565     /* The notation should be deleted.  */
 566     unsigned int ignore:1;
 567   } flags;
 568
 569   /* A field to facilitate creating a list of notations.  */
 570   struct notation *next;
 571 };
 572 typedef struct notation *notation_t;
 573
 574 /*-- mainproc.c --*/
 575 void reset_literals_seen(void);
 576 int proc_packets (ctrl_t ctrl, void *ctx, iobuf_t a );
 577 int proc_signature_packets (ctrl_t ctrl, void *ctx, iobuf_t a,
 578                             strlist_t signedfiles, const char *sigfile );
 579 int proc_signature_packets_by_fd (ctrl_t ctrl,
 580                                   void *anchor, IOBUF a, int signed_data_fd );
 581 int proc_encryption_packets (ctrl_t ctrl, void *ctx, iobuf_t a);
 582 int list_packets( iobuf_t a );
 583
 584 /*-- parse-packet.c --*/
 585
 586 /* Sets the packet list mode to MODE (i.e., whether we are dumping a
 587    packet or not).  Returns the current mode.  This allows for
 588    temporarily suspending dumping by doing the following:
 589
 590      int saved_mode = set_packet_list_mode (0);
 591      ...
 592      set_packet_list_mode (saved_mode);
 593 */
 594 int set_packet_list_mode( int mode );
 595
 596 #if DEBUG_PARSE_PACKET
 597 /* There are debug functions and should not be used directly.  */
 598 int dbg_search_packet( iobuf_t inp, PACKET *pkt, off_t *retpos, int with_uid,
 599                        const char* file, int lineno  );
 600 int dbg_parse_packet( iobuf_t inp, PACKET *ret_pkt,
 601                       const char* file, int lineno );
 602 int dbg_copy_all_packets( iobuf_t inp, iobuf_t out,
 603                           const char* file, int lineno  );
 604 int dbg_copy_some_packets( iobuf_t inp, iobuf_t out, off_t stopoff,
 605                            const char* file, int lineno  );
 606 int dbg_skip_some_packets( iobuf_t inp, unsigned n,
 607                            const char* file, int lineno );
 608 #define search_packet( a,b,c,d )   \
 609              dbg_search_packet( (a), (b), (c), (d), __FILE__, __LINE__ )
 610 #define parse_packet( a, b )  \
 611              dbg_parse_packet( (a), (b), __FILE__, __LINE__ )
 612 #define copy_all_packets( a,b )  \
 613              dbg_copy_all_packets((a),(b), __FILE__, __LINE__ )
 614 #define copy_some_packets( a,b,c ) \
 615              dbg_copy_some_packets((a),(b),(c), __FILE__, __LINE__ )
 616 #define skip_some_packets( a,b ) \
 617              dbg_skip_some_packets((a),(b), __FILE__, __LINE__ )
 618 #else
 619 /* Return the next valid OpenPGP packet in *PKT.  (This function will
 620    skip any packets whose type is 0.)
 621
 622    Returns 0 on success, -1 if EOF is reached, and an error code
 623    otherwise.  In the case of an error, the packet in *PKT may be
 624    partially constructed.  As such, even if there is an error, it is
 625    necessary to free *PKT to avoid a resource leak.  To detect what
 626    has been allocated, clear *PKT before calling this function.  */
 627 int parse_packet( iobuf_t inp, PACKET *pkt);
 628
 629 /* Return the first OpenPGP packet in *PKT that contains a key (either
 630    a public subkey, a public key, a secret subkey or a secret key) or,
 631    if WITH_UID is set, a user id.
 632
 633    Saves the position in the pipeline of the start of the returned
 634    packet (according to iobuf_tell) in RETPOS, if it is not NULL.
 635
 636    The return semantics are the same as parse_packet.  */
 637 int search_packet( iobuf_t inp, PACKET *pkt, off_t *retpos, int with_uid );
 638
 639 /* Copy all packets (except invalid packets, i.e., those with a type
 640    of 0) from INP to OUT until either an error occurs or EOF is
 641    reached.
 642
 643    Returns -1 when end of file is reached or an error code, if an
 644    error occurred.  (Note: this function never returns 0, because it
 645    effectively keeps going until it gets an EOF.)  */
 646 int copy_all_packets( iobuf_t inp, iobuf_t out );
 647
 648 /* Like copy_all_packets, but stops at the first packet that starts at
 649    or after STOPOFF (as indicated by iobuf_tell).
 650
 651    Example: if STOPOFF is 100, the first packet in INP goes from 0 to
 652    110 and the next packet starts at offset 111, then the packet
 653    starting at offset 0 will be completely processed (even though it
 654    extends beyond STOPOFF) and the packet starting at offset 111 will
 655    not be processed at all.  */
 656 int copy_some_packets( iobuf_t inp, iobuf_t out, off_t stopoff );
 657
 658 /* Skips the next N packets from INP.
 659
 660    If parsing a packet returns an error code, then the function stops
 661    immediately and returns the error code.  Note: in the case of an
 662    error, this function does not indicate how many packets were
 663    successfully processed.  */
 664 int skip_some_packets( iobuf_t inp, unsigned n );
 665 #endif
 666
 667 /* Parse a signature packet and store it in *SIG.
 668
 669    The signature packet is read from INP.  The OpenPGP header (the tag
 670    and the packet's length) have already been read; the next byte read
 671    from INP should be the first byte of the packet's contents.  The
 672    packet's type (as extract from the tag) must be passed as PKTTYPE
 673    and the packet's length must be passed as PKTLEN.  This is used as
 674    the upper bound on the amount of data read from INP.  If the packet
 675    is shorter than PKTLEN, the data at the end will be silently
 676    skipped.  If an error occurs, an error code will be returned.  -1
 677    means the EOF was encountered.  0 means parsing was successful.  */
 678 int parse_signature( iobuf_t inp, int pkttype, unsigned long pktlen,
 679                      PKT_signature *sig );
 680
 681 /* Given a subpacket area (typically either PKT_signature.hashed or
 682    PKT_signature.unhashed), either:
 683
 684      - test whether there are any subpackets with the critical bit set
 685        that we don't understand,
 686
 687      - list the subpackets, or,
 688
 689      - find a subpacket with a specific type.
 690
 691    REQTYPE indicates the type of operation.
 692
 693    If REQTYPE is SIGSUBPKT_TEST_CRITICAL, then this function checks
 694    whether there are any subpackets that have the critical bit and
 695    which GnuPG cannot handle.  If GnuPG understands all subpackets
 696    whose critical bit is set, then this function returns simply
 697    returns SUBPKTS.  If there is a subpacket whose critical bit is set
 698    and which GnuPG does not understand, then this function returns
 699    NULL and, if START is not NULL, sets *START to the 1-based index of
 700    the subpacket that violates the constraint.
 701
 702    If REQTYPE is SIGSUBPKT_LIST_HASHED or SIGSUBPKT_LIST_UNHASHED, the
 703    packets are dumped.  Note: if REQTYPE is SIGSUBPKT_LIST_HASHED,
 704    this function does not check whether the hash is correct; this is
 705    merely an indication of the section that the subpackets came from.
 706
 707    If REQTYPE is anything else, then this function interprets the
 708    values as a subpacket type and looks for the first subpacket with
 709    that type.  If such a packet is found, *CRITICAL (if not NULL) is
 710    set if the critical bit was set, *RET_N is set to the offset of the
 711    subpacket's content within the SUBPKTS buffer, *START is set to the
 712    1-based index of the subpacket within the buffer, and returns
 713    &SUBPKTS[*RET_N].
 714
 715    *START is the number of initial subpackets to not consider.  Thus,
 716    if *START is 2, then the first 2 subpackets are ignored.  */
 717 const byte *enum_sig_subpkt ( const subpktarea_t *subpkts,
 718                               sigsubpkttype_t reqtype,
 719                               size_t *ret_n, int *start, int *critical );
 720
 721 /* Shorthand for:
 722
 723      enum_sig_subpkt (buffer, reqtype, ret_n, NULL, NULL); */
 724 const byte *parse_sig_subpkt ( const subpktarea_t *buffer,
 725                                sigsubpkttype_t reqtype,
 726                                size_t *ret_n );
 727
 728 /* This calls parse_sig_subpkt first on the hashed signature area in
 729    SIG and then, if that returns NULL, calls parse_sig_subpkt on the
 730    unhashed subpacket area in SIG.  */
 731 const byte *parse_sig_subpkt2 ( PKT_signature *sig,
 732                                 sigsubpkttype_t reqtype);
 733
 734 /* Returns whether the N byte large buffer BUFFER is sufficient to
 735    hold a subpacket of type TYPE.  Note: the buffer refers to the
 736    contents of the subpacket (not the header) and it must already be
 737    initialized: for some subpackets, it checks some internal
 738    constraints.
 739
 740    Returns 0 if the size is acceptable.  Returns -2 if the buffer is
 741    definitely too short.  To check for an error, check whether the
 742    return value is less than 0.  */
 743 int parse_one_sig_subpkt( const byte *buffer, size_t n, int type );
 744
 745 /* Looks for revocation key subpackets (see RFC 4880 5.2.3.15) in the
 746    hashed area of the signature packet.  Any that are found are added
 747    to SIG->REVKEY and SIG->NUMREVKEYS is updated appropriately.  */
 748 void parse_revkeys(PKT_signature *sig);
 749
 750 /* Extract the attributes from the buffer at UID->ATTRIB_DATA and
 751    update UID->ATTRIBS and UID->NUMATTRIBS accordingly.  */
 752 int parse_attribute_subpkts(PKT_user_id *uid);
 753
 754 /* Set the UID->NAME field according to the attributes.  MAX_NAMELEN
 755    must be at least 71.  */
 756 void make_attribute_uidname(PKT_user_id *uid, size_t max_namelen);
 757
 758 /* Allocate and initialize a new GPG control packet.  DATA is the data
 759    to save in the packet.  */
 760 PACKET *create_gpg_control ( ctrlpkttype_t type,
 761                              const byte *data,
 762                              size_t datalen );
 763
 764 /*-- build-packet.c --*/
 765 int build_packet( iobuf_t inp, PACKET *pkt );
 766 gpg_error_t gpg_mpi_write (iobuf_t out, gcry_mpi_t a);
 767 gpg_error_t gpg_mpi_write_nohdr (iobuf_t out, gcry_mpi_t a);
 768 u32 calc_packet_length( PACKET *pkt );
 769 void build_sig_subpkt( PKT_signature *sig, sigsubpkttype_t type,
 770                         const byte *buffer, size_t buflen );
 771 void build_sig_subpkt_from_sig (PKT_signature *sig, PKT_public_key *pksk);
 772 int  delete_sig_subpkt(subpktarea_t *buffer, sigsubpkttype_t type );
 773 void build_attribute_subpkt(PKT_user_id *uid,byte type,
 774                             const void *buf,u32 buflen,
 775                             const void *header,u32 headerlen);
 776 struct notation *string_to_notation(const char *string,int is_utf8);
 777 struct notation *blob_to_notation(const char *name,
 778                                   const char *data, size_t len);
 779 struct notation *sig_to_notation(PKT_signature *sig);
 780 void free_notation(struct notation *notation);
 781
 782 /*-- free-packet.c --*/
 783 void free_symkey_enc( PKT_symkey_enc *enc );
 784 void free_pubkey_enc( PKT_pubkey_enc *enc );
 785 void free_seckey_enc( PKT_signature *enc );
 786 void release_public_key_parts( PKT_public_key *pk );
 787 void free_public_key( PKT_public_key *key );
 788 void free_attributes(PKT_user_id *uid);
 789 void free_user_id( PKT_user_id *uid );
 790 void free_comment( PKT_comment *rem );
 791 void free_packet( PACKET *pkt );
 792 prefitem_t *copy_prefs (const prefitem_t *prefs);
 793 PKT_public_key *copy_public_key( PKT_public_key *d, PKT_public_key *s );
 794 PKT_signature *copy_signature( PKT_signature *d, PKT_signature *s );
 795 PKT_user_id *scopy_user_id (PKT_user_id *sd );
 796 int cmp_public_keys( PKT_public_key *a, PKT_public_key *b );
 797 int cmp_signatures( PKT_signature *a, PKT_signature *b );
 798 int cmp_user_ids( PKT_user_id *a, PKT_user_id *b );
 799
 800
 801 /*-- sig-check.c --*/
 802 /* Check a signature.  This is shorthand for check_signature2 with
 803    the unnamed arguments passed as NULL.  */
 804 int check_signature (PKT_signature *sig, gcry_md_hd_t digest);
 805
 806 /* Check a signature.  Looks up the public key from the key db.  (If
 807  * R_PK is not NULL, it is stored at RET_PK.)  DIGEST contains a
 808  * valid hash context that already includes the signed data.  This
 809  * function adds the relevant meta-data to the hash before finalizing
 810  * it and verifying the signature.  */
 811 gpg_error_t check_signature2 (PKT_signature *sig, gcry_md_hd_t digest,
 812                               u32 *r_expiredate, int *r_expired, int *r_revoked,
 813                               PKT_public_key **r_pk);
 814
 815
 816 /*-- pubkey-enc.c --*/
 817 gpg_error_t get_session_key (ctrl_t ctrl, PKT_pubkey_enc *k, DEK *dek);
 818 gpg_error_t get_override_session_key (DEK *dek, const char *string);
 819
 820 /*-- compress.c --*/
 821 int handle_compressed (ctrl_t ctrl, void *ctx, PKT_compressed *cd,
 822                        int (*callback)(iobuf_t, void *), void *passthru );
 823
 824 /*-- encr-data.c --*/
 825 int decrypt_data (ctrl_t ctrl, void *ctx, PKT_encrypted *ed, DEK *dek );
 826
 827 /*-- plaintext.c --*/
 828 gpg_error_t get_output_file (const byte *embedded_name, int embedded_namelen,
 829                              iobuf_t data, char **fnamep, estream_t *fpp);
 830 int handle_plaintext( PKT_plaintext *pt, md_filter_context_t *mfx,
 831                                         int nooutput, int clearsig );
 832 int ask_for_detached_datafile( gcry_md_hd_t md, gcry_md_hd_t md2,
 833                                const char *inname, int textmode );
 834
 835 /*-- sign.c --*/
 836 int make_keysig_packet( PKT_signature **ret_sig, PKT_public_key *pk,
 837                         PKT_user_id *uid, PKT_public_key *subpk,
 838                         PKT_public_key *pksk, int sigclass, int digest_algo,
 839                         u32 timestamp, u32 duration,
 840                         int (*mksubpkt)(PKT_signature *, void *),
 841                         void *opaque,
 842                         const char *cache_nonce);
 843 gpg_error_t update_keysig_packet (PKT_signature **ret_sig,
 844                       PKT_signature *orig_sig,
 845                       PKT_public_key *pk,
 846                       PKT_user_id *uid,
 847                       PKT_public_key *subpk,
 848                       PKT_public_key *pksk,
 849                       int (*mksubpkt)(PKT_signature *, void *),
 850                       void *opaque   );
 851
 852 /*-- keygen.c --*/
 853 PKT_user_id *generate_user_id (kbnode_t keyblock, const char *uidstr);
 854
 855 #endif /*G10_PACKET_H*/