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

/*
 *  PDKIM - a RFC4871 (DKIM) implementation
 *
 *  Copyright (C) 2009 - 2012  Tom Kistner <tom@duncanthrax.net>
 *
 *  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.
 */

/* -------------------------------------------------------------------------- */
/* 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_OOM              -100
#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

/* -------------------------------------------------------------------------- */
/* 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_FAIL_BODY                  1
#define PDKIM_VERIFY_FAIL_MESSAGE               2
#define PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE 3
#define PDKIM_VERIFY_INVALID_BUFFER_SIZE        4
#define PDKIM_VERIFY_INVALID_PUBKEY_PARSING     5

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

#define PDKIM_ALGO_RSA_SHA256     0
#define PDKIM_ALGO_RSA_SHA1       1

#define PDKIM_CANON_SIMPLE        0
#define PDKIM_CANON_RELAXED       1

#define PDKIM_HASH_SHA256         0
#define PDKIM_HASH_SHA1           1

#define PDKIM_KEYTYPE_RSA         0

/* -------------------------------------------------------------------------- */
/* 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 {
  char *version;                  /* v=  */
  char *granularity;              /* g=  */

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

  char *key;                      /* p=  */
  int   key_len;

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

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

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

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

  /* (a=) The signature algorithm. Either PDKIM_ALGO_RSA_SHA256
     or PDKIM_ALGO_RSA_SHA1 */
  int algo;

  /* (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 */
  char *selector;

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

  /* (i=) The identity as given in the signature */
  char *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 */
  char *headernames;

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

  /* (b=) Raw signature data, along with its length in bytes */
  char *sigdata;
  int   sigdata_len;

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

  /* Folded DKIM-Signature: header. Singing 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(). */
  char *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;

  /* Pointer to the next pdkim_signature signature. NULL if signing or if
     this is the last signature. */
  void *next;

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

  /* Per-signature helper variables ----------------------------------- */
#ifdef SHA_OPENSSL
  SHA_CTX      sha1_body;  /* SHA1 block                                */
  SHA256_CTX   sha2_body;  /* SHA256 block                              */
#elif defined(SHA_GNUTLS)
  gnutls_hash_hd_t sha_body; /* Either SHA1 or SHA256 block             */
#elif defined(SHA_POLARSSL)
  sha1_context *sha1_body; /* SHA1 block                                */
  sha2_context *sha2_body; /* SHA256 block                              */
#endif
  unsigned long signed_body_bytes; /* How many body bytes we hashed     */
  pdkim_stringlist *headers; /* Raw headers included in the sig         */
  /* Signing specific ------------------------------------------------- */
  char *rsa_privkey;     /* Private RSA key                             */
  char *sign_headers;    /* To-be-signed header names                   */
  char *rawsig_no_b_val; /* Original signature header w/o b= tag value. */
} pdkim_signature;


/* -------------------------------------------------------------------------- */
/* Context to keep state between all operations. */
#define PDKIM_MODE_SIGN     0
#define PDKIM_MODE_VERIFY   1
typedef struct pdkim_ctx {

  /* PDKIM_MODE_VERIFY or PDKIM_MODE_SIGN */
  int mode;

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

  /* Callback for dns/txt query method (verification only) */
  int(*dns_txt_callback)(char *, char *);

  /* Coder's little helpers */
  pdkim_str *cur_header;
  char      *linebuf;
  int        linebuf_offset;
  BOOL       seen_lf;
  BOOL       seen_eod;
  BOOL       past_headers;
  int        num_buffered_crlf;
  int        num_headers;
  pdkim_stringlist *headers; /* Raw headers for verification         */
} pdkim_ctx;


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

