[exim.git] / src / src / pdkim / pdkim.h

/*
 *  PDKIM - a RFC4871 (DKIM) implementation
 *
 *  Copyright (C) 2009 - 2012  Tom Kistner <tom@duncanthrax.net>
 *  Copyright (c) 2016 - 2020  Jeremy Harris
 *
 *  http://duncanthrax.net/pdkim/
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
#ifndef PDKIM_H
#define PDKIM_H

#include "../blob.h"
#include "../hash.h"

#define PDKIM_DEFAULT_SIGN_HEADERS "From:Sender:Reply-To:Subject:Date:"\
                             "Message-ID:To:Cc:MIME-Version:Content-Type:"\
                             "Content-Transfer-Encoding:Content-ID:"\
                             "Content-Description:Resent-Date:Resent-From:"\
                             "Resent-Sender:Resent-To:Resent-Cc:"\
                             "Resent-Message-ID:In-Reply-To:References:"\
                             "List-Id:List-Help:List-Unsubscribe:"\
                             "List-Subscribe:List-Post:List-Owner:List-Archive"

#define PDKIM_OVERSIGN_HEADERS "+From:+Sender:+Reply-To:+Subject:+Date:"\
                             "+Message-ID:+To:+Cc:+MIME-Version:+Content-Type:"\
                             "+Content-Transfer-Encoding:+Content-ID:"\
                             "+Content-Description:+Resent-Date:+Resent-From:"\
                             "+Resent-Sender:+Resent-To:+Resent-Cc:"\
                             "+Resent-Message-ID:+In-Reply-To:+References:"\
                             "+List-Id:+List-Help:+List-Unsubscribe:"\
                             "+List-Subscribe:+List-Post:+List-Owner:+List-Archive"

/* -------------------------------------------------------------------------- */
/* Length of the preallocated buffer for the "answer" from the dns/txt
   callback function. This should match the maximum RDLENGTH from DNS. */
#define PDKIM_DNS_TXT_MAX_RECLEN    (1 << 16)

/* -------------------------------------------------------------------------- */
/* Function success / error codes */
#define PDKIM_OK                      0
#define PDKIM_FAIL                   -1
#define PDKIM_ERR_RSA_PRIVKEY      -101
#define PDKIM_ERR_RSA_SIGNING      -102
#define PDKIM_ERR_LONG_LINE        -103
#define PDKIM_ERR_BUFFER_TOO_SMALL -104
#define PDKIM_ERR_EXCESS_SIGS	   -105
#define PDKIM_SIGN_PRIVKEY_WRAP    -106
#define PDKIM_SIGN_PRIVKEY_B64D    -107

/* -------------------------------------------------------------------------- */
/* Main/Extended verification status */
#define PDKIM_VERIFY_NONE      0
#define PDKIM_VERIFY_INVALID   1
#define PDKIM_VERIFY_FAIL      2
#define PDKIM_VERIFY_PASS      3
#define PDKIM_VERIFY_POLICY    BIT(31)

#define PDKIM_VERIFY_FAIL_BODY                    1
#define PDKIM_VERIFY_FAIL_MESSAGE                 2
#define PDKIM_VERIFY_FAIL_SIG_ALGO_MISMATCH	  3
#define PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE   4
#define PDKIM_VERIFY_INVALID_BUFFER_SIZE          5
#define PDKIM_VERIFY_INVALID_PUBKEY_DNSRECORD     6
#define PDKIM_VERIFY_INVALID_PUBKEY_IMPORT        7
#define PDKIM_VERIFY_INVALID_PUBKEY_KEYSIZE       8
#define PDKIM_VERIFY_INVALID_SIGNATURE_ERROR      9
#define PDKIM_VERIFY_INVALID_DKIM_VERSION         10

/* -------------------------------------------------------------------------- */
/* Some parameter values */
#define PDKIM_QUERYMETHOD_DNS_TXT 0

#define PDKIM_CANON_SIMPLE        0
#define PDKIM_CANON_RELAXED       1

