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