Back to index

opendkim  2.6.2
dkim.h
Go to the documentation of this file.
00001 /*
00002 **  Copyright (c) 2005-2009 Sendmail, Inc. and its suppliers.
00003 **    All rights reserved.
00004 **
00005 **  Copyright (c) 2009-2012, The OpenDKIM Project.  All rights reserved.
00006 */
00007 
00008 #ifndef _DKIM_H_
00009 #define _DKIM_H_
00010 
00011 #ifdef __cplusplus
00012 extern "C" {
00013 #endif /* __cplusplus */
00014 
00015 #ifndef lint
00016 static char dkim_h_id[] = "@(#)$Id: dkim.h,v 1.36.2.1 2010/10/27 21:43:08 cm-msk Exp $";
00017 #endif /* !lint */
00018 
00019 /* system includes */
00020 #include <sys/types.h>
00021 #include <sys/param.h>
00022 #include <sys/time.h>
00023 #ifdef HAVE_STDBOOL_H
00024 # include <stdbool.h>
00025 #endif /* HAVE_STDBOOL_H */
00026 #include <inttypes.h>
00027 
00028 /*
00029 **  version -- 0xrrMMmmpp
00030 **  
00031 **     rr == release number
00032 **     MM == major revision number
00033 **     mm == minor revision number
00034 **     pp == patch number
00035 */
00036 
00037 #define       OPENDKIM_LIB_VERSION 0x02060200
00038 
00039 #ifdef __STDC__
00040 # ifndef __P
00041 #  define __P(x)  x
00042 # endif /* ! __P */
00043 #else /* __STDC__ */
00044 # ifndef __P
00045 #  define __P(x)  ()
00046 # endif /* ! __P */
00047 #endif /* __STDC__ */
00048 
00049 /* definitions */
00050 #define       DKIM_ATPSTAG         "atps" /* ATPS tag name */
00051 #define       DKIM_ATPSHTAG        "atpsh"       /* ATPS tag name */
00052 #define DKIM_HDRMARGIN             75     /* "standard" header margin */
00053 #define DKIM_MAXHEADER             4096   /* buffer for caching one header */
00054 #define       DKIM_MAXHOSTNAMELEN  256    /* max. FQDN we support */
00055 #define       DKIM_REPORTTAG              "r"    /* DKIM reporting request tag */
00056 #define       DKIM_REPORTTAGVAL    "y"    /* DKIM reporting request tag value */
00057 #define       DKIM_SIGNHEADER             "DKIM-Signature"
00058                                    /* DKIM signature header */
00059 
00060 /* special DNS tokens */
00061 #define       DKIM_DNSKEYNAME             "_domainkey"
00062                                    /* reserved DNS sub-zone */
00063 #define       DKIM_DNSPOLICYNAME   "_adsp"       /* reserved DNS sub-zone */
00064 
00065 /* macros */
00066 #define       DKIM_SIG_CHECK(x)    ((dkim_sig_getflags((x)) & DKIM_SIGFLAG_PASSED != 0) && (dkim_sig_getbh((x)) == DKIM_SIGBH_MATCH))
00067 
00068 /*
00069 **  DKIM_STAT -- status code type
00070 */
00071 
00072 typedef int DKIM_STAT;
00073 
00074 #define       DKIM_STAT_OK         0      /* function completed successfully */
00075 #define       DKIM_STAT_BADSIG     1      /* signature available but failed */
00076 #define       DKIM_STAT_NOSIG             2      /* no signature available */
00077 #define       DKIM_STAT_NOKEY             3      /* public key not found */
00078 #define       DKIM_STAT_CANTVRFY   4      /* can't get domain key to verify */
00079 #define       DKIM_STAT_SYNTAX     5      /* message is not valid syntax */
00080 #define       DKIM_STAT_NORESOURCE 6      /* resource unavailable */
00081 #define       DKIM_STAT_INTERNAL   7      /* internal error */
00082 #define       DKIM_STAT_REVOKED    8      /* key found, but revoked */
00083 #define       DKIM_STAT_INVALID    9      /* invalid function parameter */
00084 #define       DKIM_STAT_NOTIMPLEMENT      10     /* function not implemented */
00085 #define       DKIM_STAT_KEYFAIL    11     /* key retrieval failed */
00086 #define       DKIM_STAT_CBREJECT   12     /* callback requested reject */
00087 #define       DKIM_STAT_CBINVALID  13     /* callback gave invalid result */
00088 #define       DKIM_STAT_CBTRYAGAIN 14     /* callback says try again later */
00089 #define       DKIM_STAT_CBERROR    15     /* callback error */
00090 #define       DKIM_STAT_MULTIDNSREPLY     16     /* multiple DNS replies */
00091 
00092 /*
00093 **  DKIM_CBSTAT -- callback status code type
00094 */
00095 
00096 typedef int DKIM_CBSTAT;
00097 
00098 #define       DKIM_CBSTAT_CONTINUE 0      /* continue */
00099 #define       DKIM_CBSTAT_REJECT   1      /* reject */
00100 #define       DKIM_CBSTAT_TRYAGAIN 2      /* try again later */
00101 #define       DKIM_CBSTAT_NOTFOUND 3      /* requested record not found */
00102 #define       DKIM_CBSTAT_ERROR    4      /* error requesting record */
00103 
00104 /*
00105 **  DKIM_SIGERROR -- signature errors
00106 */
00107 
00108 typedef int DKIM_SIGERROR;
00109 
00110 #define DKIM_SIGERROR_UNKNOWN             (-1)   /* unknown error */
00111 #define DKIM_SIGERROR_OK           0      /* no error */
00112 #define DKIM_SIGERROR_VERSION             1      /* unsupported version */
00113 #define DKIM_SIGERROR_DOMAIN              2      /* invalid domain (d=/i=) */
00114 #define DKIM_SIGERROR_EXPIRED             3      /* signature expired */
00115 #define DKIM_SIGERROR_FUTURE              4      /* signature in the future */
00116 #define DKIM_SIGERROR_TIMESTAMPS   5      /* x= < t= */
00117 #define DKIM_SIGERROR_UNUSED              6      /* OBSOLETE */
00118 #define DKIM_SIGERROR_INVALID_HC   7      /* c= invalid (header) */
00119 #define DKIM_SIGERROR_INVALID_BC   8      /* c= invalid (body) */
00120 #define DKIM_SIGERROR_MISSING_A           9      /* a= missing */
00121 #define DKIM_SIGERROR_INVALID_A           10     /* a= invalid */
00122 #define DKIM_SIGERROR_MISSING_H           11     /* h= missing */
00123 #define DKIM_SIGERROR_INVALID_L           12     /* l= invalid */
00124 #define DKIM_SIGERROR_INVALID_Q           13     /* q= invalid */
00125 #define DKIM_SIGERROR_INVALID_QO   14     /* q= option invalid */
00126 #define DKIM_SIGERROR_MISSING_D           15     /* d= missing */
00127 #define DKIM_SIGERROR_EMPTY_D             16     /* d= empty */
00128 #define DKIM_SIGERROR_MISSING_S           17     /* s= missing */
00129 #define DKIM_SIGERROR_EMPTY_S             18     /* s= empty */
00130 #define DKIM_SIGERROR_MISSING_B           19     /* b= missing */
00131 #define DKIM_SIGERROR_EMPTY_B             20     /* b= empty */
00132 #define DKIM_SIGERROR_CORRUPT_B           21     /* b= corrupt */
00133 #define DKIM_SIGERROR_NOKEY        22     /* no key found in DNS */
00134 #define DKIM_SIGERROR_DNSSYNTAX           23     /* DNS reply corrupt */
00135 #define DKIM_SIGERROR_KEYFAIL             24     /* DNS query failed */
00136 #define DKIM_SIGERROR_MISSING_BH   25     /* bh= missing */
00137 #define DKIM_SIGERROR_EMPTY_BH            26     /* bh= empty */
00138 #define DKIM_SIGERROR_CORRUPT_BH   27     /* bh= corrupt */
00139 #define DKIM_SIGERROR_BADSIG              28     /* signature mismatch */
00140 #define DKIM_SIGERROR_SUBDOMAIN           29     /* unauthorized subdomain */
00141 #define DKIM_SIGERROR_MULTIREPLY   30     /* multiple records returned */
00142 #define DKIM_SIGERROR_EMPTY_H             31     /* h= empty */
00143 #define DKIM_SIGERROR_INVALID_H           32     /* h= missing req'd entries */
00144 #define DKIM_SIGERROR_TOOLARGE_L   33     /* l= value exceeds body size */
00145 #define DKIM_SIGERROR_MBSFAILED           34     /* "must be signed" failure */
00146 #define       DKIM_SIGERROR_KEYVERSION    35     /* unknown key version */
00147 #define       DKIM_SIGERROR_KEYUNKNOWNHASH       36     /* unknown key hash */
00148 #define       DKIM_SIGERROR_KEYHASHMISMATCH      37     /* sig-key hash mismatch */
00149 #define       DKIM_SIGERROR_NOTEMAILKEY   38     /* not an e-mail key */
00150 #define       DKIM_SIGERROR_UNUSED2              39     /* OBSOLETE */
00151 #define       DKIM_SIGERROR_KEYTYPEMISSING       40     /* key type missing */
00152 #define       DKIM_SIGERROR_KEYTYPEUNKNOWN       41     /* key type unknown */
00153 #define       DKIM_SIGERROR_KEYREVOKED    42     /* key revoked */
00154 #define       DKIM_SIGERROR_KEYDECODE            43     /* key couldn't be decoded */
00155 #define       DKIM_SIGERROR_MISSING_V            44     /* v= tag missing */
00156 #define       DKIM_SIGERROR_EMPTY_V              45     /* v= tag empty */
00157 
00158 /* generic DNS error codes */
00159 #define       DKIM_DNS_ERROR              (-1)          /* error in transit */
00160 #define       DKIM_DNS_SUCCESS     0             /* reply available */
00161 #define       DKIM_DNS_NOREPLY     1             /* reply not available (yet) */
00162 #define       DKIM_DNS_EXPIRED     2             /* no reply, query expired */
00163 
00164 /*
00165 **  DKIM_CANON -- canonicalization method
00166 */
00167 
00168 typedef int dkim_canon_t;
00169 
00170 #define DKIM_CANON_UNKNOWN  (-1)   /* unknown method */
00171 #define DKIM_CANON_SIMPLE   0      /* as specified in DKIM spec */
00172 #define DKIM_CANON_RELAXED  1      /* as specified in DKIM spec */
00173 
00174 #define DKIM_CANON_DEFAULT  DKIM_CANON_SIMPLE
00175 
00176 /*
00177 **  DKIM_SIGN -- signing method
00178 */
00179 
00180 typedef int dkim_alg_t;
00181 
00182 #define DKIM_SIGN_UNKNOWN   (-2)   /* unknown method */
00183 #define DKIM_SIGN_DEFAULT   (-1)   /* use internal default */
00184 #define DKIM_SIGN_RSASHA1   0      /* an RSA-signed SHA1 digest */
00185 #define DKIM_SIGN_RSASHA256 1      /* an RSA-signed SHA256 digest */
00186 
00187 /*
00188 **  DKIM_QUERY -- query method
00189 */
00190 
00191 typedef int dkim_query_t;
00192 
00193 #define DKIM_QUERY_UNKNOWN  (-1)   /* unknown method */
00194 #define DKIM_QUERY_DNS             0      /* DNS query method (per the draft) */
00195 #define DKIM_QUERY_FILE            1      /* text file method (for testing) */
00196 
00197 #define DKIM_QUERY_DEFAULT  DKIM_QUERY_DNS
00198 
00199 /*
00200 **  DKIM_PARAM -- known signature parameters
00201 */
00202 
00203 typedef int dkim_param_t;
00204 
00205 #define DKIM_PARAM_UNKNOWN  (-1)   /* unknown */
00206 #define DKIM_PARAM_SIGNATURE       0      /* b */
00207 #define DKIM_PARAM_SIGNALG  1      /* a */
00208 #define DKIM_PARAM_DOMAIN   2      /* d */
00209 #define DKIM_PARAM_CANONALG 3      /* c */
00210 #define DKIM_PARAM_QUERYMETHOD     4      /* q */
00211 #define DKIM_PARAM_SELECTOR 5      /* s */
00212 #define DKIM_PARAM_HDRLIST  6      /* h */
00213 #define DKIM_PARAM_VERSION  7      /* v */
00214 #define DKIM_PARAM_IDENTITY 8      /* i */
00215 #define DKIM_PARAM_TIMESTAMP       9      /* t */
00216 #define DKIM_PARAM_EXPIRATION      10     /* x */
00217 #define DKIM_PARAM_COPIEDHDRS      11     /* z */
00218 #define DKIM_PARAM_BODYHASH 12     /* bh */
00219 #define DKIM_PARAM_BODYLENGTH      13     /* l */
00220 
00221 /*
00222 **  DKIM_POLICY -- policies
00223 */
00224 
00225 typedef int dkim_policy_t;
00226 
00227 #define DKIM_POLICY_NONE    (-1)   /* none/undefined */
00228 #define DKIM_POLICY_UNKNOWN 0      /* unknown */
00229 #define DKIM_POLICY_ALL            1      /* all */
00230 #define DKIM_POLICY_DISCARDABLE    2      /* discardable */
00231 
00232 #define DKIM_POLICY_DEFAULT DKIM_POLICY_UNKNOWN
00233 #define DKIM_POLICY_DEFAULTTXT     "dkim=unknown"
00234 
00235 /*
00236 **  DKIM_PRESULT -- policy results
00237 */
00238 
00239 #define DKIM_PRESULT_NONE          (-1)   /* none/undefined */
00240 #define DKIM_PRESULT_NXDOMAIN             0      /* domain does not exist */
00241 #define DKIM_PRESULT_FOUND         1      /* ADSP query succeeded */
00242 
00243 /*
00244 **  DKIM_MODE -- mode of a handle
00245 */
00246 
00247 #define       DKIM_MODE_UNKNOWN    (-1)
00248 #define       DKIM_MODE_SIGN              0
00249 #define       DKIM_MODE_VERIFY     1
00250 
00251 /*
00252 **  DKIM_OPTS -- library-specific options
00253 */
00254 
00255 typedef int dkim_opt_t;
00256 
00257 #define DKIM_OP_GETOPT             0
00258 #define       DKIM_OP_SETOPT              1
00259 
00260 typedef int dkim_opts_t;
00261 
00262 #define       DKIM_OPTS_FLAGS             0
00263 #define       DKIM_OPTS_TMPDIR     1
00264 #define       DKIM_OPTS_TIMEOUT    2
00265 #define       DKIM_OPTS_SENDERHDRS 3
00266 #define       DKIM_OPTS_SIGNHDRS   4
00267 #define       DKIM_OPTS_OVERSIGNHDRS      5
00268 #define       DKIM_OPTS_QUERYMETHOD       6
00269 #define       DKIM_OPTS_QUERYINFO  7
00270 #define       DKIM_OPTS_FIXEDTIME  8
00271 #define       DKIM_OPTS_SKIPHDRS   9
00272 #define       DKIM_OPTS_ALWAYSHDRS 10
00273 #define       DKIM_OPTS_SIGNATURETTL      11
00274 #define       DKIM_OPTS_CLOCKDRIFT 12
00275 #define       DKIM_OPTS_MUSTBESIGNED      13
00276 
00277 #define       DKIM_LIBFLAGS_NONE          0x0000
00278 #define       DKIM_LIBFLAGS_TMPFILES             0x0001
00279 #define       DKIM_LIBFLAGS_KEEPFILES            0x0002
00280 #define       DKIM_LIBFLAGS_SIGNLEN              0x0004
00281 #define DKIM_LIBFLAGS_CACHE        0x0008
00282 #define DKIM_LIBFLAGS_ZTAGS        0x0010
00283 #define DKIM_LIBFLAGS_DELAYSIGPROC 0x0020
00284 #define DKIM_LIBFLAGS_EOHCHECK            0x0040
00285 #define DKIM_LIBFLAGS_ACCEPTV05           0x0080
00286 #define DKIM_LIBFLAGS_FIXCRLF             0x0100
00287 #define DKIM_LIBFLAGS_ACCEPTDK            0x0200
00288 #define DKIM_LIBFLAGS_BADSIGHANDLES       0x0400
00289 #define DKIM_LIBFLAGS_VERIFYONE           0x0800
00290 #define DKIM_LIBFLAGS_STRICTHDRS   0x1000
00291 #define DKIM_LIBFLAGS_REPORTBADADSP       0x2000
00292 #define DKIM_LIBFLAGS_DROPSIGNER   0x4000
00293 
00294 #define       DKIM_LIBFLAGS_DEFAULT              DKIM_LIBFLAGS_NONE
00295 
00296 /*
00297 **  DKIM_PFLAG -- policy flags
00298 */
00299 
00300 #define       DKIM_PFLAG_UNUSED1   0x01   /* no longer used */
00301 #define       DKIM_PFLAG_UNUSED2   0x02   /* no longer used */
00302 
00303 /*
00304 **  DKIM_DNSSEC -- results of DNSSEC queries
00305 */
00306 
00307 #define DKIM_DNSSEC_UNKNOWN (-1)
00308 #define DKIM_DNSSEC_BOGUS   0
00309 #define DKIM_DNSSEC_INSECURE       1
00310 #define DKIM_DNSSEC_SECURE  2
00311 
00312 /*
00313 **  DKIM_ATPS -- ATPS result codes
00314 */
00315 
00316 #define       DKIM_ATPS_UNKNOWN    (-1)
00317 #define       DKIM_ATPS_NOTFOUND   0
00318 #define       DKIM_ATPS_FOUND             1
00319 
00320 typedef int dkim_atps_t;
00321 
00322 /*
00323 **  DKIM_LIB -- library handle
00324 */
00325 
00326 struct dkim_lib;
00327 typedef struct dkim_lib DKIM_LIB;
00328 
00329 /*
00330 **  DKIM -- DKIM context
00331 */
00332 
00333 struct dkim;
00334 typedef struct dkim DKIM;
00335 
00336 /*
00337 **  DKIM_SIGKEY_T -- private/public key (unencoded)
00338 */
00339 
00340 typedef unsigned char * dkim_sigkey_t;
00341 
00342 /*
00343 **  DKIM_SIGINFO -- signature information for use by the caller
00344 */
00345 
00346 struct dkim_siginfo;
00347 typedef struct dkim_siginfo DKIM_SIGINFO;
00348 
00349 #define DKIM_SIGFLAG_IGNORE        0x01
00350 #define DKIM_SIGFLAG_PROCESSED            0x02
00351 #define DKIM_SIGFLAG_PASSED        0x04
00352 #define DKIM_SIGFLAG_TESTKEY              0x08
00353 #define DKIM_SIGFLAG_NOSUBDOMAIN   0x10
00354 #define DKIM_SIGFLAG_KEYLOADED            0x20
00355 
00356 #define DKIM_SIGBH_UNTESTED        (-1)
00357 #define DKIM_SIGBH_MATCH           0
00358 #define DKIM_SIGBH_MISMATCH        1
00359 
00360 /*
00361 **  DKIM_QUERYINFO -- information about a DNS query that is/may be needed
00362 */
00363 
00364 struct dkim_queryinfo;
00365 typedef struct dkim_queryinfo DKIM_QUERYINFO;
00366 
00367 /*
00368 **  DKIM_PSTATE -- policy query state
00369 */
00370 
00371 struct dkim_pstate;
00372 typedef struct dkim_pstate DKIM_PSTATE;
00373 
00374 /*
00375 **  DKIM_HDRDIFF -- header differences
00376 */
00377 
00378 struct dkim_hdrdiff
00379 {
00380        u_char *             hd_old;
00381        u_char *             hd_new;
00382 };
00383 
00384 /*
00385 **  PROTOTYPES
00386 */
00387 
00388 /*
00389 **  DKIM_INIT -- initialize the DKIM package
00390 **
00391 **  Parameters:
00392 **     mallocf -- a function to receive malloc()-like calls, or NULL
00393 **     freef -- a function to receive corresponding free()-like calls, or NULL
00394 **
00395 **  Return value:
00396 **     A new DKIM library instance handle, or NULL on failure.
00397 */
00398 
00399 extern DKIM_LIB *dkim_init __P((void *(*mallocf)(void *closure, size_t nbytes),
00400                                 void (*freef)(void *closure, void *p)));
00401 
00402 /*
00403 **  DKIM_CLOSE -- shut down the DKIM package
00404 **
00405 **  Parameters:
00406 **     lib -- DKIM_LIB handle to shut down
00407 **
00408 **  Return value:
00409 **     None.
00410 */
00411 
00412 extern void dkim_close __P((DKIM_LIB *lib));
00413 
00414 /*
00415 **  DKIM_SIGN -- make a new DKIM context for signing
00416 **
00417 **  Parameters:
00418 **     libhandle -- library handle, returned by dkim_init()
00419 **     id -- an opaque printable string for identifying this message, suitable
00420 **           for use in logging or debug output; may not be NULL
00421 **     memclosure -- memory closure, for use by user-provided malloc/free
00422 **     secretkey -- pointer to secret key data to use; if NULL, it will be
00423 **                  obtained from disk
00424 **     selector -- selector being used to sign
00425 **     domain -- domain on behalf of which we're signing
00426 **     hdr_canon_alg -- canonicalization algorithm to use for headers;
00427 **                      one of the DKIM_CANON_* macros, or -1 for default
00428 **     body_canon_alg -- canonicalization algorithm to use for body;
00429 **                       one of the DKIM_CANON_* macros, or -1 for default
00430 **     sign_alg -- signing algorithm to use; one of the DKIM_SIGN_* macros,
00431 **                 or -1 for default
00432 **     length -- number of bytes of the body to sign (-1 == all)
00433 **     statp -- pointer to a DKIM_STAT which is updated by this call
00434 **
00435 **  Return value:
00436 **     A newly-allocated DKIM handle, or NULL on failure.  "statp" will be
00437 **     updated.
00438 */
00439 
00440 extern DKIM *dkim_sign __P((DKIM_LIB *libhandle, const unsigned char *id,
00441                             void *memclosure, const dkim_sigkey_t secretkey,
00442                             const unsigned char *selector,
00443                             const unsigned char *domain,
00444                             dkim_canon_t hdr_canon_alg,
00445                             dkim_canon_t body_canon_alg,
00446                             dkim_alg_t sign_alg,
00447                             ssize_t length, DKIM_STAT *statp));
00448 
00449 /*
00450 **  DKIM_VERIFY -- make a new DKIM context for verifying
00451 **
00452 **  Parameters:
00453 **     libhandle -- library handle, returned by dkim_init()
00454 **     id -- an opaque printable string for identifying this message, suitable
00455 **           for use in logging or debug output; may not be NULL
00456 **     memclosure -- memory closure, for use by user-provided malloc/free
00457 **     statp -- pointer to a DKIM_STAT which is updated by this call
00458 **
00459 **  Return value:
00460 **     A newly-allocated DKIM handle, or NULL on failure.  "statp" will be
00461 **     updated.
00462 */
00463 
00464 extern DKIM *dkim_verify __P((DKIM_LIB *libhandle, const unsigned char *id,
00465                               void *memclosure, DKIM_STAT *statp));
00466 
00467 /*
00468 **  DKIM_RESIGN -- bind a new signing handle to a completed handle
00469 **
00470 **  Parameters:
00471 **     new -- new signing handle
00472 **     old -- old signing/verifying handle
00473 **     hdrbind -- bind headers as well as body
00474 **
00475 **  Return value:
00476 **     DKIM_STAT_OK -- success
00477 **     DKIM_STAT_INVALID -- invalid state of one or both handles
00478 **     DKIM_STAT_NOTIMPLEMENT -- not enabled at compile-time
00479 **
00480 **  Side effects:
00481 **     Sets up flags such that the two are bound; dkim_free() on "old"
00482 **     now does nothing, and dkim_free() on "new" will free "old" once
00483 **     its reference count reaches zero.  See documentation for details.
00484 */
00485 
00486 extern DKIM_STAT dkim_resign __P((DKIM *news, DKIM *olds, _Bool hdrbind));
00487 
00488 /*
00489 **  DKIM_HEADER -- process a header
00490 **
00491 **  Parameters:
00492 **     dkim -- a DKIM handle previously returned by dkim_sign() or
00493 **             dkim_verify()
00494 **     hdr -- the header to be processed, in canonical format
00495 **     len -- number of bytes to process starting at "hdr"
00496 **
00497 **  Return value:
00498 **     A DKIM_STAT value.
00499 */
00500 
00501 extern DKIM_STAT dkim_header __P((DKIM *dkim, u_char *hdr, size_t len));
00502 
00503 /*
00504 **  DKIM_EOH -- identify end of headers
00505 **
00506 **  Parameters:
00507 **     dkim -- a DKIM handle previously returned by dkim_sign() or
00508 **             dkim_verify()
00509 **
00510 **  Return value:
00511 **     A DKIM_STAT value.  DKIM_STAT_NOSIG will be returned if we're
00512 **     validating a signature but no DKIM signature was found in the headers.
00513 */
00514 
00515 extern DKIM_STAT dkim_eoh __P((DKIM *dkim));
00516 
00517 /*
00518 **  DKIM_BODY -- process a body chunk
00519 **
00520 **  Parameters:
00521 **     dkim -- a DKIM handle previously returned by dkim_sign() or
00522 **             dkim_verify()
00523 **     buf -- the body chunk to be processed, in canonical format
00524 **     len -- number of bytes to process starting at "hdr"
00525 **
00526 **  Return value:
00527 **     A DKIM_STAT value.
00528 */
00529 
00530 extern DKIM_STAT dkim_body __P((DKIM *dkim, u_char *buf, size_t len));
00531 
00532 /*
00533 **  DKIM_CHUNK -- process a message chunk
00534 **
00535 **  Parameters:
00536 **     dkim -- DKIM handle
00537 **     buf -- data to process
00538 **     buflen -- number of bytes at "buf" to process
00539 **
00540 **  Return value:
00541 **     A DKIM_STAT_* constant.
00542 */
00543 
00544 extern DKIM_STAT dkim_chunk __P((DKIM *dkim, u_char *buf, size_t buflen));
00545 
00546 /*
00547 **  DKIM_EOM -- identify end of body
00548 **
00549 **  Parameters:
00550 **     dkim -- a DKIM handle previously returned by dkim_sign() or
00551 **             dkim_verify()
00552 **     testkey -- TRUE iff the a matching key was found but is marked as a
00553 **                test key (returned)
00554 **
00555 **  Return value:
00556 **     A DKIM_STAT value.
00557 */
00558 
00559 extern DKIM_STAT dkim_eom __P((DKIM *dkim, _Bool *testkey));
00560 
00561 /*
00562 **  DKIM_KEY_SYNTAX -- process a key record parameter set for valid syntax
00563 **
00564 **  Parameters:
00565 **     dkim -- DKIM context in which this is performed
00566 **     str -- string to be scanned
00567 **     len -- number of bytes available at "str"
00568 **
00569 **  Return value:
00570 **     A DKIM_STAT constant.
00571 */
00572 
00573 extern DKIM_STAT dkim_key_syntax __P((DKIM *dkim, u_char *str, size_t len));
00574 
00575 /*
00576 **  DKIM_POLICY_SYNTAX -- process a policy record parameter set
00577 **                        for valid syntax
00578 **
00579 **  Parameters:
00580 **     dkim -- DKIM context in which this is performed
00581 **     str -- string to be scanned
00582 **     len -- number of bytes available at "str"
00583 **
00584 **  Return value:
00585 **     A DKIM_STAT constant.
00586 */
00587 
00588 extern DKIM_STAT dkim_policy_syntax __P((DKIM *dkim, u_char *str, size_t len));
00589 
00590 /*
00591 **  DKIM_SIG_SYNTAX -- process a signature parameter set for valid syntax
00592 **
00593 **  Parameters:
00594 **     dkim -- DKIM context in which this is performed
00595 **     str -- string to be scanned
00596 **     len -- number of bytes available at "str"
00597 **
00598 **  Return value:
00599 **     A DKIM_STAT constant.
00600 */
00601 
00602 extern DKIM_STAT dkim_sig_syntax __P((DKIM *dkim, u_char *str, size_t len));
00603 
00604 /*
00605 **  DKIM_GETID -- retrieve "id" pointer from a handle
00606 **
00607 **  Parameters:
00608 **     dkim -- DKIM handle
00609 **
00610 **  Return value:
00611 **     The "id" pointer from inside the handle, stored when it was created.
00612 */
00613 
00614 extern const char *dkim_getid __P((DKIM *dkim));
00615 
00616 /*
00617 **  DKIM_GETCACHESTATS -- retrieve cache statistics
00618 **
00619 **  Parameters:
00620 **     queries -- number of queries handled (returned)
00621 **     hits -- number of cache hits (returned)
00622 **     expired -- number of expired hits (returned)
00623 **
00624 **  Return value:
00625 **     DKIM_STAT_OK -- statistics returned
00626 **     DKIM_STAT_NOTIMPLEMENT -- function not implemented
00627 **
00628 **  Notes:
00629 **     Any of the parameters may be NULL if the corresponding datum
00630 **     is not of interest.
00631 */
00632 
00633 extern DKIM_STAT dkim_getcachestats __P((u_int *queries, u_int *hits,
00634                                          u_int *expired));
00635 
00636 /*
00637 **  DKIM_FLUSH_CACHE -- purge expired records from the database, reclaiming
00638 **                      space for use by new data
00639 **
00640 **  Parameters:
00641 **     lib -- DKIM library whose cache should be flushed
00642 **
00643 **  Return value:
00644 **     -1 -- caching is not in effect
00645 **     >= 0 -- number of flushed records
00646 */
00647 
00648 extern int dkim_flush_cache __P((DKIM_LIB *lib));
00649 
00650 /*
00651 **  DKIM_MINBODY -- return number of bytes still expected
00652 **
00653 **  Parameters:
00654 **     dkim -- DKIM handle
00655 **
00656 **  Return value:
00657 **     0 -- all canonicalizations satisfied
00658 **     ULONG_MAX -- at least one canonicalization wants the whole message
00659 **     other -- bytes required to satisfy all canonicalizations
00660 */
00661 
00662 extern u_long dkim_minbody __P((DKIM *dkim));
00663 
00664 /*
00665 **  DKIM_GETSIGLIST -- retrieve the list of signatures
00666 **
00667 **  Parameters:
00668 **     dkim -- DKIM handle
00669 **     sigs -- pointer to a vector of DKIM_SIGINFO pointers (updated)
00670 **     nsigs -- pointer to an integer to receive the pointer count (updated)
00671 **
00672 **  Return value:
00673 **     A DKIM_STAT_* constant.
00674 */
00675 
00676 extern DKIM_STAT dkim_getsiglist __P((DKIM *dkim, DKIM_SIGINFO ***sigs,
00677                                       int *nsigs));
00678 
00679 /*
00680 **  DKIM_GETSIGNATURE -- retrieve the "final" signature
00681 **
00682 **  Parameters:
00683 **     dkim -- DKIM handle
00684 **
00685 **  Return value:
00686 **     Pointer to a DKIM_SIGINFO handle which is the one libopendkim will
00687 **     use to return a "final" result; NULL if none could be determined.
00688 */
00689 
00690 extern DKIM_SIGINFO *dkim_getsignature __P((DKIM *dkim));
00691 
00692 /*
00693 **  DKIM_GETSIGHDR -- compute and return a signature header for a message
00694 **
00695 **  Parameters:
00696 **     dkim -- a DKIM handle previously returned by dkim_sign()
00697 **     buf -- buffer into which to write the signature
00698 **     len -- number of bytes available at "buf"
00699 **     initial -- width of the first line
00700 **
00701 **  Return value:
00702 **     A DKIM_STAT value.
00703 */
00704 
00705 extern DKIM_STAT dkim_getsighdr __P((DKIM *dkim, u_char *buf, size_t len,
00706                                      size_t initial));
00707 
00708 /*
00709 **  DKIM_GETSIGHDR_D -- compute and return a signature header for a message,
00710 **                      but do it dynamically
00711 **
00712 **  Parameters:
00713 **     dkim -- a DKIM handle previously returned by dkim_sign()
00714 **     initial -- width of the first line
00715 **     buf -- location of generated header (returned)
00716 **     len -- number of bytes available at "buf" (returned)
00717 **
00718 **  Return value:
00719 **     A DKIM_STAT value.
00720 */
00721 
00722 extern DKIM_STAT dkim_getsighdr_d __P((DKIM *dkim, size_t initial,
00723                                        u_char **buf, size_t *len));
00724 
00725 /*
00726 **  DKIM_SIG_HDRSIGNED -- retrieve the header list from a signature
00727 **
00728 **  Parameters:
00729 **     sig -- DKIM_SIGINFO handle
00730 **     hdr -- header name to find
00731 **
00732 **  Return value:
00733 **     TRUE iff "sig" had a header list in it and the header "hdr"
00734 **     appeared in that list.
00735 */
00736 
00737 extern _Bool dkim_sig_hdrsigned __P((DKIM_SIGINFO *sig, u_char *hdr));
00738 
00739 /*
00740 **  DKIM_SIG_GETQUERIES -- retrieve the queries needed to validate a signature
00741 **
00742 **  Parameters:
00743 **     dkim -- DKIM handle
00744 **     sig -- DKIM_SIGINFO handle
00745 **     qi -- DKIM_QUERYINFO handle array (returned)
00746 **     nqi -- number of entries in the "qi" array
00747 **
00748 **  Return value:
00749 **     A DKIM_STAT_* constant.
00750 */
00751 
00752 extern DKIM_STAT dkim_sig_getqueries __P((DKIM *dkim, DKIM_SIGINFO *sig,
00753                                           DKIM_QUERYINFO ***qi,
00754                                           unsigned int *nqi));
00755 
00756 /*
00757 **  DKIM_SIG_GETDNSSEC -- retrieve DNSSEC results for a signature
00758 **
00759 **  Parameters:
00760 **     sig -- DKIM_SIGINFO handle
00761 **
00762 **  Return value:
00763 **     A DKIM_DNSSEC_* constant.
00764 */
00765 
00766 extern int dkim_sig_getdnssec __P((DKIM_SIGINFO *sig));
00767 
00768 /*
00769 **  DKIM_SIG_GETREPORTINFO -- retrieve reporting information from a key
00770 **
00771 **  Parameters:
00772 **     dkim -- DKIM handle
00773 **     sig -- DKIM_SIGINFO handle
00774 **     hfd -- canonicalized header descriptor (or NULL) (returned)
00775 **     bfd -- canonicalized body descriptor (or NULL) (returned)
00776 **     addr -- address buffer (or NULL)
00777 **     addrlen -- size of addr
00778 **     opts -- options buffer (or NULL)
00779 **     optslen -- size of opts
00780 **     smtp -- SMTP prefix buffer (or NULL)
00781 **     smtplen -- size of smtp
00782 **     interval -- requested report interval (or NULL)
00783 **
00784 **  Return value:
00785 **     A DKIM_STAT_* constant.
00786 */
00787 
00788 extern DKIM_STAT dkim_sig_getreportinfo __P((DKIM *dkim, DKIM_SIGINFO *sig,
00789                                              int *hfd, int *bfd,
00790                                              u_char *addr, size_t addrlen,
00791                                              u_char *opts, size_t optslen,
00792                                              u_char *smtp, size_t smtplen,
00793                                              u_int *interval));
00794 
00795 /*
00796 **  DKIM_SIG_GETIDENTITY -- retrieve identity of the signer
00797 **
00798 **  Parameters:
00799 **     dkim -- DKIM handle
00800 **     sig -- DKIM_SIGINFO handle (or NULL to choose final one)
00801 **     val -- destination buffer
00802 **     vallen -- size of destination buffer
00803 **
00804 **  Return value:
00805 **     A DKIM_STAT_* constant.
00806 */
00807 
00808 extern DKIM_STAT dkim_sig_getidentity __P((DKIM *dkim, DKIM_SIGINFO *sig,
00809                                            u_char *val, size_t vallen));
00810 
00811 /*
00812 **  DKIM_SIG_GETCANONLEN -- report number of (canonicalized) body bytes that
00813 **                          were signed
00814 **
00815 **  Parameters:
00816 **     dkim -- a DKIM handle previously returned by dkim_sign() or
00817 **             dkim_verify()
00818 **     sig -- a DKIM_SIGINFO handle
00819 **     msglen -- total size of the message body (returned)
00820 **     canonlen -- total number of canonicalized bytes (returned)
00821 **     signlen -- restricted signature length (returned)
00822 **
00823 **  Return value:
00824 **     A DKIM_STAT value.
00825 **
00826 **  Notes:
00827 **     msglen or canonlen can be NULL if that information is not of interest
00828 **     to the caller.
00829 */
00830 
00831 extern DKIM_STAT dkim_sig_getcanonlen __P((DKIM *dkim, DKIM_SIGINFO *sig,
00832                                            ssize_t *msglen, ssize_t *canonlen,
00833                                            ssize_t *signlen));
00834 
00835 /*
00836 **  DKIM_OPTIONS -- set/get options
00837 **
00838 **  Parameters:
00839 **     dkimlib -- DKIM library handle
00840 **     op -- operation (DKIM_OP_GET or DKIM_OP_SET)
00841 **     opt -- which option (a DKIM_OPTS_* constant)
00842 **     ptr -- value (in or out)
00843 **     len -- bytes available at "ptr"
00844 **
00845 **  Return value:
00846 **     A DKIM_STAT value.
00847 */
00848 
00849 extern DKIM_STAT dkim_options __P((DKIM_LIB *dkimlib, int op, dkim_opts_t opt,
00850                                    void *ptr, size_t len));
00851 
00852 /*
00853 **  DKIM_SIG_GETFLAGS -- retreive signature handle flags
00854 **
00855 **  Parameters:
00856 **     sig -- DKIM_SIGINFO handle
00857 **
00858 **  Return value:
00859 **     An unsigned integer which is a bitwise-OR of the DKIM_SIGFLAG_*
00860 **     constants currently set in the provided handle.
00861 */
00862 
00863 extern unsigned int dkim_sig_getflags __P((DKIM_SIGINFO *sig));
00864 
00865 /*
00866 **  DKIM_SIG_GETBH -- retreive signature handle "bh" test state
00867 **
00868 **  Parameters:
00869 **     sig -- DKIM_SIGINFO handle
00870 **
00871 **  Return value:
00872 **     An integer that is one of the DKIM_SIGBH_* constants
00873 **     indicating the current state of "bh" evaluation of the signature.
00874 */
00875 
00876 extern int dkim_sig_getbh __P((DKIM_SIGINFO *sig));
00877 
00878 /*
00879 **  DKIM_SIG_GETKEYSIZE -- retreive key size after verifying
00880 **
00881 **  Parameters:
00882 **     sig -- DKIM_SIGINFO handle
00883 **     bits -- size of the key in bits (returned)
00884 **
00885 **  Return value:
00886 **     A DKIM_STAT value.
00887 */
00888 
00889 extern DKIM_STAT dkim_sig_getkeysize __P((DKIM_SIGINFO *sig,
00890                                           unsigned int *bits));
00891 
00892 /*
00893 **  DKIM_SIG_GETSIGNALG -- retreive signature algorithm after verifying
00894 **
00895 **  Parameters:
00896 **     sig -- DKIM_SIGINFO handle
00897 **     alg -- a DKIM_SIGN_* value (returned)
00898 **
00899 **  Return value:
00900 **     A DKIM_STAT value.
00901 */
00902 
00903 extern DKIM_STAT dkim_sig_getsignalg __P((DKIM_SIGINFO *sig, dkim_alg_t *alg));
00904 
00905 /*
00906 **  DKIM_SIG_GETSIGNTIME -- retreive signature timestamp after verifying
00907 **
00908 **  Parameters:
00909 **     sig -- DKIM_SIGINFO handle
00910 **     when -- timestamp on the signature (returned)
00911 **
00912 **  Return value:
00913 **     A DKIM_STAT value.
00914 */
00915 
00916 extern DKIM_STAT dkim_sig_getsigntime __P((DKIM_SIGINFO *sig, uint64_t *when));
00917 
00918 /*
00919 **  DKIM_SIG_GETSELECTOR -- retrieve selector used to generate the signature
00920 **
00921 **  Parameters:
00922 **     sig -- DKIM_SIGINFO handle from which to retrieve selector
00923 **
00924 **  Return value:
00925 **     Selector found in the signature.
00926 */
00927 
00928 extern unsigned char *dkim_sig_getselector __P((DKIM_SIGINFO *sig));
00929 
00930 /*
00931 **  DKIM_SIG_GETDOMAIN -- retrieve signing domain after verifying
00932 **
00933 **  Parameters:
00934 **     sig -- DKIM_SIGINFO handle
00935 **
00936 **  Return value:
00937 **     Pointer to the signing domain.
00938 */
00939 
00940 extern unsigned char *dkim_sig_getdomain __P((DKIM_SIGINFO *sig));
00941 
00942 /*
00943 **  DKIM_SIG_GETCANONS -- retrieve canonicaliztions after verifying
00944 **
00945 **  Parameters:
00946 **     sig -- DKIM_SIGINFO handle
00947 **
00948 **  Return value:
00949 **     DKIM_STAT_OK -- success
00950 */
00951 
00952 extern DKIM_STAT dkim_sig_getcanons __P((DKIM_SIGINFO *sig, dkim_canon_t *hdr,
00953                                          dkim_canon_t *body));
00954 
00955 /*
00956 **  DKIM_SET_USER_CONTEXT -- set DKIM handle user context
00957 **
00958 **  Parameters:
00959 **     dkim -- DKIM signing handle
00960 **     ctx -- user context pointer to store
00961 **
00962 **  Parameters:
00963 **     A DKIM_STAT_* constant.
00964 */
00965 
00966 extern DKIM_STAT dkim_set_user_context __P((DKIM *dkim, void *ctx));
00967 
00968 /*
00969 **  DKIM_GET_USER_CONTEXT -- retrieve DKIM handle user context
00970 **
00971 **  Parameters:
00972 **     dkim -- DKIM signing handle
00973 **
00974 **  Parameters:
00975 **     User context pointer.
00976 */
00977 
00978 extern void *dkim_get_user_context __P((DKIM *dkim));
00979 
00980 /*
00981 **  DKIM_GETMODE -- return the mode (signing, verifying, etc.) of a handle
00982 **
00983 **  Parameters:
00984 **     dkim -- DKIM handle
00985 **
00986 **  Return value:
00987 **     A DKIM_MODE_* constant.
00988 */
00989 
00990 extern int dkim_getmode __P((DKIM *dkim));
00991 
00992 /*
00993 **  DKIM_GETDOMAIN -- retrieve policy domain from a DKIM context
00994 **
00995 **  Parameters:
00996 **     dkim -- DKIM handle
00997 **
00998 **  Return value:           
00999 **     Pointer to the domain used for policy checking (if any) or NULL if
01000 **     no domain could be determined.
01001 */
01002 
01003 extern u_char *dkim_getdomain __P((DKIM *dkim));
01004 
01005 /*
01006 **  DKIM_GETUSER -- retrieve sending user (local-part) from a DKIM context
01007 **
01008 **  Parameters:
01009 **     dkim -- DKIM handle
01010 **
01011 **  Return value:
01012 **     Pointer to the apparent sending user (local-part) or NULL if not known.
01013 */
01014 
01015 extern u_char *dkim_getuser __P((DKIM *dkim));
01016 
01017 /*
01018 **  DKIM_GET_SIGNER -- get DKIM signature's signer
01019 **
01020 **  Parameters:
01021 **     dkim -- DKIM signing handle
01022 **
01023 **  Parameters:
01024 **     Pointer to a buffer containing the signer previously requested,
01025 **     or NULL if none.
01026 */
01027 
01028 extern const unsigned char *dkim_get_signer __P((DKIM *dkim));
01029 
01030 /*
01031 **  DKIM_SET_SIGNER -- set DKIM signature's signer
01032 **
01033 **  Parameters:
01034 **     dkim -- DKIM signing handle
01035 **     signer -- signer to store
01036 **
01037 **  Parameters:
01038 **     A DKIM_STAT_* constant.
01039 */
01040 
01041 extern DKIM_STAT dkim_set_signer __P((DKIM *dkim, const u_char *signer));
01042 
01043 /*
01044 **  DKIM_SET_DNS_CALLBACK -- set the DNS wait callback
01045 **
01046 **  Parameters:
01047 **     libopendkim -- DKIM library handle
01048 **     func -- function to call; should take an opaque context pointer
01049 **     interval -- how often to call back
01050 **
01051 **  Return value:
01052 **     DKIM_STAT_OK -- success
01053 **     DKIM_STAT_INVALID -- invalid use
01054 **     DKIM_STAT_NOTIMPLEMENT -- underlying resolver doesn't support callbacks
01055 */
01056 
01057 extern DKIM_STAT dkim_set_dns_callback __P((DKIM_LIB *libopendkim,
01058                                             void (*func)(const void *context),
01059                                             unsigned int interval));
01060 
01061 /*
01062 **  DKIM_SET_KEY_LOOKUP -- set the key lookup function
01063 **
01064 **  Parameters:
01065 **     libopendkim -- DKIM library handle
01066 **     func -- function to call
01067 **
01068 **  Return value:
01069 **     DKIM_STAT_OK
01070 */
01071 
01072 extern DKIM_STAT dkim_set_key_lookup __P((DKIM_LIB *libopendkim,
01073                                           DKIM_CBSTAT (*func)(DKIM *dkim,
01074                                                               DKIM_SIGINFO *sig,
01075                                                               u_char *buf,
01076                                                               size_t buflen)));
01077 
01078 /*
01079 **  DKIM_SET_POLICY_LOOKUP -- set the policy lookup function
01080 **
01081 **  Parameters:
01082 **     libopendkim -- DKIM library handle
01083 **     func -- function to call
01084 **
01085 **  Return value:
01086 **     DKIM_STAT_OK
01087 */
01088 
01089 extern DKIM_STAT dkim_set_policy_lookup __P((DKIM_LIB *libopendkim,
01090                                              DKIM_CBSTAT (*func)(DKIM *dkim,
01091                                                                  u_char *query,
01092                                                                  _Bool excheck,
01093                                                                  u_char *buf,
01094                                                                  size_t buflen,
01095                                                                  int *qstat)));
01096 
01097 /*
01098 **  DKIM_SET_SIGNATURE_HANDLE -- set the signature handle creator function
01099 **
01100 **  Parameters:
01101 **     libopendkim -- DKIM library handle
01102 **     func -- function to call
01103 **
01104 **  Return value:
01105 **     Pointer to the user-side handle thus created, or NULL.
01106 */
01107 
01108 extern DKIM_STAT dkim_set_signature_handle __P((DKIM_LIB *libopendkim,
01109                                                 void * (*func)(void *closure)));
01110 
01111 /*
01112 **  DKIM_SET_SIGNATURE_HANDLE_FREE -- set the signature handle destroyer
01113 **                                    function
01114 **
01115 **  Parameters:
01116 **     libopendkim -- DKIM library handle
01117 **     func -- function to call
01118 **
01119 **  Return value:
01120 **     None.
01121 */
01122 
01123 extern DKIM_STAT dkim_set_signature_handle_free __P((DKIM_LIB *libopendkim,
01124                                                      void (*func)(void *closure,
01125                                                                   void *user)));
01126 
01127 /*
01128 **  DKIM_SET_SIGNATURE_TAGVALUES -- set the signature handle populator function
01129 **
01130 **  Parameters:
01131 **     libopendkim -- DKIM library handle
01132 **     func -- function to call
01133 **
01134 **  Return value:
01135 **     DKIM_STAT_OK
01136 */
01137 
01138 extern DKIM_STAT dkim_set_signature_tagvalues __P((DKIM_LIB *libopendkim,
01139                                                    void (*func)(void *user,
01140                                                                 dkim_param_t pcode,
01141                                                                 const u_char *param,
01142                                                                 const u_char *value)));
01143 
01144 /*
01145 **  DKIM_SET_PRESCREEN -- set the prescreen function
01146 **
01147 **  Parameters:
01148 **     libopendkim -- DKIM library handle
01149 **     func -- function to call
01150 **
01151 **  Return value:
01152 **     DKIM_STAT_OK
01153 */
01154 
01155 extern DKIM_STAT dkim_set_prescreen __P((DKIM_LIB *libopendkim,
01156                                          DKIM_CBSTAT (*func)(DKIM *dkim,
01157                                                              DKIM_SIGINFO **sigs,
01158                                                              int nsigs)));
01159 
01160 /*
01161 **  DKIM_SET_FINAL -- set the final processing function
01162 **
01163 **  Parameters:
01164 **     libopendkim -- DKIM library handle
01165 **     func -- function to call
01166 **
01167 **  Return value:
01168 **     DKIM_STAT_OK
01169 */
01170 
01171 extern DKIM_STAT dkim_set_final __P((DKIM_LIB *libopendkim,
01172                                      DKIM_CBSTAT (*func)(DKIM *dkim,
01173                                                          DKIM_SIGINFO **sigs,
01174                                                          int nsigs)));
01175 
01176 /*
01177 **  DKIM_SIG_GETCONTEXT -- get user-specific context from a DKIM_SIGINFO
01178 **
01179 **  Parameters:
01180 **     siginfo -- a pointer to a DKIM_SIGINFO
01181 **
01182 **  Return value:
01183 **     The user-provided pointer stored in the named "siginfo", or NULL
01184 **     if none was ever set.
01185 */
01186 
01187 extern void *dkim_sig_getcontext __P((DKIM_SIGINFO *siginfo));
01188 
01189 /*
01190 **  DKIM_SIG_GETERROR -- get error code from a DKIM_SIGINFO
01191 **
01192 **  Parameters:
01193 **     siginfo -- a pointer to a DKIM_SIGINFO
01194 **
01195 **  Return value:
01196 **     A DKIM_SIGERROR_* constant.
01197 */
01198 
01199 extern int dkim_sig_geterror __P((DKIM_SIGINFO *siginfo));
01200 
01201 /*
01202 **  DKIM_SIG_GETERRORSTR -- translate a DKIM_SIGERROR into a string
01203 **
01204 **  Parameters:
01205 **     sigerr -- a DKIM_SIGERROR constant
01206 **
01207 **  Return value:
01208 **     A pointer to a human-readable string translation of "sigerr", or NULL
01209 **     if no such translation exists.
01210 */
01211 
01212 extern const char *dkim_sig_geterrorstr __P((DKIM_SIGERROR sigerr));
01213 
01214 /*
01215 **  DKIM_SIG_IGNORE -- mark a signature referenced by a DKIM_SIGINFO with
01216 **                     an "ignore" flag
01217 **
01218 **  Parameters:
01219 **     siginfo -- pointer to a DKIM_SIGINFO to update
01220 **
01221 **  Return value:
01222 **     None.
01223 */
01224 
01225 extern void dkim_sig_ignore __P((DKIM_SIGINFO *siginfo));
01226 
01227 /*
01228 **  DKIM_POLICY_GETQUERIES -- retrieve the queries needed to conduct an ADSP
01229 **                            evaluation
01230 **
01231 **  Parameters:
01232 **     dkim -- DKIM handle
01233 **     qi -- DKIM_QUERYINFO handle array (returned)
01234 **     nqi -- number of entries in the "qi" array
01235 **
01236 **  Return value:
01237 **     A DKIM_STAT_* constant.
01238 */
01239 
01240 extern DKIM_STAT dkim_policy_getqueries __P((DKIM *dkim,
01241                                              DKIM_QUERYINFO ***qi,
01242                                              unsigned int *nqi));
01243 
01244 /*
01245 **  DKIM_POLICY_STATE_NEW -- initialize and return a DKIM policy state handle
01246 **
01247 **  Parameters:
01248 **     dkim -- DKIM handle from which to do an allocation
01249 **
01250 **  Return value:
01251 **     A DKIM_PSTATE handle, or NULL on failure.
01252 */
01253 
01254 extern DKIM_PSTATE *dkim_policy_state_new __P((DKIM *dkim));
01255 
01256 /*
01257 **  DKIM_POLICY_STATE_FREE -- destroy a DKIM policy state handle
01258 **
01259 **  Parameters:
01260 **     pstate -- previously allocated policy state handle
01261 **
01262 **  Return value:
01263 **     None.
01264 */
01265 
01266 extern void dkim_policy_state_free __P((DKIM_PSTATE *pstate));
01267 
01268 /*
01269 **  DKIM_POLICY -- parse policy associated with the sender's domain
01270 **
01271 **  Parameters:
01272 **     dkim -- DKIM handle
01273 **     pcode -- discovered policy (returned)
01274 **     pflags -- discovered policy flags (returned)
01275 **     pstate -- state, for re-entrancy (updated; can be NULL)
01276 **
01277 **  Return value:
01278 **     A DKIM_STAT_* constant.
01279 */
01280 
01281 extern DKIM_STAT dkim_policy __P((DKIM *dkim, dkim_policy_t *pcode,
01282                                   u_int *pflags, DKIM_PSTATE *pstate));
01283 
01284 /*
01285 **  DKIM_POLICY_GETDNSSEC -- retrieve DNSSEC results for a policy
01286 **
01287 **  Parameters:
01288 **     dkim -- DKIM handle
01289 **
01290 **  Return value:
01291 **     A DKIM_DNSSEC_* constant.
01292 */
01293 
01294 extern int dkim_policy_getdnssec __P((DKIM *dkim));
01295 
01296 /*
01297 **  DKIM_POLICY_GETREPORTINFO -- retrieve reporting information from policy
01298 **
01299 **  Parameters:
01300 **     dkim -- DKIM handle
01301 **     addr -- address buffer (or NULL)
01302 **     addrlen -- size of addr
01303 **     opts -- options buffer (or NULL)
01304 **     optslen -- size of opts
01305 **     smtp -- SMTP prefix buffer (or NULL)
01306 **     smtplen -- size of smtp
01307 **     interval -- requested report interval (or NULL)
01308 **
01309 **  Return value:
01310 **     A DKIM_STAT_* constant.
01311 */
01312 
01313 extern DKIM_STAT dkim_policy_getreportinfo __P((DKIM *dkim,
01314                                                 u_char *addr, size_t addrlen,
01315                                                 u_char *opts, size_t optslen,
01316                                                 u_char *smtp, size_t smtplen,
01317                                                 u_int *interval));
01318 
01319 /*
01320 **  DKIM_SIG_PROCESS -- process a signature
01321 **
01322 **  Parameters:
01323 **     dkim -- DKIM handle
01324 **     sig -- DKIM_SIGINFO handle
01325 **
01326 **  Return value:
01327 **     A DKIM_STAT_* constant.
01328 */
01329 
01330 extern DKIM_STAT dkim_sig_process __P((DKIM *dkim, DKIM_SIGINFO *sig));
01331 
01332 /*
01333 **  DKIM_FREE -- release resources associated with a DKIM handle
01334 **
01335 **  Parameters:
01336 **     dkim -- a DKIM handle previously returned by dkim_sign() or
01337 **             dkim_verify()
01338 **
01339 **  Return value:
01340 **     A DKIM_STAT value.
01341 */
01342 
01343 extern DKIM_STAT dkim_free __P((DKIM *dkim));
01344 
01345 /*
01346 **  DKIM_GETERROR -- return any stored error string from within the DKIM
01347 **                   context handle
01348 **
01349 **  Parameters:
01350 **     dkim -- DKIM handle from which to retrieve an error string
01351 **
01352 **  Return value:
01353 **     A pointer to the stored string, or NULL if none was stored.
01354 */
01355 
01356 extern const char *dkim_geterror __P((DKIM *dkim));
01357 
01358 /*
01359 **  DKIM_GETRESULTSTR -- translate a DKIM_STAT_* constant to a string
01360 **
01361 **  Parameters:
01362 **      result -- DKIM_STAT_* constant to translate
01363 **
01364 **  Return value:
01365 **      Pointer to a text describing "result", or NULL if none exists
01366 */
01367 
01368 extern const char *dkim_getresultstr __P((DKIM_STAT result));
01369 
01370 /*
01371 **  DKIM_GETPRESULT -- retrieve policy result
01372 **
01373 **  Parameters:
01374 **     dkim -- DKIM handle from which to get policy result
01375 **
01376 **  Return value:
01377 **     DKIM policy check result.
01378 */
01379 
01380 extern int dkim_getpresult __P((DKIM *dkim));
01381 
01382 /*
01383 **  DKIM_GETPRESULTSTR -- retrieve policy result string
01384 **
01385 **  Parameters:
01386 **     presult -- policy result code to translate
01387 **
01388 **  Return value:
01389 **     Pointer to text that describes "presult".
01390 */
01391 
01392 extern const char *dkim_getpresultstr __P((int presult));
01393 
01394 /*
01395 **  DKIM_GETPOLICYSTR -- retrieve sender policy string
01396 **
01397 **  Parameters:
01398 **     policy -- policy code to translate
01399 **
01400 **  Return value:
01401 **     Pointer to text that describes "policy".
01402 */
01403 
01404 extern const char *dkim_getpolicystr __P((int policy));
01405 
01406 /*
01407 **  DKIM_OHDRS -- extract and decode original headers
01408 **
01409 **  Parameters:
01410 **     dkim -- DKIM handle
01411 **     sig -- DKIM_SIGINFO handle
01412 **     ptrs -- user-provided array of pointers to header strings (updated)
01413 **     pcnt -- number of pointers available (updated)
01414 **
01415 **  Return value:
01416 **     A DKIM_STAT_* constant.
01417 */
01418 
01419 extern DKIM_STAT dkim_ohdrs __P((DKIM *dkim, DKIM_SIGINFO *sig, u_char **ptrs,
01420                                  int *pcnt));
01421 
01422 /*
01423 **  DKIM_DIFFHEADERS -- compare original headers with received headers
01424 **
01425 **  Parameters:
01426 **     dkim -- DKIM handle
01427 **     canon -- canonicalization mode in use
01428 **     maxcost -- maximum "cost" of changes to be reported
01429 **     ohdrs -- original headers, presumably extracted from a "z" tag
01430 **     nohdrs -- number of headers at "ohdrs" available
01431 **     out -- pointer to an array of struct dkim_hdrdiff objects (updated)
01432 **     nout -- counter of handles returned (updated)
01433 **
01434 **  Return value:
01435 **     A DKIM_STAT_* constant.
01436 **
01437 **  Side effects:
01438 **     A series of DKIM_HDRDIFF handles is allocated and must later be
01439 **     destroyed.
01440 */
01441 
01442 extern DKIM_STAT dkim_diffheaders __P((DKIM *dkim, dkim_canon_t canon,
01443                                        int maxcost,
01444                                        char **ohdrs, int nohdrs,
01445                                        struct dkim_hdrdiff **out, int *nout));
01446 
01447 /*
01448 **  DKIM_GETPARTIAL -- return a DKIM handle's "body length tag" flag
01449 **
01450 **  Parameters:
01451 **     dkim -- DKIM handle
01452 **
01453 **  Return value:
01454 **     True iff the signature is to include a body length tag
01455 */
01456 
01457 extern _Bool dkim_getpartial __P((DKIM *dkim));
01458 
01459 /*
01460 **  DKIM_SETPARTIAL -- set the DKIM handle to sign using the DKIM body length
01461 **                     tag (l=)
01462 **
01463 **  Parameters:
01464 **     dkim -- DKIM handle
01465 **     value -- new flag value
01466 **
01467 **  Return value:
01468 **     DKIM_STAT_OK
01469 */
01470 
01471 extern DKIM_STAT dkim_setpartial __P((DKIM *dkim, _Bool value));
01472 
01473 /*
01474 **  DKIM_SET_MARGIN -- set the margin to use when generating signatures
01475 **
01476 **  Parameters:
01477 **      dkim -- DKIM handle
01478 **      value -- new margin value
01479 **
01480 **  Return value:
01481 **      DKIM_STAT_INVALID -- "dkim" referenced a verification handle, or
01482 **                          "value" was negative
01483 **      DKIM_STAT_OK -- otherwise
01484 */
01485 
01486 extern DKIM_STAT dkim_set_margin __P((DKIM *dkim, int value));
01487 
01488 /*
01489 **  DKIM_GET_REPUTATION -- query reputation service about a signature
01490 **                         (OBSOLETE; moved to libdkimrep)
01491 **
01492 **  Parameters:
01493 **     dkim -- DKIM handle
01494 **     sig -- DKIM_SIGINFO handle
01495 **     qroot -- query root
01496 **     rep -- integer reputation (returned)
01497 **
01498 **  Return value:
01499 **     DKIM_STAT_NOTIMPLEMENT -- not implemented
01500 */
01501 
01502 extern DKIM_STAT dkim_get_reputation __P((DKIM *dkim, DKIM_SIGINFO *sig,
01503                                           char *qroot, int *rep));
01504 
01505 /*
01506 **  DKIM_MAIL_PARSE -- extract the local-part and domain-name from a structured
01507 **                     header field
01508 **
01509 **  Parameters:
01510 **     addr -- the header to parse; see RFC2822 for format
01511 **     user -- local-part of the parsed header (returned)
01512 **     domain -- domain part of the parsed header (returned)
01513 **
01514 **  Return value:
01515 **     0 on success; other on error (see source)
01516 */
01517 
01518 extern int dkim_mail_parse __P((u_char *addr, u_char **user, u_char **domain));
01519 
01520 /*
01521 **  DKIM_SSL_VERSION -- return the version of the OpenSSL library against
01522 **                      which this library was compiled
01523 **
01524 **  Parameters:
01525 **     None.
01526 **
01527 **  Return value:
01528 **     The OPENSSL_VERSION_NUMBER constant as defined by OpenSSL.
01529 */
01530 
01531 extern unsigned long dkim_ssl_version __P((void));
01532 
01533 /*
01534 **  DKIM_LIBFEATURE -- check for a library feature
01535 **
01536 **  Parameters:
01537 **     lib -- DKIM_LIB handle
01538 **     fc -- feature code
01539 **
01540 **  Return value:
01541 **     TRUE iff the library was compiled with the requested feature
01542 */
01543 
01544 #define DKIM_FEATURE_DIFFHEADERS   0
01545 #define DKIM_FEATURE_DKIM_REPUTATION      1
01546 #define DKIM_FEATURE_PARSE_TIME           2
01547 #define DKIM_FEATURE_QUERY_CACHE   3
01548 #define DKIM_FEATURE_SHA256        4
01549 #define DKIM_FEATURE_OVERSIGN             5
01550 #define DKIM_FEATURE_DNSSEC        6
01551 #define DKIM_FEATURE_RESIGN        7
01552 #define DKIM_FEATURE_ATPS          8
01553 #define DKIM_FEATURE_XTAGS         9
01554 
01555 #define       DKIM_FEATURE_MAX            9
01556 
01557 extern _Bool dkim_libfeature __P((DKIM_LIB *lib, u_int fc));
01558 
01559 
01560 /*
01561 **  DKIM_LIBVERSION -- return version of libopendkim at runtime
01562 **
01563 **  Parameters:
01564 **     None.
01565 **
01566 **  Return value:
01567 **     Library version, i.e. value of the OPENDKIM_LIB_VERSION macro.
01568 */
01569 
01570 extern uint32_t dkim_libversion __P((void));
01571 
01572 /*
01573 **  DKIM_GET_SIGSUBSTRING -- retrieve a minimal signature substring for
01574 **                           disambiguation
01575 **
01576 **  Parameters:
01577 **     dkim -- DKIM handle
01578 **     sig -- DKIM_SIGINFO handle
01579 **     buf -- buffer into which to put the substring
01580 **     buflen -- bytes available at "buf"
01581 **
01582 **  Return value:
01583 **     A DKIM_STAT_* constant.
01584 */
01585 
01586 extern DKIM_STAT dkim_get_sigsubstring __P((DKIM *, DKIM_SIGINFO *,
01587                                             char *, size_t *));
01588 
01589 /*
01590 **  DKIM_TEST_ADSP -- verify that a valid author domain signing policy exists
01591 **                    in DNS
01592 **
01593 **  Parameters:
01594 **     lib -- DKIM library handle
01595 **     domain -- domain name
01596 **     presult -- policy discovered (returned)
01597 **     presult2 -- policy stage at which result was decided (returned)
01598 **     err -- error buffer
01599 **     errlen -- bytes available at "err"
01600 **
01601 **  Return value:
01602 **     0 -- some kind of result was made available
01603 **     -1 -- error
01604 */
01605 
01606 extern int dkim_test_adsp __P((DKIM_LIB *, const char *, dkim_policy_t *,
01607                                int *, char *, size_t));
01608 
01609 /*
01610 **  DKIM_TEST_KEY -- retrieve a public key and verify it against a provided
01611 **                   private key
01612 **
01613 **  Parameters:
01614 **     lib -- DKIM library handle
01615 **     selector -- selector
01616 **     domain -- domain name
01617 **     key -- private key to verify (PEM format)
01618 **     keylen -- size of private key
01619 **     dnssec -- DNSSEC result (may be NULL)
01620 **     err -- error buffer (may be NULL)
01621 **     errlen -- size of error buffer
01622 **
01623 **  Return value:
01624 **     1 -- keys don't match
01625 **     0 -- keys match (or no key provided)
01626 **     -1 -- error
01627 */
01628 
01629 extern int dkim_test_key __P((DKIM_LIB *, char *, char *, char *, size_t,
01630                               int *, char *, size_t));
01631 
01632 /*
01633 **  DKIM_SIG_GETTAGVALUE -- retrieve a tag's value from a signature or its key
01634 **
01635 **  Parameters:
01636 **     sig -- DKIM_SIGINFO handle
01637 **     keytag -- TRUE iff we want a key's tag
01638 **     tag -- name of the tag of interest
01639 **
01640 **  Return value:
01641 **     Pointer to the string containing the value of the requested key,
01642 **     or NULL if not present.
01643 **
01644 **  Notes:
01645 **     This was added for use in determining whether or not a key or
01646 **     signature contained particular data, for gathering general statistics
01647 **     about DKIM use.  It is not intended to give applications direct access
01648 **     to unprocessed signature or key data.  The data returned has not
01649 **     necessarily been vetted in any way.  Caveat emptor.
01650 */
01651 
01652 extern u_char *dkim_sig_gettagvalue __P((DKIM_SIGINFO *, _Bool, u_char *));
01653 
01654 /*
01655 **  DKIM_SIG_GETSIGNEDHDRS -- retrieve the signed header fields covered by
01656 **                            a signature that passed
01657 **
01658 **  Parameters:
01659 **     dkim -- DKIM instance
01660 **     sig -- signature
01661 **     hdrs -- rectangular array of header field strings
01662 **     hdrlen -- length of each element of "hdrs"
01663 **     nhdrs -- size of "hdrs" array (updated)
01664 **
01665 **  Return value:
01666 **     A DKIM_STAT_* constant.
01667 */
01668 
01669 extern DKIM_STAT dkim_sig_getsignedhdrs __P((DKIM *, DKIM_SIGINFO *,
01670                                              u_char *, size_t, u_int *));
01671 
01672 /*
01673 **  DKIM_STRLCPY -- size-bounded strcpy()
01674 **
01675 **  Parameters:
01676 **     dst -- destination string
01677 **     src -- source string
01678 **     len -- total length of buffer at "dst"
01679 **
01680 **  Return value:
01681 **     Number of bytes needed to complete the copy, including the terminating
01682 **     NULL.  If this is greater than or equal to "len", truncation occurred
01683 **     as this function guarantees "dst" will always be NULL-terminated.
01684 */
01685 
01686 extern size_t dkim_strlcpy __P((char *, const char *, ssize_t));
01687 
01688 /*
01689 **  DKIM_STRLCAT -- size-bounded strcat()
01690 **
01691 **  Parameters:
01692 **     dst -- destination string
01693 **     src -- source string
01694 **     len -- total length of buffer at "dst"
01695 **
01696 **  Return value:
01697 **     Total length of the string the caller tried to create, including
01698 **     leaving a trailng NULL.  If this is greater than or equal to "len",
01699 **     truncation occurred.
01700 */
01701 
01702 extern size_t dkim_strlcat __P((char *, const char *, ssize_t));
01703 
01704 /*
01705 **  DKIM_QP_DECODE -- decode a quoted-printable string
01706 **
01707 **  Parameters:
01708 **     in -- input
01709 **     out -- output
01710 **     outlen -- bytes available at "out"
01711 **
01712 **  Return value:
01713 **     >= 0 -- number of bytes in output
01714 **     -1 -- parse error
01715 */
01716 
01717 extern int dkim_qp_decode __P((unsigned char *, unsigned char *, int));
01718 
01719 /*
01720 **  DKIM_DNS_SET_QUERY_SERVICE -- stores a handle representing the DNS
01721 **                                query service to be used, returning any
01722 **                                previous handle
01723 **
01724 **  Parameters:
01725 **     lib -- DKIM library handle
01726 **     h -- handle to be used
01727 **
01728 **  Return value:
01729 **     Previously stored handle, or NULL if none.
01730 */
01731 
01732 extern void *dkim_dns_set_query_service __P((DKIM_LIB *, void *));
01733 
01734 /*
01735 **  DKIM_DNS_SET_QUERY_START -- stores a pointer to a query start function
01736 **
01737 **  Parameters:
01738 **     lib -- DKIM library handle
01739 **     func -- function to use to start queries
01740 **
01741 **  Return value:
01742 **     None.
01743 **
01744 **  Notes:
01745 **     "func" should match the following prototype:
01746 **            returns int (status)
01747 **            void *dns -- receives handle stored by
01748 **                         dkim_dns_set_query_service()
01749 **            int type -- DNS RR query type (C_IN assumed)
01750 **            char *query -- question to ask
01751 **            char *buf -- buffer into which to write reply
01752 **            size_t buflen -- size of buf
01753 **            void **qh -- returned query handle
01754 */
01755 
01756 extern void dkim_dns_set_query_start __P((DKIM_LIB *,
01757                                           int (*)(void *, int,
01758                                                   unsigned char *,
01759                                                   unsigned char *,
01760                                                   size_t, void **)));
01761 
01762 /*
01763 **  DKIM_DNS_SET_QUERY_CANCEL -- stores a pointer to a query cancel function
01764 **
01765 **  Parameters:
01766 **     lib -- DKIM library handle
01767 **     func -- function to use to cancel running queries
01768 **
01769 **  Return value:
01770 **     None.
01771 **
01772 **  Notes:
01773 **     "func" should match the following prototype:
01774 **            returns int (status)
01775 **            void *dns -- DNS service handle
01776 **            void *qh -- query handle to be canceled
01777 */
01778 
01779 extern void dkim_dns_set_query_cancel __P((DKIM_LIB *,
01780                                            int (*)(void *, void *)));
01781 
01782 /*
01783 **  DKIM_DNS_SET_QUERY_WAITREPLY -- stores a pointer to wait for a DNS reply
01784 **
01785 **  Parameters:
01786 **     lib -- DKIM library handle
01787 **     func -- function to use to wait for a reply
01788 **
01789 **  Return value:
01790 **     None.
01791 **
01792 **  Notes:
01793 **     "func" should match the following prototype:
01794 **            returns int (status)
01795 **            void *dns -- DNS service handle
01796 **            void *qh -- handle of query that has completed
01797 **            struct timeval *timeout -- how long to wait
01798 **            size_t *bytes -- bytes returned
01799 **            int *error -- error code returned
01800 **            int *dnssec -- DNSSEC status returned
01801 */
01802 
01803 extern void dkim_dns_set_query_waitreply __P((DKIM_LIB *,
01804                                               int (*)(void *, void *,
01805                                                       struct timeval *,
01806                                                       size_t *, int *,
01807                                                       int *)));
01808 
01809 /*
01810 **  DKIM_ADD_XTAG -- add an extension tag/value
01811 **
01812 **  Parameters:
01813 **     dkim -- DKIM signing handle to extend
01814 **     tag -- name of tag to add
01815 **     value -- value to include
01816 **
01817 **  Return value:
01818 **     A DKIM_STAT_* constant.
01819 */
01820 
01821 extern DKIM_STAT dkim_add_xtag __P((DKIM *, const char *, const char *));
01822 
01823 /*
01824 **  DKIM_PRIVKEY_LOAD -- explicitly try to load the private key
01825 **
01826 **  Parameters:
01827 **     dkim -- DKIM signing handle
01828 **
01829 **  Return value:
01830 **     A DKIM_STAT_* constant.
01831 */
01832 
01833 extern DKIM_STAT dkim_privkey_load __P((DKIM *));
01834 
01835 /*
01836 **  DKIM_ATPS_CHECK -- check for Authorized Third Party Signing
01837 **
01838 **  Parameters:
01839 **     dkim -- DKIM message handle
01840 **     sig -- signature information handle
01841 **     timeout -- timeout (can be NULL)
01842 **     res -- ATPS result code
01843 **
01844 **  Return value:
01845 **     A DKIM_STAT_* constant.
01846 */
01847 
01848 extern DKIM_STAT dkim_atps_check __P((DKIM *, DKIM_SIGINFO *,
01849                                       struct timeval *, dkim_atps_t *res));
01850 
01851 /*
01852 **  DKIM_QI_GETNAME -- retrieve the DNS name from a DKIM_QUERYINFO object
01853 **
01854 **  Parameters:
01855 **     query -- DKIM_QUERYINFO handle
01856 **
01857 **  Return value:
01858 **     A pointer to a NULL-terminated string indicating the name to be
01859 **     queried, or NULL on error.
01860 */
01861 
01862 extern const char *dkim_qi_getname __P((DKIM_QUERYINFO *));
01863 
01864 /*
01865 **  DKIM_QI_GETTYPE -- retrieve the DNS RR type from a DKIM_QUERYINFO object
01866 **
01867 **  Parameters:
01868 **     query -- DKIM_QUERYINFO handle
01869 **
01870 **  Return value:
01871 **     The DNS RR type to be queried, or -1 on error.
01872 */
01873 
01874 extern int dkim_qi_gettype __P((DKIM_QUERYINFO *));
01875 
01876 /*
01877 **  DKIM_BASE32_ENCODE -- encode a string using base32
01878 **
01879 **  Parameters:
01880 **     buf -- destination buffer
01881 **     buflen -- bytes available at buf (updated)
01882 **     data -- pointer to data to encode
01883 **     size -- bytes at "data" to encode
01884 **
01885 **  Return value:
01886 **     Length of encoding.
01887 **
01888 **  Notes:
01889 **     buf should be at least a byte more than *buflen to hold the trailing
01890 **     '\0'.
01891 **
01892 **     *buflen is updated to count the number of bytes read from "data".
01893 */
01894 
01895 extern int dkim_base32_encode __P((char *, size_t *, const void *, size_t));
01896 
01897 /*
01898 **  DKIM_SIG_GETHASHES -- retrieve hashes
01899 **
01900 **  Parameters:
01901 **     sig -- signature from which to get completed hashes
01902 **     hh -- pointer to header hash buffer (returned)
01903 **     hhlen -- bytes used at hh (returned)
01904 **     bh -- pointer to body hash buffer (returned)
01905 **     bhlen -- bytes used at bh (returned)
01906 **
01907 **  Return value:
01908 **     DKIM_STAT_OK -- successful completion
01909 **     DKIM_STAT_INVALID -- hashing hasn't been completed
01910 */
01911 
01912 extern DKIM_STAT dkim_sig_gethashes __P((DKIM_SIGINFO *, void **, size_t *,
01913                                          void **, size_t *));
01914 
01915 /* default list of sender headers */
01916 extern const u_char *dkim_default_senderhdrs[];
01917 
01918 /* list of headers that should be signed, per RFC6376 Section 5.4 */
01919 extern const u_char *dkim_should_signhdrs[]; 
01920 
01921 /* list of headers that should not be signed, per RFC6376 Section 5.4 */
01922 extern const u_char *dkim_should_not_signhdrs[];
01923 
01924 
01925 #ifdef __cplusplus
01926 }
01927 #endif /* __cplusplus */
01928 
01929 #endif /* ! _DKIM_H_ */