/* -------------------------------------------------------------------------- */
/* Some required forward declarations, please ignore */
typedef struct pdkim_stringlist pdkim_stringlist;
typedef struct pdkim_str pdkim_str;
typedef struct sha1_context sha1_context;
typedef struct sha2_context sha2_context;
#define HAVE_SHA1_CONTEXT
#define HAVE_SHA2_CONTEXT

/* -------------------------------------------------------------------------- */
/* Some concessions towards Redmond */
#ifdef WINDOWS
#define snprintf _snprintf
#define strcasecmp _stricmp
#define strncasecmp _strnicmp
#define DLLEXPORT __declspec(dllexport)
#else
#define DLLEXPORT
#endif


/* -------------------------------------------------------------------------- */
/* Public key as (usually) fetched from DNS */
typedef struct pdkim_pubkey {
  const uschar * version;         /* v=  */
  const uschar *granularity;      /* g=  */

  const uschar * hashes;          /* h=  */
  const uschar * keytype;         /* k=  */
  const uschar * srvtype;         /* s=  */
  uschar *notes;                  /* n=  */

  blob  key;                      /* p=  */
  int   testing;                  /* t=y */
  int   no_subdomaining;          /* t=s */
} pdkim_pubkey;

/* -------------------------------------------------------------------------- */
/* Body-hash to be calculated */
typedef struct pdkim_bodyhash {
  struct pdkim_bodyhash *	next;
  int				hashtype;
  int 				canon_method;
  long				bodylength;

  hctx         			body_hash_ctx;
  unsigned long			signed_body_bytes;	/* done so far */
  int				num_buffered_blanklines;

  blob				bh;			/* completed hash */
} pdkim_bodyhash;

/* -------------------------------------------------------------------------- */
/* Signature as it appears in a DKIM-Signature header */
typedef struct pdkim_signature {
  struct pdkim_signature * next;

  /* Bits stored in a DKIM signature header --------------------------- */

  /* (v=) The version, as an integer. Currently, always "1" */
  int version;

  /* (a=) The signature algorithm. */
  int		keytype;	/* pdkim_keytypes index */
  unsigned	keybits;	/* size of the key */
  int		hashtype;	/* pdkim_hashes index */

  /* (c=x/) Header canonicalization method. Either PDKIM_CANON_SIMPLE
     or PDKIM_CANON_RELAXED */
  int canon_headers;

  /* (c=/x) Body canonicalization method. Either PDKIM_CANON_SIMPLE
     or PDKIM_CANON_RELAXED */
  int canon_body;

  /* (q=) Query Method. Currently, only PDKIM_QUERYMETHOD_DNS_TXT
     is specified */
  int querymethod;

  /* (s=) The selector string as given in the signature */
  uschar *selector;

  /* (d=) The domain as given in the signature */
  uschar *domain;

  /* (i=) The identity as given in the signature */
  uschar *identity;

  /* (t=) Timestamp of signature creation */
  unsigned long created;

  /* (x=) Timestamp of expiry of signature */
  unsigned long expires;

  /* (l=) Amount of hashed body bytes (after canonicalization). Default
     is -1. Note: a value of 0 means that the body is unsigned! */
  long bodylength;

  /* (h=) Colon-separated list of header names that are included in the
     signature */
  uschar *headernames;

  /* (z=) */
  uschar *copiedheaders;

  /* (b=) Raw signature data, along with its length in bytes */
  blob sighash;

  /* (bh=) Raw body hash data, along with its length in bytes */
  blob bodyhash;

  /* Folded DKIM-Signature: header. Signing only, NULL for verifying.
     Ready for insertion into the message. Note: Folded using CRLFTB,
     but final line terminator is NOT included. Note2: This buffer is
     free()d when you call pdkim_free_ctx(). */
  uschar *signature_header;

  /* The main verification status. Verification only. One of:

     PDKIM_VERIFY_NONE      Verification was not attempted. This status
                            should not appear.

     PDKIM_VERIFY_INVALID   There was an error while trying to verify
                            the signature. A more precise description
                            is available in verify_ext_status.

     PDKIM_VERIFY_FAIL      Verification failed because either the body
                            hash did not match, or the signature verification
                            failed. This means the message was modified.
                            Check verify_ext_status for the exact reason.

     PDKIM_VERIFY_PASS      Verification succeeded.
  */
  int verify_status;

  /* Extended verification status. Verification only. Depending on the value
     of verify_status, it can contain:

     For verify_status == PDKIM_VERIFY_INVALID:

        PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE
          Unable to retrieve a public key container.

        PDKIM_VERIFY_INVALID_BUFFER_SIZE
          Either the DNS name constructed to retrieve the public key record
          does not fit into PDKIM_DNS_TXT_MAX_NAMELEN bytes, or the retrieved
          record is longer than PDKIM_DNS_TXT_MAX_RECLEN bytes.

        PDKIM_VERIFY_INVALID_PUBKEY_PARSING
          (Syntax) error while parsing the retrieved public key record.


     For verify_status == PDKIM_VERIFY_FAIL:

        PDKIM_VERIFY_FAIL_BODY
          The calculated body hash does not match the advertised body hash
          from the bh= tag of the signature.

        PDKIM_VERIFY_FAIL_MESSAGE
          RSA verification of the signature (b= tag) failed.
  */
  int verify_ext_status;

  /* Pointer to a public key record that was used to verify the signature.
     See pdkim_pubkey declaration above for more information.
     Caution: is NULL if signing or if no record was retrieved. */
  pdkim_pubkey *pubkey;

  /* Properties below this point are used internally only ------------- */

  /* Per-signature helper variables ----------------------------------- */
  pdkim_bodyhash *calc_body_hash;	/* hash to be / being calculated */

  pdkim_stringlist *headers;		/* Raw headers included in the sig */

  /* Signing specific ------------------------------------------------- */
  uschar * privkey;	     /* Private key                                 */
  uschar * sign_headers;    /* To-be-signed header names                   */
  uschar * rawsig_no_b_val; /* Original signature header w/o b= tag value. */
} pdkim_signature;