#ifdef __cplusplus
extern "C" {
#endif

DLLEXPORT
pdkim_ctx *pdkim_init_sign    (char *, char *, char *, int);

DLLEXPORT
pdkim_ctx *pdkim_init_verify  (int(*)(char *, char *));

DLLEXPORT
int        pdkim_set_optional (pdkim_ctx *, char *, char *,int, int,
                               long,
                               unsigned long,
                               unsigned long);

DLLEXPORT
int        pdkim_feed         (pdkim_ctx *, char *, int);
DLLEXPORT
int        pdkim_feed_finish  (pdkim_ctx *, pdkim_signature **);

DLLEXPORT
void       pdkim_free_ctx     (pdkim_ctx *);

#ifdef __cplusplus
}
#endif
Commit	Line	Data
	1	/*
	2	* PDKIM - a RFC4871 (DKIM) implementation
	3	*
	4	* Copyright (C) 2009 - 2012 Tom Kistner <tom@duncanthrax.net>
	5	*
	6	* http://duncanthrax.net/pdkim/
	7	*
	8	* This program 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 2 of the License, or
	11	* (at your option) any later version.
	12	*
	13	* This program 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 along
	19	* with this program; if not, write to the Free Software Foundation, Inc.,
	20	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
	21	*/
	22
	23	/* -------------------------------------------------------------------------- */
	24	/* Length of the preallocated buffer for the "answer" from the dns/txt
	25	callback function. This should match the maximum RDLENGTH from DNS. */
	26	#define PDKIM_DNS_TXT_MAX_RECLEN (1 << 16)
	27
	28	/* -------------------------------------------------------------------------- */
	29	/* Function success / error codes */
	30	#define PDKIM_OK 0
	31	#define PDKIM_FAIL -1
	32	#define PDKIM_ERR_OOM -100
	33	#define PDKIM_ERR_RSA_PRIVKEY -101
	34	#define PDKIM_ERR_RSA_SIGNING -102
	35	#define PDKIM_ERR_LONG_LINE -103
	36	#define PDKIM_ERR_BUFFER_TOO_SMALL -104
	37
	38	/* -------------------------------------------------------------------------- */
	39	/* Main/Extended verification status */
	40	#define PDKIM_VERIFY_NONE 0
	41	#define PDKIM_VERIFY_INVALID 1
	42	#define PDKIM_VERIFY_FAIL 2
	43	#define PDKIM_VERIFY_PASS 3
	44
	45	#define PDKIM_VERIFY_FAIL_BODY 1
	46	#define PDKIM_VERIFY_FAIL_MESSAGE 2
	47	#define PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE 3
	48	#define PDKIM_VERIFY_INVALID_BUFFER_SIZE 4
	49	#define PDKIM_VERIFY_INVALID_PUBKEY_PARSING 5
	50
	51	/* -------------------------------------------------------------------------- */
	52	/* Some parameter values */
	53	#define PDKIM_QUERYMETHOD_DNS_TXT 0
	54
	55	#define PDKIM_ALGO_RSA_SHA256 0
	56	#define PDKIM_ALGO_RSA_SHA1 1
	57
	58	#define PDKIM_CANON_SIMPLE 0
	59	#define PDKIM_CANON_RELAXED 1
	60
	61	#define PDKIM_HASH_SHA256 0
	62	#define PDKIM_HASH_SHA1 1
	63
	64	#define PDKIM_KEYTYPE_RSA 0
	65
	66	/* -------------------------------------------------------------------------- */
	67	/* Some required forward declarations, please ignore */
	68	typedef struct pdkim_stringlist pdkim_stringlist;
	69	typedef struct pdkim_str pdkim_str;
	70	typedef struct sha1_context sha1_context;
	71	typedef struct sha2_context sha2_context;
	72	#define HAVE_SHA1_CONTEXT
	73	#define HAVE_SHA2_CONTEXT
	74
	75	/* -------------------------------------------------------------------------- */
	76	/* Some concessions towards Redmond */
	77	#ifdef WINDOWS
	78	#define snprintf _snprintf
	79	#define strcasecmp _stricmp
	80	#define strncasecmp _strnicmp
	81	#define DLLEXPORT __declspec(dllexport)
	82	#else
	83	#define DLLEXPORT
	84	#endif
	85
	86
	87	/* -------------------------------------------------------------------------- */
	88	/* Public key as (usually) fetched from DNS */
	89	typedef struct pdkim_pubkey {
	90	char version; / v= */
	91	char granularity; / g= */
	92
	93	char hashes; / h= */
	94	char keytype; / k= */
	95	char srvtype; / s= */
	96	char notes; / n= */
	97
	98	char key; / p= */
	99	int key_len;
	100
	101	int testing; /* t=y */
	102	int no_subdomaining; /* t=s */
	103	} pdkim_pubkey;
	104
	105	/* -------------------------------------------------------------------------- */
	106	/* Signature as it appears in a DKIM-Signature header */
	107	typedef struct pdkim_signature {
	108
	109	/* Bits stored in a DKIM signature header --------------------------- */
	110
	111	/* (v=) The version, as an integer. Currently, always "1" */
	112	int version;
	113
	114	/* (a=) The signature algorithm. Either PDKIM_ALGO_RSA_SHA256
	115	or PDKIM_ALGO_RSA_SHA1 */
	116	int algo;
	117
	118	/* (c=x/) Header canonicalization method. Either PDKIM_CANON_SIMPLE
	119	or PDKIM_CANON_RELAXED */
	120	int canon_headers;
	121
	122	/* (c=/x) Body canonicalization method. Either PDKIM_CANON_SIMPLE
	123	or PDKIM_CANON_RELAXED */
	124	int canon_body;
	125
	126	/* (q=) Query Method. Currently, only PDKIM_QUERYMETHOD_DNS_TXT
	127	is specified */
	128	int querymethod;
	129
	130	/* (s=) The selector string as given in the signature */
	131	char *selector;
	132
	133	/* (d=) The domain as given in the signature */
	134	char *domain;
	135
	136	/* (i=) The identity as given in the signature */
	137	char *identity;
	138
	139	/* (t=) Timestamp of signature creation */
	140	unsigned long created;
	141
	142	/* (x=) Timestamp of expiry of signature */
	143	unsigned long expires;
	144
	145	/* (l=) Amount of hashed body bytes (after canonicalization). Default
	146	is -1. Note: a value of 0 means that the body is unsigned! */
	147	long bodylength;
	148
	149	/* (h=) Colon-separated list of header names that are included in the
	150	signature */
	151	char *headernames;
	152
	153	/* (z=) */
	154	char *copiedheaders;
	155
	156	/* (b=) Raw signature data, along with its length in bytes */
	157	char *sigdata;
	158	int sigdata_len;
	159
	160	/* (bh=) Raw body hash data, along with its length in bytes */
	161	char *bodyhash;
	162	int bodyhash_len;
	163
	164	/* Folded DKIM-Signature: header. Singing only, NULL for verifying.
	165	Ready for insertion into the message. Note: Folded using CRLFTB,
	166	but final line terminator is NOT included. Note2: This buffer is
	167	free()d when you call pdkim_free_ctx(). */
	168	char *signature_header;
	169
	170	/* The main verification status. Verification only. One of:
	171
	172	PDKIM_VERIFY_NONE Verification was not attempted. This status
	173	should not appear.
	174
	175	PDKIM_VERIFY_INVALID There was an error while trying to verify
	176	the signature. A more precise description
	177	is available in verify_ext_status.
	178
	179	PDKIM_VERIFY_FAIL Verification failed because either the body
	180	hash did not match, or the signature verification
	181	failed. This means the message was modified.
	182	Check verify_ext_status for the exact reason.
	183
	184	PDKIM_VERIFY_PASS Verification succeeded.
	185	*/
	186	int verify_status;
	187
	188	/* Extended verification status. Verification only. Depending on the value
	189	of verify_status, it can contain:
	190
	191	For verify_status == PDKIM_VERIFY_INVALID:
	192
	193	PDKIM_VERIFY_INVALID_PUBKEY_UNAVAILABLE
	194	Unable to retrieve a public key container.
	195
	196	PDKIM_VERIFY_INVALID_BUFFER_SIZE
	197	Either the DNS name constructed to retrieve the public key record
	198	does not fit into PDKIM_DNS_TXT_MAX_NAMELEN bytes, or the retrieved
	199	record is longer than PDKIM_DNS_TXT_MAX_RECLEN bytes.
	200
	201	PDKIM_VERIFY_INVALID_PUBKEY_PARSING
	202	(Syntax) error while parsing the retrieved public key record.
	203
	204
	205	For verify_status == PDKIM_VERIFY_FAIL:
	206
	207	PDKIM_VERIFY_FAIL_BODY
	208	The calculated body hash does not match the advertised body hash
	209	from the bh= tag of the signature.
	210
	211	PDKIM_VERIFY_FAIL_MESSAGE
	212	RSA verification of the signature (b= tag) failed.
	213	*/
	214	int verify_ext_status;
	215
	216	/* Pointer to a public key record that was used to verify the signature.
	217	See pdkim_pubkey declaration above for more information.
	218	Caution: is NULL if signing or if no record was retrieved. */
	219	pdkim_pubkey *pubkey;
	220
	221	/* Pointer to the next pdkim_signature signature. NULL if signing or if
	222	this is the last signature. */
	223	void *next;
	224
	225	/* Properties below this point are used internally only ------------- */
	226
	227	/* Per-signature helper variables ----------------------------------- */
	228	#ifdef SHA_OPENSSL
	229	SHA_CTX sha1_body; /* SHA1 block */
	230	SHA256_CTX sha2_body; /* SHA256 block */
	231	#elif defined(SHA_GNUTLS)
	232	gnutls_hash_hd_t sha_body; /* Either SHA1 or SHA256 block */
	233	#elif defined(SHA_POLARSSL)
	234	sha1_context sha1_body; / SHA1 block */
	235	sha2_context sha2_body; / SHA256 block */
	236	#endif
	237	unsigned long signed_body_bytes; /* How many body bytes we hashed */
	238	pdkim_stringlist headers; / Raw headers included in the sig */
	239	/* Signing specific ------------------------------------------------- */
	240	char rsa_privkey; / Private RSA key */
	241	char sign_headers; / To-be-signed header names */
	242	char rawsig_no_b_val; / Original signature header w/o b= tag value. */
	243	} pdkim_signature;
	244
	245
	246	/* -------------------------------------------------------------------------- */
	247	/* Context to keep state between all operations. */
	248	#define PDKIM_MODE_SIGN 0
	249	#define PDKIM_MODE_VERIFY 1
	250	typedef struct pdkim_ctx {
	251
	252	/* PDKIM_MODE_VERIFY or PDKIM_MODE_SIGN */
	253	int mode;
	254
	255	/* One (signing) or several chained (verification) signatures */
	256	pdkim_signature *sig;
	257
	258	/* Callback for dns/txt query method (verification only) */
	259	int(dns_txt_callback)(char , char *);
	260
	261	/* Coder's little helpers */
	262	pdkim_str *cur_header;
	263	char *linebuf;
	264	int linebuf_offset;
	265	BOOL seen_lf;
	266	BOOL seen_eod;
	267	BOOL past_headers;
	268	int num_buffered_crlf;
	269	int num_headers;
	270	pdkim_stringlist headers; / Raw headers for verification */
	271	} pdkim_ctx;
	272
	273
	274	/* -------------------------------------------------------------------------- */
	275	/* API functions. Please see the sample code in sample/test_sign.c and
	276	sample/test_verify.c for documentation.
	277	*/
	278
	279	#ifdef __cplusplus
	280	extern "C" {
	281	#endif
	282
	283	DLLEXPORT
	284	pdkim_ctx pdkim_init_sign (char , char , char , int);
	285
	286	DLLEXPORT
	287	pdkim_ctx pdkim_init_verify (int()(char , char ));
	288
	289	DLLEXPORT
	290	int pdkim_set_optional (pdkim_ctx , char , char *,int, int,
	291	long,
	292	unsigned long,
	293	unsigned long);
	294
	295	DLLEXPORT
	296	int pdkim_feed (pdkim_ctx , char , int);
	297	DLLEXPORT
	298	int pdkim_feed_finish (pdkim_ctx , pdkim_signature *);
	299
	300	DLLEXPORT
	301	void pdkim_free_ctx (pdkim_ctx *);
	302
	303	#ifdef __cplusplus
	304	}
	305	#endif