/* ** Copyright (c) 2005-2007 Sendmail, Inc. and its suppliers. ** All rights reserved. */ #ifndef _DKIM_H_ #define _DKIM_H_ #ifndef lint static char dkim_h_id[] = "@(#)$Id: dkim.h,v 1.157 2007/12/18 01:31:08 msk Exp $"; #endif /* !lint */ /* system includes */ #include #include /* libsm includes */ #include #include #include /* openssl includes */ #include /* ** version -- 0xrrMMmmpp ** ** rr == release number ** MM == major revision number ** mm == minor revision number ** pp == patch number */ #define DKIM_LIB_VERSION 0x02040100 /* the basics */ #ifndef NULL # define NULL 0 #endif /* ! NULL */ #ifndef FALSE # define FALSE 0 #endif /* ! FALSE */ #ifndef TRUE # define TRUE 1 #endif /* ! TRUE */ #ifndef MAXPATHLEN # define MAXPATHLEN 256 #endif /* ! MAXPATHLEN */ #ifndef ULONG_MAX # define ULONG_MAX 0xffffffffL #endif /* ! ULONG_MAX */ #ifndef ULLONG_MAX # define ULLONG_MAX 0xffffffffffffffffLL #endif /* ! ULLONG_MAX */ #ifndef MIN # define MIN(x,y) ((x) < (y) ? (x) : (y)) #endif /* ! MIN */ #ifndef MAX # define MAX(x,y) ((x) > (y) ? (x) : (y)) #endif /* ! MAX */ /* limits, macros, etc. */ #define BUFRSZ 1024 /* base temp buffer size */ #define MAXADDRESS 256 /* biggest user@host we accept */ #define MAXBUFRSZ 65536 /* max temp buffer size */ #define MAXCNAMEDEPTH 3 /* max. CNAME recursion we allow */ #define MAXHEADERS 32768 /* buffer for caching headers */ #define MAXLABELS 16 /* max. labels we allow */ #define MAXPOLICYDEPTH 1 /* policy recursion we allow */ #define MAXTAGNAME 8 /* biggest tag name */ #define DKIM_MAXHEADER 4096 /* buffer for caching one header */ #define DKIM_MAXHOSTNAMELEN 256 /* max. FQDN we support */ /* defaults */ #define DEFERRLEN 64 /* default error string length */ #define DEFTMPDIR "/var/tmp" /* default temporary directory */ /* version */ #define DKIM_VERSION_KEY "DKIM1" /* current version token for keys */ #define DKIM_VERSION_SIG "1" /* current version token for sigs */ #define DKIM_VERSION_SIGOLD "0.5" /* old version token for sigs */ /* headers */ #define DKIM_DATEHEADER "Date" /* Date: header */ #define DKIM_FROMHEADER "From" /* From: header */ #define DKIM_SIGNHEADER "DKIM-Signature" /* DKIM signature header */ #define DKIM_DATEHEADER_LEN (sizeof(DKIM_DATEHEADER) - 1) #define DKIM_FROMHEADER_LEN (sizeof(DKIM_FROMHEADER) - 1) #define DKIM_SIGNHEADER_LEN (sizeof(DKIM_SIGNHEADER) - 1) #define DKIM_HDRMARGIN 75 /* "standard" header margin */ /* special DNS tokens */ #define DKIM_DNSKEYNAME "_domainkey" /* reserved DNS sub-zone */ #define DKIM_DNSPOLICYNAME "_ssp" /* reserved DNS sub-zone */ /* ** DKIM_STAT -- status code type */ typedef int DKIM_STAT; #define DKIM_STAT_OK 0 /* function completed successfully */ #define DKIM_STAT_BADSIG 1 /* signature available but failed */ #define DKIM_STAT_NOSIG 2 /* no signature available */ #define DKIM_STAT_NOKEY 3 /* public key not found */ #define DKIM_STAT_CANTVRFY 4 /* can't get domain key to verify */ #define DKIM_STAT_SYNTAX 5 /* message is not valid syntax */ #define DKIM_STAT_NORESOURCE 6 /* resource unavailable */ #define DKIM_STAT_INTERNAL 7 /* internal error */ #define DKIM_STAT_REVOKED 8 /* key found, but revoked */ #define DKIM_STAT_INVALID 9 /* invalid function parameter */ #define DKIM_STAT_NOTIMPLEMENT 10 /* function not implemented */ #define DKIM_STAT_KEYFAIL 11 /* key retrieval failed */ #define DKIM_STAT_CBREJECT 12 /* callback requested reject */ #define DKIM_STAT_CBINVALID 13 /* callback gave invalid result */ #define DKIM_STAT_CBTRYAGAIN 14 /* callback says try again later */ #define DKIM_STAT_CBERROR 15 /* callback error */ /* ** DKIM_CBSTAT -- callback status code type */ typedef int DKIM_CBSTAT; #define DKIM_CBSTAT_CONTINUE 0 /* continue */ #define DKIM_CBSTAT_REJECT 1 /* reject */ #define DKIM_CBSTAT_TRYAGAIN 2 /* try again later */ #define DKIM_CBSTAT_NOTFOUND 3 /* requested record not found */ #define DKIM_CBSTAT_ERROR 4 /* error requesting record */ /* ** DKIM_SIGERROR -- signature errors */ typedef int DKIM_SIGERROR; #define DKIM_SIGERROR_UNKNOWN (-1) /* unknown error */ #define DKIM_SIGERROR_OK 0 /* no error */ #define DKIM_SIGERROR_VERSION 1 /* unsupported version */ #define DKIM_SIGERROR_DOMAIN 2 /* invalid domain (d=/i=) */ #define DKIM_SIGERROR_EXPIRED 3 /* signature expired */ #define DKIM_SIGERROR_FUTURE 4 /* signature in the future */ #define DKIM_SIGERROR_TIMESTAMPS 5 /* x= < t= */ #define DKIM_SIGERROR_MISSING_C 6 /* c= missing */ #define DKIM_SIGERROR_INVALID_HC 7 /* c= invalid (header) */ #define DKIM_SIGERROR_INVALID_BC 8 /* c= invalid (body) */ #define DKIM_SIGERROR_MISSING_A 9 /* a= missing */ #define DKIM_SIGERROR_INVALID_A 10 /* a= invalid */ #define DKIM_SIGERROR_MISSING_H 11 /* h= missing */ #define DKIM_SIGERROR_INVALID_L 12 /* l= invalid */ #define DKIM_SIGERROR_INVALID_Q 13 /* q= invalid */ #define DKIM_SIGERROR_INVALID_QO 14 /* q= option invalid */ #define DKIM_SIGERROR_MISSING_D 15 /* d= missing */ #define DKIM_SIGERROR_EMPTY_D 16 /* d= empty */ #define DKIM_SIGERROR_MISSING_S 17 /* s= missing */ #define DKIM_SIGERROR_EMPTY_S 18 /* s= empty */ #define DKIM_SIGERROR_MISSING_B 19 /* b= missing */ #define DKIM_SIGERROR_EMPTY_B 20 /* b= empty */ #define DKIM_SIGERROR_CORRUPT_B 21 /* b= corrupt */ #define DKIM_SIGERROR_NOKEY 22 /* no key found in DNS */ #define DKIM_SIGERROR_DNSSYNTAX 23 /* DNS reply corrupt */ #define DKIM_SIGERROR_KEYFAIL 24 /* DNS query failed */ #define DKIM_SIGERROR_MISSING_BH 25 /* bh= missing */ #define DKIM_SIGERROR_EMPTY_BH 26 /* bh= empty */ #define DKIM_SIGERROR_CORRUPT_BH 27 /* bh= corrupt */ #define DKIM_SIGERROR_BADSIG 28 /* signature mismatch */ #define DKIM_SIGERROR_SUBDOMAIN 29 /* unauthorized subdomain */ /* ** DKIM_CANON -- canonicalization method */ typedef int dkim_canon_t; #define DKIM_CANON_UNKNOWN (-1) /* unknown method */ #define DKIM_CANON_SIMPLE 0 /* as specified in DKIM spec */ #define DKIM_CANON_RELAXED 1 /* as specified in DKIM spec */ #define DKIM_CANON_DEFAULT DKIM_CANON_SIMPLE /* ** DKIM_SIGN -- signing method */ typedef int dkim_alg_t; #define DKIM_SIGN_UNKNOWN (-1) /* unknown method */ #define DKIM_SIGN_RSASHA1 0 /* an RSA-signed SHA1 digest */ #ifdef SHA256_DIGEST_LENGTH # define DKIM_SIGN_RSASHA256 1 /* an RSA-signed SHA256 digest */ #endif /* SHA256_DIGEST_LENGTH */ #ifdef SHA256_DIGEST_LENGTH # define DKIM_SIGN_DEFAULT DKIM_SIGN_RSASHA256 #else /* SHA256_DIGEST_LENGTH */ # define DKIM_SIGN_DEFAULT DKIM_SIGN_RSASHA1 #endif /* SHA256_DIGEST_LENGTH */ /* ** DKIM_QUERY -- query method */ typedef int dkim_query_t; #define DKIM_QUERY_UNKNOWN (-1) /* unknown method */ #define DKIM_QUERY_DNS 0 /* DNS query method (per the draft) */ #define DKIM_QUERY_FILE 1 /* text file method (for testing) */ #define DKIM_QUERY_DEFAULT DKIM_QUERY_DNS /* ** DKIM_PARAM -- known signature parameters */ typedef int dkim_param_t; #define DKIM_PARAM_UNKNOWN (-1) /* unknown */ #define DKIM_PARAM_SIGNATURE 0 /* b */ #define DKIM_PARAM_SIGNALG 1 /* a */ #define DKIM_PARAM_DOMAIN 2 /* d */ #define DKIM_PARAM_CANONALG 3 /* c */ #define DKIM_PARAM_QUERYMETHOD 4 /* q */ #define DKIM_PARAM_SELECTOR 5 /* s */ #define DKIM_PARAM_HDRLIST 6 /* h */ #define DKIM_PARAM_VERSION 7 /* v */ #define DKIM_PARAM_IDENTITY 8 /* i */ #define DKIM_PARAM_TIMESTAMP 9 /* t */ #define DKIM_PARAM_EXPIRATION 10 /* x */ #define DKIM_PARAM_COPIEDHDRS 11 /* z */ #define DKIM_PARAM_BODYHASH 12 /* bh */ #define DKIM_PARAM_BODYLENGTH 13 /* l */ /* ** DKIM_KEY -- known key parameters */ typedef int dkim_key_t; #define DKIM_KEY_VERSION 0 /* v */ #define DKIM_KEY_GRANULARITY 1 /* g */ #define DKIM_KEY_ALGORITHM 2 /* a */ #define DKIM_KEY_NOTES 3 /* n */ #define DKIM_KEY_DATA 4 /* p */ #define DKIM_KEY_SERVICE 5 /* s */ #define DKIM_KEY_FLAGS 6 /* t */ /* ** DKIM_PPARAM -- policy parameters */ typedef int dkim_pparam_t; #define DKIM_PPARAM_POLICY 0 /* dkim */ #define DKIM_PPARAM_FLAGS 1 /* t */ #define DKIM_PPARAM_REPORTADDR 2 /* r */ #define DKIM_PPARAM_HANDLING 3 /* handling */ /* ** DKIM_POLICY -- policies */ typedef int dkim_policy_t; #define DKIM_POLICY_NONE (-1) /* none/undefined */ #define DKIM_POLICY_UNKNOWN 0 /* unknown */ #define DKIM_POLICY_ALL 1 /* all */ #define DKIM_POLICY_STRICT 2 /* strict */ #define DKIM_POLICY_DEFAULT DKIM_POLICY_UNKNOWN #define DKIM_POLICY_DEFAULTTXT "dkim=unknown" /* ** DKIM_HANDLING -- suspicious message handling */ typedef int dkim_handling_t; #define DKIM_HANDLING_NONE (-1) /* none/undefined */ #define DKIM_HANDLING_PROCESS 0 /* process message */ #define DKIM_HANDLING_DENY 1 /* block/reject message */ #define DKIM_HANDLING_DEFAULT DKIM_HANDLING_PROCESS /* ** DKIM_PFLAG -- policy flags */ #define DKIM_PFLAG_TEST 0x01 /* t */ #define DKIM_PFLAG_NOSUBDOMAIN 0x02 /* s */ #define DKIM_PFLAG_DEFAULT 0x00 /* ** DKIM_PRESULT -- policy results */ #define DKIM_PRESULT_NONE (-1) /* none/undefined */ #define DKIM_PRESULT_NXDOMAIN 0 /* domain does not exist */ #define DKIM_PRESULT_UNKNOWN 1 /* policy is "unknown" */ #define DKIM_PRESULT_TOPLEVEL 2 /* top-level domain */ #define DKIM_PRESULT_PARENTOK 3 /* parent domain check OK */ #define DKIM_PRESULT_NOSUBDOMAIN 4 /* no subdomains allowed */ #define DKIM_PRESULT_TESTFLAG 5 /* policy marked "test" */ #define DKIM_PRESULT_ALLVALIDSIG 6 /* policy "all", valid sig. */ #define DKIM_PRESULT_VALIDOSIG 7 /* valid originator sig. */ #define DKIM_PRESULT_POLICYERROR 8 /* policy check failed */ /* ** DKIM_MODE -- mode of a handle */ #define DKIM_MODE_UNKNOWN (-1) #define DKIM_MODE_SIGN 0 #define DKIM_MODE_VERIFY 1 /* ** DKIM_SETTYPE -- types of sets */ typedef int dkim_set_t; #define DKIM_SETTYPE_ANY (-1) #define DKIM_SETTYPE_SIGNATURE 0 #define DKIM_SETTYPE_POLICY 1 #define DKIM_SETTYPE_KEY 2 #ifdef _FFR_VBR # define DKIM_SETTYPE_VBRINFO 3 #endif /* _FFR_VBR */ /* ** DKIM_HASHTYPE -- types of hashes */ #define DKIM_HASHTYPE_UNKNOWN (-1) #define DKIM_HASHTYPE_SHA1 0 #ifdef SHA256_DIGEST_LENGTH # define DKIM_HASHTYPE_SHA256 1 #endif /* SHA256_DIGEST_LENGTH */ /* ** DKIM_KEYTYPE -- types of keys */ #define DKIM_KEYTYPE_UNKNOWN (-1) #define DKIM_KEYTYPE_RSA 0 /* ** DKIM_OPTS -- library-specific options */ typedef int dkim_opt_t; #define DKIM_OP_GETOPT 0 #define DKIM_OP_SETOPT 1 typedef int dkim_opts_t; #define DKIM_OPTS_FLAGS 0 #define DKIM_OPTS_TMPDIR 1 #define DKIM_OPTS_TIMEOUT 2 #define DKIM_OPTS_SENDERHDRS 3 #define DKIM_OPTS_SIGNHDRS 4 #define DKIM_OPTS_VERSION 5 /* unused */ #define DKIM_OPTS_QUERYMETHOD 6 #define DKIM_OPTS_QUERYINFO 7 #define DKIM_OPTS_FIXEDTIME 8 #define DKIM_OPTS_SKIPHDRS 9 #define DKIM_OPTS_ALWAYSHDRS 10 #define DKIM_OPTS_SIGNATURETTL 11 #define DKIM_OPTS_CLOCKDRIFT 12 #define DKIM_LIBFLAGS_NONE 0x00 #define DKIM_LIBFLAGS_TMPFILES 0x01 #define DKIM_LIBFLAGS_KEEPFILES 0x02 #define DKIM_LIBFLAGS_SIGNLEN 0x04 #define DKIM_LIBFLAGS_CACHE 0x08 #define DKIM_LIBFLAGS_ZTAGS 0x10 #define DKIM_LIBFLAGS_DELAYSIGPROC 0x20 #define DKIM_LIBFLAGS_EOHCHECK 0x40 #define DKIM_LIBFLAGS_ACCEPTV05 0x80 #define DKIM_LIBFLAGS_DEFAULT DKIM_LIBFLAGS_NONE /* ** DKIM_LIB -- library handle */ struct dkim_lib; typedef struct dkim_lib DKIM_LIB; /* ** DKIM -- DKIM context */ struct dkim; typedef struct dkim DKIM; /* ** DKIM_SET -- a set of parameters and values */ struct dkim_set; typedef struct dkim_set DKIM_SET; /* ** DKIM_PLIST -- a parameter/value pair, as a linked list */ struct dkim_plist; typedef struct dkim_plist DKIM_PLIST; /* ** DKIM_SIGNATURE -- contents of a DKIM-Signature: header */ struct dkim_signature; typedef struct dkim_signature DKIM_SIGNATURE; /* ** DKIM_SIGKEY_T -- private/public key (unencoded) */ typedef unsigned char * dkim_sigkey_t; /* ** DKIM_KEY -- contents of a published key record */ struct dkim_key; typedef struct dkim_key DKIM_KEY; /* ** DKIM_POLICY -- contents of a published policy record */ struct dkim_policy; typedef struct dkim_policy DKIM_POLICY; /* ** DKIM_CANON -- canonicalization */ struct dkim_canon; typedef struct dkim_canon DKIM_CANON; /* ** DKIM_SIGINFO -- signature information for use by the caller */ struct dkim_siginfo; typedef struct dkim_siginfo DKIM_SIGINFO; #define DKIM_SIGFLAG_IGNORE 0x01 #define DKIM_SIGFLAG_PROCESSED 0x02 #define DKIM_SIGFLAG_PASSED 0x04 #define DKIM_SIGFLAG_TESTKEY 0x08 #define DKIM_SIGFLAG_NOSUBDOMAIN 0x10 #define DKIM_SIGBH_UNTESTED (-1) #define DKIM_SIGBH_MATCH 0 #define DKIM_SIGBH_MISMATCH 1 /* ** DKIM_PSTATE -- policy query state */ struct dkim_pstate; typedef struct dkim_pstate DKIM_PSTATE; #ifdef _FFR_DIFFHEADERS /* ** DKIM_HDRDIFF -- header differences */ struct dkim_hdrdiff { u_char * hd_old; u_char * hd_new; }; #endif /* _FFR_DIFFHEADERS */ /* ** PROTOTYPES */ /* ** DKIM_INIT -- initialize the DKIM package ** ** Parameters: ** None. ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_LIB *dkim_init __P((void *(*mallocf)(void *closure, size_t nbytes), void (*freef)(void *closure, void *p))); /* ** DKIM_CLOSE -- shut down the DKIM package ** ** Parameters: ** lib -- DKIM_LIB handle to shut down ** ** Return value: ** None. */ extern void dkim_close __P((DKIM_LIB *lib)); /* ** DKIM_SIGN -- make a new DKIM context for signing ** ** Parameters: ** libhandle -- library handle, returned by dkim_init() ** id -- an opaque printable string for identifying this message, suitable ** for use in logging or debug output; may not be NULL ** memclosure -- memory closure, for use by user-provided malloc/free ** secretkey -- pointer to secret key data to use; if NULL, it will be ** obtained from disk ** selector -- selector being used to sign ** domain -- domain on behalf of which we're signing ** hdr_canon_alg -- canonicalization algorithm to use for headers; ** one of the DKIM_CANON_* macros, or -1 for default ** body_canon_alg -- canonicalization algorithm to use for body; ** one of the DKIM_CANON_* macros, or -1 for default ** sign_alg -- signing algorithm to use; one of the DKIM_SIGN_* macros, ** or -1 for default ** length -- number of bytes of the body to sign (-1 == all) ** statp -- pointer to a DKIM_STAT which is updated by this call ** ** Return value: ** A newly-allocated DKIM handle, or NULL on failure. "statp" will be ** updated. */ extern DKIM *dkim_sign __P((DKIM_LIB *libhandle, const char *id, void *memclosure, const dkim_sigkey_t secretkey, const char *selector, const char *domain, dkim_canon_t hdr_canon_alg, dkim_canon_t body_canon_alg, dkim_alg_t sign_alg, off_t length, DKIM_STAT *statp)); /* ** DKIM_VERIFY -- make a new DKIM context for verifying ** ** Parameters: ** libhandle -- library handle, returned by dkim_init() ** id -- an opaque printable string for identifying this message, suitable ** for use in logging or debug output; may not be NULL ** memclosure -- memory closure, for use by user-provided malloc/free ** statp -- pointer to a DKIM_STAT which is updated by this call ** ** Return value: ** A newly-allocated DKIM handle, or NULL on failure. "statp" will be ** updated. */ extern DKIM *dkim_verify __P((DKIM_LIB *libhandle, const char *id, void *memclosure, DKIM_STAT *statp)); /* ** DKIM_HEADER -- process a header ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** hdr -- the header to be processed, in canonical format ** len -- number of bytes to process starting at "hdr" ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_header __P((DKIM *dkim, u_char *hdr, size_t len)); /* ** DKIM_EOH -- identify end of headers ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** ** Return value: ** A DKIM_STAT value. DKIM_STAT_NOSIG will be returned if we're ** validating a signature but no DKIM signature was found in the headers. */ extern DKIM_STAT dkim_eoh __P((DKIM *dkim)); /* ** DKIM_BODY -- process a body chunk ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** buf -- the body chunk to be processed, in canonical format ** len -- number of bytes to process starting at "hdr" ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_body __P((DKIM *dkim, u_char *buf, size_t len)); /* ** DKIM_EOM -- identify end of body ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** testkey -- TRUE iff the a matching key was found but is marked as a ** test key (returned) ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_eom __P((DKIM *dkim, bool *testkey)); /* ** DKIM_GETCACHESTATS -- retrieve cache statistics ** ** Parameters: ** queries -- number of queries handled (returned) ** hits -- number of cache hits (returned) ** expired -- number of expired hits (returned) ** ** Return value: ** None. ** ** Notes: ** Any of the parameters may be NULL if the corresponding datum ** is not of interest. */ extern void dkim_getcachestats __P((u_int *queries, u_int *hits, u_int *expired)); /* ** DKIM_FLUSH_CACHE -- purge expired records from the database, reclaiming ** space for use by new data ** ** Parameters: ** lib -- DKIM library whose cache should be flushed ** ** Return value: ** -1 -- caching is not in effect ** >= 0 -- number of flushed records */ extern int dkim_flush_cache __P((DKIM_LIB *lib)); /* ** DKIM_MINBODY -- return number of bytes still expected ** ** Parameters: ** dkim -- DKIM handle ** ** Return value: ** 0 -- all canonicalizations satisfied ** ULONG_MAX -- at least one canonicalization wants the whole message ** other -- bytes required to satisfy all canonicalizations */ extern u_long dkim_minbody __P((DKIM *dkim)); /* ** DKIM_GETSIGLIST -- retrieve the list of signatures ** ** Parameters: ** dkim -- DKIM handle ** sigs -- pointer to a vector of DKIM_SIGINFO pointers (updated) ** nsigs -- pointer to an integer to receive the pointer count (updated) ** ** Return value: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_getsiglist __P((DKIM *dkim, DKIM_SIGINFO ***sigs, int *nsigs)); /* ** DKIM_GETSIGNATURE -- retrieve the "final" signature ** ** Parameters: ** dkim -- DKIM handle ** ** Return value: ** Pointer to a DKIM_SIGINFO handle which is the one libdkim will ** use to return a "final" result; NULL if none could be determined. */ extern DKIM_SIGINFO *dkim_getsignature __P((DKIM *dkim)); /* ** DKIM_GETSIGHDR -- compute and return a signature header for a message ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() ** buf -- buffer into which to write the signature ** len -- number of bytes available at "sig" ** margin -- attempt to wrap the header at the specified length ** initial -- width of the first line ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_getsighdr __P((DKIM *dkim, u_char *buf, size_t len, size_t margin, size_t initial)); /* ** DKIM_SIG_GETIDENTITY -- retrieve identity of the signer ** ** Parameters: ** dkim -- DKIM handle ** sig -- DKIM_SIGINFO handle (or NULL to choose final one) ** val -- destination buffer ** vallen -- size of destination buffer ** ** Return value: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_sig_getidentity __P((DKIM *dkim, DKIM_SIGINFO *sig, char *val, size_t vallen)); /* ** DKIM_SIG_GETCANONLEN -- report number of (canonicalized) body bytes that ** were signed ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** sig -- a DKIM_SIGINFO handle ** msglen -- total size of the message body (returned) ** canonlen -- total number of canonicalized bytes (returned) ** signlen -- restricted signature length (returned) ** ** Return value: ** A DKIM_STAT value. ** ** Notes: ** msglen or canonlen can be NULL if that information is not of interest ** to the caller. */ extern DKIM_STAT dkim_sig_getcanonlen __P((DKIM *dkim, DKIM_SIGINFO *sig, off_t *msglen, off_t *canonlen, off_t *signlen)); /* ** DKIM_REPORTINFO -- return info needed to generate failure report ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_verify() ** sig -- a DKIM_SIGINFO handle previously returned by dkim_getsignature() ** fd -- pointer to receive temporary file descriptor ** bfd -- pointer to receive temporary body file descriptor ** raddr -- buffer to receive report address ** rlen -- bytes available at raddr ** ** Return vlalue: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_reportinfo __P((DKIM *dkim, DKIM_SIGINFO *sig, int *fd, int *bfd, u_char *raddr, size_t rlen)); /* ** DKIM_OPTIONS -- set/get options ** ** Parameters: ** dklib -- DKIM library handle ** op -- operation (DKIM_OPT_GET or DKIM_OPT_SET) ** opt -- which option (a DKIM_OPTS_* constant) ** ptr -- value (in or out) ** len -- bytes available at "ptr" ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_options __P((DKIM_LIB *dklib, int op, dkim_opts_t opt, void *ptr, size_t len)); /* ** DKIM_SIG_GETFLAGS -- retreive signature handle flags ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** ** Return value: ** An unsigned integer which is a bitwise-OR of the DKIM_SIGFLAG_* ** constants currently set in the provided handle. */ extern unsigned int dkim_sig_getflags __P((DKIM_SIGINFO *sig)); /* ** DKIM_SIG_GETBH -- retreive signature handle "bh" test state ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** ** Return value: ** An unsigned integer which is one of the DKIM_SIGBH_* constants ** indicating the current state of "bh" evaluation of the signature. */ extern unsigned int dkim_sig_getbh __P((DKIM_SIGINFO *sig)); /* ** DKIM_SIG_GETKEYSIZE -- retreive key size after verifying ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** bits -- size of the key in bits (returned) ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_sig_getkeysize __P((DKIM_SIGINFO *sig, unsigned int *bits)); /* ** DKIM_SIG_GETSIGNALG -- retreive signature algorithm after verifying ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** alg -- a DKIM_SIGN_* value (returned) ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_sig_getsignalg __P((DKIM_SIGINFO *sig, dkim_alg_t *alg)); /* ** DKIM_SIG_GETSIGNTIME -- retreive signature timestamp after verifying ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** when -- timestamp on the signature (returned) ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_sig_getsigntime __P((DKIM_SIGINFO *sig, time_t *when)); /* ** DKIM_SIG_GETSELECTOR -- retrieve selector used to generate the signature ** ** Parameters: ** sig -- DKIM_SIGINFO handle from which to retrieve selector ** ** Return value: ** Selector found in the signature. */ extern char *dkim_sig_getselector __P((DKIM_SIGINFO *sig)); /* ** DKIM_SIG_GETDOMAIN -- retrieve signing domain after verifying ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** ** Return value: ** Pointer to the signing domain. */ extern char *dkim_sig_getdomain __P((DKIM_SIGINFO *sig)); #ifdef _FFR_STATS /* ** DKIM_SIG_GETCANONS -- retrieve canonicaliztions after verifying ** ** Parameters: ** sig -- DKIM_SIGINFO handle ** ** Return value: ** Pointer to the signing domain. */ extern DKIM_STAT dkim_sig_getcanons __P((DKIM_SIGINFO *sig, dkim_canon_t *hdr, dkim_canon_t *body)); #endif /* _FFR_STATS */ /* ** DKIM_SET_USER_CONTEXT -- set DKIM handle user context ** ** Parameters: ** dkim -- DKIM signing handle ** ctx -- user context pointer to store ** ** Parameters: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_set_user_context __P((DKIM *dkim, const void *ctx)); /* ** DKIM_GET_USER_CONTEXT -- retrieve DKIM handle user context ** ** Parameters: ** dkim -- DKIM signing handle ** ** Parameters: ** User context pointer. */ extern const void *dkim_get_user_context __P((DKIM *dkim)); #ifdef _FFR_PARSE_TIME /* ** DKIM_GET_MSGDATE -- retrieve value extracted from the Date: header ** ** Parameters: ** dkim -- DKIM handle ** ** Return value: ** time_t representing the value in the Date: header of the message, ** or 0 if no such header was found or the value in it was unusable */ extern time_t dkim_get_msgdate __P((DKIM *dkim)); #endif /* _FFR_PARSE_TIME */ /* ** DKIM_GETMODE -- return the mode (signing, verifying, etc.) of a handle ** ** Parameters: ** dkim -- DKIM handle ** ** Return value: ** A DKIM_MODE_* constant. */ extern int dkim_getmode __P((DKIM *dkim)); /* ** DKIM_GETDOMAIN -- retrieve policy domain from a DKIM context ** ** Parameters: ** dkim -- DKIM handle ** ** Return value: ** Pointer to the domain used for policy checking (if any) or NULL if ** no domain could be determined. */ extern u_char *dkim_getdomain __P((DKIM *dkim)); /* ** DKIM_SET_SIGNER -- set DKIM signature's signer ** ** Parameters: ** dkim -- DKIM signing handle ** signer -- signer to store ** ** Parameters: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_set_signer __P((DKIM *dkim, const char *signer)); /* ** DKIM_SET_DNS_CALLBACK -- set the DNS wait callback ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call; should take an opaque context pointer ** interval -- how often to call back ** ** Return value: ** None. */ extern DKIM_STAT dkim_set_dns_callback __P((DKIM_LIB *libdkim, void (*func)(const void *context), unsigned int interval)); /* ** DKIM_SET_KEY_LOOKUP -- set the key lookup function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** DKIM_STAT_OK */ extern DKIM_STAT dkim_set_key_lookup __P((DKIM_LIB *libdkim, DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO *sig, u_char *buf, size_t buflen))); /* ** DKIM_SET_POLICY_LOOKUP -- set the policy lookup function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** DKIM_STAT_OK */ extern DKIM_STAT dkim_set_policy_lookup __P((DKIM_LIB *libdkim, DKIM_CBSTAT (*func)(DKIM *dkim, u_char *query, bool usemx, u_char *buf, size_t buflen, int *qstat))); /* ** DKIM_SET_SIGNATURE_HANDLE -- set the signature handle creator function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** Pointer to the user-side handle thus created, or NULL. */ extern DKIM_STAT dkim_set_signature_handle __P((DKIM_LIB *libdkim, void * (*func)(void *closure))); /* ** DKIM_SET_SIGNATURE_HANDLE_FREE -- set the signature handle destroyer ** function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** None. */ extern DKIM_STAT dkim_set_signature_handle_free __P((DKIM_LIB *libdkim, void (*func)(void *closure, void *user))); /* ** DKIM_SET_SIGNATURE_TAGVALUES -- set the signature handle populator function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** DKIM_STAT_OK */ extern DKIM_STAT dkim_set_signature_tagvalues __P((DKIM_LIB *libdkim, void (*func)(void *user, dkim_param_t pcode, const u_char *param, const u_char *value))); /* ** DKIM_SET_PRESCREEN -- set the prescreen function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** DKIM_STAT_OK */ extern DKIM_STAT dkim_set_prescreen __P((DKIM_LIB *libdkim, DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO **sigs, int nsigs))); /* ** DKIM_SET_FINAL -- set the final processing function ** ** Parameters: ** libdkim -- DKIM library handle ** func -- function to call ** ** Return value: ** DKIM_STAT_OK */ extern DKIM_STAT dkim_set_final __P((DKIM_LIB *libdkim, DKIM_CBSTAT (*func)(DKIM *dkim, DKIM_SIGINFO **sigs, int nsigs))); /* ** DKIM_SIG_GETCONTEXT -- get user-specific context from a DKIM_SIGINFO ** ** Parameters: ** siginfo -- a pointer to a DKIM_SIGINFO ** ** Return value: ** The user-provided pointer stored in the named "siginfo", or NULL ** if none was ever set. */ extern void *dkim_sig_getcontext __P((DKIM_SIGINFO *siginfo)); /* ** DKIM_SIG_GETERROR -- get error code from a DKIM_SIGINFO ** ** Parameters: ** siginfo -- a pointer to a DKIM_SIGINFO ** ** Return value: ** A DKIM_SIGERROR_* constant. */ extern int dkim_sig_geterror __P((DKIM_SIGINFO *siginfo)); /* ** DKIM_SIG_GETERRORSTR -- translate a DKIM_SIGERROR into a string ** ** Parameters: ** sigerr -- a DKIM_SIGERROR constant ** ** Return value: ** A pointer to a human-readable string translation of "sigerr", or NULL ** if no such translation exists. */ extern const char *dkim_sig_geterrorstr __P((DKIM_SIGERROR sigerr)); /* ** DKIM_SIG_IGNORE -- mark a signature referenced by a DKIM_SIGINFO with ** an "ignore" flag ** ** Parameters: ** siginfo -- pointer to a DKIM_SIGINFO to update ** ** Return value: ** None. */ extern void dkim_sig_ignore __P((DKIM_SIGINFO *siginfo)); /* ** DKIM_POLICY -- parse policy associated with the sender's domain ** ** Parameters: ** dkim -- DKIM handle ** test -- policy test flag (returned) ** susp -- suspicious message flag (returned) ** pcode -- discovered policy (returned) ** hcode -- recommended suspicious message handling (returned) ** pstate -- state, for re-entrancy (updated; can be NULL) ** ** Return value: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_policy __P((DKIM *dkim, bool *test, bool *susp, dkim_policy_t *pcode, dkim_handling_t *hcode, DKIM_PSTATE *pstate)); /* ** DKIM_SIG_PROCESS -- process a signature ** ** Parameters: ** dkim -- DKIM handle ** sig -- DKIM_SIGINFO handle ** ** Return value: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_sig_process __P((DKIM *dkim, DKIM_SIGINFO *sig)); /* ** DKIM_FREE -- release resources associated with a DKIM handle ** ** Parameters: ** dkim -- a DKIM handle previously returned by dkim_sign() or ** dkim_verify() ** ** Return value: ** A DKIM_STAT value. */ extern DKIM_STAT dkim_free __P((DKIM *dkim)); /* ** DKIM_GETERROR -- return any stored error string from within the DKIM ** context handle ** ** Parameters: ** dkim -- DKIM handle from which to retrieve an error string ** ** Return value: ** A pointer to the stored string, or NULL if none was stored. */ extern const char *dkim_geterror __P((DKIM *dkim)); /* ** DKIM_GETRESULTSTR -- translate a DKIM_STAT_* constant to a string ** ** Parameters: ** result -- DKIM_STAT_* constant to translate ** ** Return value: ** Pointer to a text describing "result", or NULL if none exists */ extern const char *dkim_getresultstr __P((DKIM_STAT result)); /* ** DKIM_GETPRESULT -- retrieve policy result ** ** Parameters: ** dkim -- DKIM handle from which to get policy result ** ** Return value: ** DKIM policy check result. */ extern int dkim_getpresult __P((DKIM *dkim)); /* ** DKIM_GETPRESULTSTR -- retrieve policy result string ** ** Parameters: ** presult -- policy result code to translate ** ** Return value: ** Pointer to text that describes "presult". */ extern const char *dkim_getpresultstr __P((int presult)); /* ** DKIM_GETHANDLINGSTR -- retrieve handling result string ** ** Parameters: ** hresult -- policy result code to translate ** ** Return value: ** Pointer to text that describes "hresult". */ extern const char *dkim_gethandlingstr __P((int hresult)); /* ** DKIM_GETPOLICYSTR -- retrieve sender policy string ** ** Parameters: ** policy -- policy code to translate ** ** Return value: ** Pointer to text that describes "policy". */ extern const char *dkim_getpolicystr __P((int policy)); /* ** DKIM_OHDRS -- extract and decode original headers ** ** Parameters: ** dkim -- DKIM handle ** sig -- DKIM_SIGINFO handle ** ptrs -- user-provided array of pointers to header strings (updated) ** pcnt -- number of pointers available (updated) ** ** Return value: ** A DKIM_STAT_* constant. */ extern DKIM_STAT dkim_ohdrs __P((DKIM *dkim, DKIM_SIGINFO *sig, char **ptrs, int *pcnt)); #ifdef _FFR_DIFFHEADERS /* ** DKIM_DIFFHEADERS -- compare original headers with received headers ** ** Parameters: ** dkim -- DKIM handle ** maxcost -- maximum "cost" of changes to be reported ** ohdrs -- original headers, presumably extracted from a "z" tag ** nohdrs -- number of headers at "ohdrs" available ** out -- pointer to an array of struct dkim_hdrdiff objects (updated) ** nout -- counter of handles returned (updated) ** ** Return value: ** A DKIM_STAT_* constant. ** ** Side effects: ** A series of DKIM_HDRDIFF handles is allocated and must later be ** destroyed. */ extern DKIM_STAT dkim_diffheaders __P((DKIM *dkim, int maxcost, char **ohdrs, int nohdrs, struct dkim_hdrdiff **out, int *nout)); #endif /* _FFR_DIFFHEADERS */ /* ** RFC2822_MAILBOX_SPLIT -- extract the userid and host from a structured ** header ** ** Parameters: ** addr -- the header to parse; see RFC2822 for format ** user -- local-part of the parsed header (returned) ** domain -- domain part of the parsed header (returned) ** ** Return value: ** 0 on success; other on error (see source) */ extern int rfc2822_mailbox_split __P((char *addr, char **user, char **domain)); /* ** DKIM_SSL_VERSION -- return the version of the OpenSSL library against ** which this library was compiled ** ** Parameters: ** None. ** ** Return value: ** The OPENSSL_VERSION_NUMBER constant as defined by OpenSSL. */ extern unsigned long dkim_ssl_version __P((void)); /* default list of sender headers */ extern const u_char *default_senderhdrs[]; /* list of headers that should be signed, per RFC4871 section 5.5 */ extern const u_char *should_signhdrs[]; /* list of headers that should not be signed, per RFC4871 section 5.5 */ extern const u_char *should_not_signhdrs[]; #endif /* ! _DKIM_H_ */