/* -------------------------------------------------------------------------- */
/* Context to keep state between all operations. */
typedef struct pdkim_ctx {

#define PDKIM_MODE_SIGN   BIT(0)	/* if unset, mode==verify */
#define PDKIM_DOT_TERM	  BIT(1)	/* dot termination and unstuffing */
#define PDKIM_SEEN_CR	  BIT(2)
#define PDKIM_SEEN_LF	  BIT(3)
#define PDKIM_PAST_HDRS	  BIT(4)
#define PDKIM_SEEN_EOD	  BIT(5)
  unsigned   flags;

  /* One (signing) or several chained (verification) signatures */
  pdkim_signature *sig;

  /* One (signing) or several chained (verification) bodyhashes */
  pdkim_bodyhash *bodyhash;

  /* Callback for dns/txt query method (verification only) */
  uschar * (*dns_txt_callback)(const uschar *);

  /* Coder's little helpers */
  gstring   *cur_header;
  uschar    *linebuf;
  int        linebuf_offset;
  int        num_headers;
  pdkim_stringlist *headers; /* Raw headers for verification         */
} pdkim_ctx;


/******************************************************************************/

typedef struct {
  const uschar * dkim_hashname;
  hashmethod	 exim_hashmethod;
} pdkim_hashtype;
extern const pdkim_hashtype pdkim_hashes[];

/******************************************************************************/


/* -------------------------------------------------------------------------- */
/* API functions. Please see the sample code in sample/test_sign.c and
   sample/test_verify.c for documentation.
*/

