diff options
Diffstat (limited to '')
| -rw-r--r-- | g10/packet.h | 135 |
1 files changed, 133 insertions, 2 deletions
diff --git a/g10/packet.h b/g10/packet.h index 0563bb14c..8bd5fc458 100644 --- a/g10/packet.h +++ b/g10/packet.h @@ -1,6 +1,7 @@ /* packet.h - OpenPGP packet definitions * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, * 2007 Free Software Foundation, Inc. + * Copyright (C) 2015 g10 Code GmbH * * This file is part of GnuPG. * @@ -373,7 +374,7 @@ struct packet_struct { PKT_pubkey_enc *pubkey_enc; /* PKT_PUBKEY_ENC */ PKT_onepass_sig *onepass_sig; /* PKT_ONEPASS_SIG */ PKT_signature *signature; /* PKT_SIGNATURE */ - PKT_public_key *public_key; /* PKT_PUBLIC_[SUB)KEY */ + PKT_public_key *public_key; /* PKT_PUBLIC_[SUB]KEY */ PKT_public_key *secret_key; /* PKT_SECRET_[SUB]KEY */ PKT_comment *comment; /* PKT_COMMENT */ PKT_user_id *user_id; /* PKT_USER_ID */ @@ -417,9 +418,19 @@ int proc_encryption_packets (ctrl_t ctrl, void *ctx, iobuf_t a); int list_packets( iobuf_t a ); /*-- parse-packet.c --*/ + +/* Sets the packet list mode to MODE (i.e., whether we are dumping a + packet or not). Returns the current mode. This allows for + temporarily suspending dumping by doing the following: + + int saved_mode = set_packet_list_mode (0); + ... + set_packet_list_mode (saved_mode); +*/ int set_packet_list_mode( int mode ); #if DEBUG_PARSE_PACKET +/* There are debug functions and should not be used directly. */ int dbg_search_packet( iobuf_t inp, PACKET *pkt, off_t *retpos, int with_uid, const char* file, int lineno ); int dbg_parse_packet( iobuf_t inp, PACKET *ret_pkt, @@ -441,27 +452,147 @@ int dbg_skip_some_packets( iobuf_t inp, unsigned n, #define skip_some_packets( a,b ) \ dbg_skip_some_packets((a),(b), __FILE__, __LINE__ ) #else +/* Return the next valid OpenPGP packet in *PKT. (This function will + skip any packets whose type is 0.) + + Returns 0 on success, -1 if EOF is reached, and an error code + otherwise. In the case of an error, the packet in *PKT may be + partially constructed. As such, even if there is an error, it is + necessary to free *PKT to avoid a resource leak. To detect what + has been allocated, clear *PKT before calling this function. */ +int parse_packet( iobuf_t inp, PACKET *pkt); + +/* Return the first OpenPGP packet in *PKT that contains a key (either + a public subkey, a public key, a secret subkey or a secret key) or, + if WITH_UID is set, a user id. + + Saves the position in the pipeline of the start of the returned + packet (according to iobuf_tell) in RETPOS, if it is not NULL. + + The return semantics are the same as parse_packet. */ int search_packet( iobuf_t inp, PACKET *pkt, off_t *retpos, int with_uid ); -int parse_packet( iobuf_t inp, PACKET *ret_pkt); + +/* Copy all packets (except invalid packets, i.e., those with a type + of 0) from INP to OUT until either an error occurs or EOF is + reached. + + Returns -1 when end of file is reached or an error code, if an + error occured. (Note: this function never returns 0, because it + effectively keeps going until it gets an EOF.) */ int copy_all_packets( iobuf_t inp, iobuf_t out ); + +/* Like copy_all_packets, but stops at the first packet that starts at + or after STOPOFF (as indicated by iobuf_tell). + + Example: if STOPOFF is 100, the first packet in INP goes from 0 to + 110 and the next packet starts at offset 111, then the packet + starting at offset 0 will be completely processed (even though it + extends beyond STOPOFF) and the packet starting at offset 111 will + not be processed at all. */ int copy_some_packets( iobuf_t inp, iobuf_t out, off_t stopoff ); + +/* Skips the next N packets from INP. + + If parsing a packet returns an error code, then the function stops + immediately and returns the error code. Note: in the case of an + error, this function does not indicate how many packets were + successfully processed. */ int skip_some_packets( iobuf_t inp, unsigned n ); #endif +/* Parse a signature packet and store it in *SIG. + + The signature packet is read from INP. The OpenPGP header (the tag + and the packet's length) have already been read; the next byte read + from INP should be the first byte of the packet's contents. The + packet's type (as extract from the tag) must be passed as PKTTYPE + and the packet's length must be passed as PKTLEN. This is used as + the upper bound on the amount of data read from INP. If the packet + is shorter than PKTLEN, the data at the end will be silently + skipped. If an error occurs, an error code will be returned. -1 + means the EOF was encountered. 0 means parsing was successful. */ int parse_signature( iobuf_t inp, int pkttype, unsigned long pktlen, PKT_signature *sig ); + +/* Given a subpacket area (typically either PKT_signature.hashed or + PKT_signature.unhashed), either: + + - test whether there are any subpackets with the critical bit set + that we don't understand, + + - list the subpackets, or, + + - find a subpacket with a specific type. + + REQTYPE indicates the type of operation. + + If REQTYPE is SIGSUBPKT_TEST_CRITICAL, then this function checks + whether there are any subpackets that have the critical bit and + which GnuPG cannot handle. If GnuPG understands all subpackets + whose critical bit is set, then this function returns simply + returns SUBPKTS. If there is a subpacket whose critical bit is set + and which GnuPG does not understand, then this function returns + NULL and, if START is not NULL, sets *START to the 1-based index of + the subpacket that violates the constraint. + + If REQTYPE is SIGSUBPKT_LIST_HASHED or SIGSUBPKT_LIST_UNHASHED, the + packets are dumped. Note: if REQTYPE is SIGSUBPKT_LIST_HASHED, + this function does not check whether the hash is correct; this is + merely an indication of the section that the subpackets came from. + + If REQTYPE is anything else, then this function interprets the + values as a subpacket type and looks for the first subpacket with + that type. If such a packet is found, *CRITICAL (if not NULL) is + set if the critical bit was set, *RET_N is set to the offset of the + subpacket's content within the SUBPKTS buffer, *START is set to the + 1-based index of the subpacket within the buffer, and returns + &SUBPKTS[*RET_N]. + + *START is the number of initial subpackets to not consider. Thus, + if *START is 2, then the first 2 subpackets are ignored. */ const byte *enum_sig_subpkt ( const subpktarea_t *subpkts, sigsubpkttype_t reqtype, size_t *ret_n, int *start, int *critical ); + +/* Shorthand for: + + enum_sig_subpkt (buffer, reqtype, ret_n, NULL, NULL); */ const byte *parse_sig_subpkt ( const subpktarea_t *buffer, sigsubpkttype_t reqtype, size_t *ret_n ); + +/* This calls parse_sig_subpkt first on the hashed signature area in + SIG and then, if that returns NULL, calls parse_sig_subpkt on the + unhashed subpacket area in SIG. */ const byte *parse_sig_subpkt2 ( PKT_signature *sig, sigsubpkttype_t reqtype); + +/* Returns whether the N byte large buffer BUFFER is sufficient to + hold a subpacket of type TYPE. Note: the buffer refers to the + contents of the subpacket (not the header) and it must already be + initialized: for some subpackets, it checks some internal + constraints. + + Returns 0 if the size is acceptable. Returns -2 if the buffer is + definately too short. To check for an error, check whether the + return value is less than 0. */ int parse_one_sig_subpkt( const byte *buffer, size_t n, int type ); + +/* Looks for revocation key subpackets (see RFC 4880 5.2.3.15) in the + hashed area of the signature packet. Any that are found are added + to SIG->REVKEY and SIG->NUMREVKEYS is updated appropriately. */ void parse_revkeys(PKT_signature *sig); + +/* Extract the attributes from the buffer at UID->ATTRIB_DATA and + update UID->ATTRIBS and UID->NUMATTRIBS accordingly. */ int parse_attribute_subpkts(PKT_user_id *uid); + +/* Set the UID->NAME field according to the attributes. MAX_NAMELEN + must be at least 71. */ void make_attribute_uidname(PKT_user_id *uid, size_t max_namelen); + +/* Allocate and initialize a new GPG control packet. DATA is the data + to save in the packet. */ PACKET *create_gpg_control ( ctrlpkttype_t type, const byte *data, size_t datalen ); |