#ifdef __cplusplus
extern "C" {
#endif

void	   pdkim_init         (void);

void	   pdkim_init_context (pdkim_ctx *, BOOL, uschar * (*)(const uschar *));

DLLEXPORT
pdkim_signature *pdkim_init_sign    (pdkim_ctx *,
			       uschar *, uschar *, uschar *, uschar *,
			       const uschar **);

DLLEXPORT
pdkim_ctx *pdkim_init_verify  (uschar * (*)(const uschar *), BOOL);

DLLEXPORT
void       pdkim_set_optional (pdkim_signature *, char *, char *,int, int,
                               long,
                               unsigned long,
                               unsigned long);

int		pdkim_hashname_to_hashtype(const uschar *, unsigned);
void		pdkim_cstring_to_canons(const uschar *, unsigned, int *, int *);
pdkim_bodyhash *pdkim_set_bodyhash(pdkim_ctx *, int, int, long);
pdkim_bodyhash *pdkim_set_sig_bodyhash(pdkim_ctx *, pdkim_signature *);

DLLEXPORT
int        pdkim_feed         (pdkim_ctx *, uschar *, int);
DLLEXPORT
int        pdkim_feed_finish  (pdkim_ctx *, pdkim_signature **, const uschar **);

DLLEXPORT
void       pdkim_free_ctx     (pdkim_ctx *);


const uschar *	pdkim_errstr(int);

extern uschar *		pdkim_encode_base64(blob *);
extern void		pdkim_decode_base64(const uschar *, blob *);
extern void		pdkim_hexprint(const uschar *, int);
extern void		pdkim_quoteprint(const uschar *, int);
extern pdkim_pubkey *	pdkim_parse_pubkey_record(const uschar *);
extern uschar *		pdkim_relax_header_n(const uschar *, int, BOOL);
extern uschar *		pdkim_relax_header(const uschar *, BOOL);
extern uschar *		dkim_sig_to_a_tag(const pdkim_signature *);

#ifdef __cplusplus
}
#endif

#endif
Commit	Line	Data
80a47a2c TK	1	/*
	2	* PDKIM - a RFC4871 (DKIM) implementation
	3	*
c4ceed07	4	* Copyright (C) 2009 - 2012 Tom Kistner <tom@duncanthrax.net>
1e1ddfac	5	* Copyright (c) 2016 - 2020 Jeremy Harris
80a47a2c TK	6	*
	7	* http://duncanthrax.net/pdkim/
	8	*
	9	* This program is free software; you can redistribute it and/or modify
	10	* it under the terms of the GNU General Public License as published by
	11	* the Free Software Foundation; either version 2 of the License, or
	12	* (at your option) any later version.
	13	*
	14	* This program is distributed in the hope that it will be useful,
	15	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	16	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	17	* GNU General Public License for more details.
	18	*
	19	* You should have received a copy of the GNU General Public License along
	20	* with this program; if not, write to the Free Software Foundation, Inc.,
	21	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
	22	*/
2592e6c0 JH	23	#ifndef PDKIM_H
	24	#define PDKIM_H
	25
63af6f3a JH	26	#include "../blob.h"
63af6f3a JH	27	#include "../hash.h"
80a47a2c	28
970424a5 JH	29	#define PDKIM_DEFAULT_SIGN_HEADERS "From:Sender:Reply-To:Subject:Date:"\
	30	"Message-ID:To:Cc:MIME-Version:Content-Type:"\
	31	"Content-Transfer-Encoding:Content-ID:"\
	32	"Content-Description:Resent-Date:Resent-From:"\
	33	"Resent-Sender:Resent-To:Resent-Cc:"\
	34	"Resent-Message-ID:In-Reply-To:References:"\
	35	"List-Id:List-Help:List-Unsubscribe:"\
	36	"List-Subscribe:List-Post:List-Owner:List-Archive"
	37
d34c22b8 JH	38	#define PDKIM_OVERSIGN_HEADERS "+From:+Sender:+Reply-To:+Subject:+Date:"\
	39	"+Message-ID:+To:+Cc:+MIME-Version:+Content-Type:"\
	40	"+Content-Transfer-Encoding:+Content-ID:"\
	41	"+Content-Description:+Resent-Date:+Resent-From:"\
	42	"+Resent-Sender:+Resent-To:+Resent-Cc:"\
	43	"+Resent-Message-ID:+In-Reply-To:+References:"\
	44	"+List-Id:+List-Help:+List-Unsubscribe:"\
	45	"+List-Subscribe:+List-Post:+List-Owner:+List-Archive"
	46
80a47a2c TK	47	/* -------------------------------------------------------------------------- */
80a47a2c TK	48	/* Length of the preallocated buffer for the "answer" from the dns/txt
4263f395 PP	49	callback function. This should match the maximum RDLENGTH from DNS. */
4263f395 PP	50	#define PDKIM_DNS_TXT_MAX_RECLEN (1 << 16)
80a47a2c TK	51
	52	/* -------------------------------------------------------------------------- */
	53	/* Function success / error codes */
	54	#define PDKIM_OK 0
	55	#define PDKIM_FAIL -1
80a47a2c TK	56	#define PDKIM_ERR_RSA_PRIVKEY -101
	57	#define PDKIM_ERR_RSA_SIGNING -102
	58	#define PDKIM_ERR_LONG_LINE -103
	59	#define PDKIM_ERR_BUFFER_TOO_SMALL -104
64b67b65 JH	60	#define PDKIM_ERR_EXCESS_SIGS -105
	61	#define PDKIM_SIGN_PRIVKEY_WRAP -106
	62	#define PDKIM_SIGN_PRIVKEY_B64D -107
80a47a2c TK	63
	64	/* -------------------------------------------------------------------------- */
	65	/* Main/Extended verification status */
	66	#define PDKIM_VERIFY_NONE 0
	67	#define PDKIM_VERIFY_INVALID 1
	68	#define PDKIM_VERIFY_FAIL 2
	69	#define PDKIM_VERIFY_PASS 3
dfbcb5ac	70	#define PDKIM_VERIFY_POLICY BIT(31)
80a47a2c	71
07eeb4df	72	#define PDKIM_VERIFY_FAIL_BODY 1
07eeb4df	73	#define PDKIM_VERIFY_FAIL_MESSAGE 2
135e9496 JH	74	#define PDKIM_VERIFY_FAIL_SIG_ALGO_MISMATCH 3
	75	#define PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE 4
	76	#define PDKIM_VERIFY_INVALID_BUFFER_SIZE 5
	77	#define PDKIM_VERIFY_INVALID_PUBKEY_DNSRECORD 6
	78	#define PDKIM_VERIFY_INVALID_PUBKEY_IMPORT 7
be24b950 JH	79	#define PDKIM_VERIFY_INVALID_PUBKEY_KEYSIZE 8
	80	#define PDKIM_VERIFY_INVALID_SIGNATURE_ERROR 9
	81	#define PDKIM_VERIFY_INVALID_DKIM_VERSION 10
80a47a2c TK	82
	83	/* -------------------------------------------------------------------------- */
	84	/* Some parameter values */
	85	#define PDKIM_QUERYMETHOD_DNS_TXT 0
	86
80a47a2c TK	87	#define PDKIM_CANON_SIMPLE 0
	88	#define PDKIM_CANON_RELAXED 1
	89
80a47a2c TK	90	/* -------------------------------------------------------------------------- */
	91	/* Some required forward declarations, please ignore */
	92	typedef struct pdkim_stringlist pdkim_stringlist;
	93	typedef struct pdkim_str pdkim_str;
cb224393 JH	94	typedef struct sha1_context sha1_context;
	95	typedef struct sha2_context sha2_context;
	96	#define HAVE_SHA1_CONTEXT
	97	#define HAVE_SHA2_CONTEXT
80a47a2c TK	98
	99	/* -------------------------------------------------------------------------- */
	100	/* Some concessions towards Redmond */
	101	#ifdef WINDOWS
	102	#define snprintf _snprintf
	103	#define strcasecmp _stricmp
	104	#define strncasecmp _strnicmp
	105	#define DLLEXPORT __declspec(dllexport)
	106	#else
	107	#define DLLEXPORT
	108	#endif
	109
	110
	111	/* -------------------------------------------------------------------------- */
	112	/* Public key as (usually) fetched from DNS */
	113	typedef struct pdkim_pubkey {
35cf75e9 JH	114	const uschar * version; /* v= */
35cf75e9 JH	115	const uschar granularity; / g= */
80a47a2c	116
35cf75e9	117	const uschar * hashes; /* h= */
286b9d5f JH	118	const uschar * keytype; /* k= */
286b9d5f JH	119	const uschar * srvtype; /* s= */
e2e3255a	120	uschar notes; / n= */
80a47a2c	121
2592e6c0	122	blob key; /* p= */
80a47a2c TK	123	int testing; /* t=y */
	124	int no_subdomaining; /* t=s */
	125	} pdkim_pubkey;
	126
cf1cce5e JH	127	/* -------------------------------------------------------------------------- */
	128	/* Body-hash to be calculated */
	129	typedef struct pdkim_bodyhash {
	130	struct pdkim_bodyhash * next;
	131	int hashtype;
	132	int canon_method;
	133	long bodylength;
	134
	135	hctx body_hash_ctx;
	136	unsigned long signed_body_bytes; /* done so far */
	137	int num_buffered_blanklines;
	138
	139	blob bh; /* completed hash */
	140	} pdkim_bodyhash;
	141
80a47a2c TK	142	/* -------------------------------------------------------------------------- */
	143	/* Signature as it appears in a DKIM-Signature header */
	144	typedef struct pdkim_signature {
9e70917d	145	struct pdkim_signature * next;
80a47a2c TK	146
	147	/* Bits stored in a DKIM signature header --------------------------- */
	148
	149	/* (v=) The version, as an integer. Currently, always "1" */
	150	int version;
	151
042e558f	152	/* (a=) The signature algorithm. */
a841a6ec JH	153	int keytype; /* pdkim_keytypes index */
	154	unsigned keybits; /* size of the key */
	155	int hashtype; /* pdkim_hashes index */
80a47a2c TK	156
	157	/* (c=x/) Header canonicalization method. Either PDKIM_CANON_SIMPLE
	158	or PDKIM_CANON_RELAXED */
	159	int canon_headers;
	160
	161	/* (c=/x) Body canonicalization method. Either PDKIM_CANON_SIMPLE
	162	or PDKIM_CANON_RELAXED */
	163	int canon_body;
	164
	165	/* (q=) Query Method. Currently, only PDKIM_QUERYMETHOD_DNS_TXT
	166	is specified */
	167	int querymethod;
	168
	169	/* (s=) The selector string as given in the signature */
e2e3255a	170	uschar *selector;
80a47a2c TK	171
80a47a2c TK	172	/* (d=) The domain as given in the signature */
e2e3255a	173	uschar *domain;
80a47a2c TK	174
80a47a2c TK	175	/* (i=) The identity as given in the signature */
e2e3255a	176	uschar *identity;
80a47a2c TK	177
	178	/* (t=) Timestamp of signature creation */
	179	unsigned long created;
	180
	181	/* (x=) Timestamp of expiry of signature */
	182	unsigned long expires;
	183
	184	/* (l=) Amount of hashed body bytes (after canonicalization). Default
	185	is -1. Note: a value of 0 means that the body is unsigned! */
	186	long bodylength;
	187
	188	/* (h=) Colon-separated list of header names that are included in the
	189	signature */
2592e6c0	190	uschar *headernames;
80a47a2c TK	191
80a47a2c TK	192	/* (z=) */
e2e3255a	193	uschar *copiedheaders;
80a47a2c TK	194
80a47a2c TK	195	/* (b=) Raw signature data, along with its length in bytes */
dcd03763	196	blob sighash;
80a47a2c TK	197
80a47a2c TK	198	/* (bh=) Raw body hash data, along with its length in bytes */
2592e6c0	199	blob bodyhash;
80a47a2c	200
9e70917d	201	/* Folded DKIM-Signature: header. Signing only, NULL for verifying.
80a47a2c TK	202	Ready for insertion into the message. Note: Folded using CRLFTB,
	203	but final line terminator is NOT included. Note2: This buffer is
	204	free()d when you call pdkim_free_ctx(). */
e2e3255a	205	uschar *signature_header;
80a47a2c TK	206
	207	/* The main verification status. Verification only. One of:
	208
	209	PDKIM_VERIFY_NONE Verification was not attempted. This status
	210	should not appear.
	211
	212	PDKIM_VERIFY_INVALID There was an error while trying to verify
	213	the signature. A more precise description
	214	is available in verify_ext_status.
	215
	216	PDKIM_VERIFY_FAIL Verification failed because either the body
	217	hash did not match, or the signature verification
	218	failed. This means the message was modified.
	219	Check verify_ext_status for the exact reason.
	220
	221	PDKIM_VERIFY_PASS Verification succeeded.
	222	*/
	223	int verify_status;
	224
	225	/* Extended verification status. Verification only. Depending on the value
	226	of verify_status, it can contain:
	227
	228	For verify_status == PDKIM_VERIFY_INVALID:
	229
	230	PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE
	231	Unable to retrieve a public key container.
	232
	233	PDKIM_VERIFY_INVALID_BUFFER_SIZE
	234	Either the DNS name constructed to retrieve the public key record
	235	does not fit into PDKIM_DNS_TXT_MAX_NAMELEN bytes, or the retrieved
	236	record is longer than PDKIM_DNS_TXT_MAX_RECLEN bytes.
	237
	238	PDKIM_VERIFY_INVALID_PUBKEY_PARSING
	239	(Syntax) error while parsing the retrieved public key record.
	240
	241
	242	For verify_status == PDKIM_VERIFY_FAIL:
	243
	244	PDKIM_VERIFY_FAIL_BODY
	245	The calculated body hash does not match the advertised body hash
	246	from the bh= tag of the signature.
	247
	248	PDKIM_VERIFY_FAIL_MESSAGE
	249	RSA verification of the signature (b= tag) failed.
	250	*/
	251	int verify_ext_status;
	252
	253	/* Pointer to a public key record that was used to verify the signature.
	254	See pdkim_pubkey declaration above for more information.
	255	Caution: is NULL if signing or if no record was retrieved. */
	256	pdkim_pubkey *pubkey;
	257
80a47a2c TK	258	/* Properties below this point are used internally only ------------- */
	259
	260	/* Per-signature helper variables ----------------------------------- */
cf1cce5e	261	pdkim_bodyhash calc_body_hash; / hash to be / being calculated */
2592e6c0	262
cf1cce5e	263	pdkim_stringlist headers; / Raw headers included in the sig */
9e70917d	264
80a47a2c	265	/* Signing specific ------------------------------------------------- */
d73e45df	266	uschar * privkey; /* Private key */
ca9cb170 JH	267	uschar * sign_headers; /* To-be-signed header names */
ca9cb170 JH	268	uschar * rawsig_no_b_val; /* Original signature header w/o b= tag value. */
80a47a2c TK	269	} pdkim_signature;
	270
	271
	272	/* -------------------------------------------------------------------------- */
	273	/* Context to keep state between all operations. */
80a47a2c TK	274	typedef struct pdkim_ctx {
80a47a2c TK	275
e983e85a JH	276	#define PDKIM_MODE_SIGN BIT(0) /* if unset, mode==verify */
e983e85a JH	277	#define PDKIM_DOT_TERM BIT(1) /* dot termination and unstuffing */
b895f4b2 JH	278	#define PDKIM_SEEN_CR BIT(2)
b895f4b2 JH	279	#define PDKIM_SEEN_LF BIT(3)
e983e85a	280	#define PDKIM_PAST_HDRS BIT(4)
b895f4b2	281	#define PDKIM_SEEN_EOD BIT(5)
e983e85a	282	unsigned flags;
80a47a2c	283
80a47a2c TK	284	/* One (signing) or several chained (verification) signatures */
	285	pdkim_signature *sig;
	286
cf1cce5e JH	287	/* One (signing) or several chained (verification) bodyhashes */
	288	pdkim_bodyhash *bodyhash;
	289
80a47a2c	290	/* Callback for dns/txt query method (verification only) */
fc2ba7b9	291	uschar * (dns_txt_callback)(const uschar );
80a47a2c TK	292
80a47a2c TK	293	/* Coder's little helpers */
acec9514	294	gstring *cur_header;
7845dbb3	295	uschar *linebuf;
80a47a2c	296	int linebuf_offset;
80a47a2c	297	int num_headers;
37f8b554	298	pdkim_stringlist headers; / Raw headers for verification */
80a47a2c TK	299	} pdkim_ctx;
	300
	301
617d3932 JH	302	/******************************************************************************/
	303
	304	typedef struct {
	305	const uschar * dkim_hashname;
	306	hashmethod exim_hashmethod;
	307	} pdkim_hashtype;
	308	extern const pdkim_hashtype pdkim_hashes[];
	309
	310	/******************************************************************************/
	311
	312
80a47a2c TK	313	/* -------------------------------------------------------------------------- */
	314	/* API functions. Please see the sample code in sample/test_sign.c and
	315	sample/test_verify.c for documentation.
	316	*/
	317
	318	#ifdef __cplusplus
	319	extern "C" {
	320	#endif
	321
2592e6c0 JH	322	void pdkim_init (void);
2592e6c0 JH	323
fc2ba7b9	324	void pdkim_init_context (pdkim_ctx , BOOL, uschar ()(const uschar ));
9e70917d	325
80a47a2c	326	DLLEXPORT
9e70917d JH	327	pdkim_signature pdkim_init_sign (pdkim_ctx ,
	328	uschar , uschar , uschar , uschar ,
	329	const uschar **);
80a47a2c TK	330
80a47a2c TK	331	DLLEXPORT
fc2ba7b9	332	pdkim_ctx pdkim_init_verify (uschar ()(const uschar ), BOOL);
80a47a2c TK	333
80a47a2c TK	334	DLLEXPORT
9e70917d	335	void pdkim_set_optional (pdkim_signature , char , char *,int, int,
f444c2c7	336	long,
80a47a2c TK	337	unsigned long,
	338	unsigned long);
	339
617d3932 JH	340	int pdkim_hashname_to_hashtype(const uschar *, unsigned);
	341	void pdkim_cstring_to_canons(const uschar , unsigned, int , int *);
	342	pdkim_bodyhash pdkim_set_bodyhash(pdkim_ctx , int, int, long);
	343	pdkim_bodyhash pdkim_set_sig_bodyhash(pdkim_ctx , pdkim_signature *);
cf1cce5e	344
80a47a2c	345	DLLEXPORT
ef698bf6	346	int pdkim_feed (pdkim_ctx , uschar , int);
80a47a2c	347	DLLEXPORT
b9df1829	348	int pdkim_feed_finish (pdkim_ctx , pdkim_signature , const uschar *);
80a47a2c TK	349
	350	DLLEXPORT
	351	void pdkim_free_ctx (pdkim_ctx *);
	352
f7302073	353
b9df1829	354	const uschar * pdkim_errstr(int);
f7302073	355
617d3932 JH	356	extern uschar * pdkim_encode_base64(blob *);
	357	extern void pdkim_decode_base64(const uschar , blob );
	358	extern void pdkim_hexprint(const uschar *, int);
	359	extern void pdkim_quoteprint(const uschar *, int);
	360	extern pdkim_pubkey * pdkim_parse_pubkey_record(const uschar *);
	361	extern uschar * pdkim_relax_header_n(const uschar *, int, BOOL);
	362	extern uschar * pdkim_relax_header(const uschar *, BOOL);
	363	extern uschar * dkim_sig_to_a_tag(const pdkim_signature *);
d73e45df	364
80a47a2c TK	365	#ifdef __cplusplus
	366	}
	367	#endif
2592e6c0 JH	368
2592e6c0 JH	369	#endif