1 /* 2 ** Copyright (c) 2005-2009 Sendmail, Inc. and its suppliers. 3 ** All rights reserved. 4 ** 5 ** Copyright (c) 2009-2015, The Trusted Domain Project. All rights reserved. 6 */ 7 8 #ifndef _DKIM_H_ 9 #define _DKIM_H_ 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif /* __cplusplus */ 14 15 /* system includes */ 16 #include <sys/types.h> 17 #include <sys/param.h> 18 #include <sys/time.h> 19 #ifdef HAVE_STDBOOL_H 20 # include <stdbool.h> 21 #endif /* HAVE_STDBOOL_H */ 22 #include <inttypes.h> 23 #ifdef HAVE_LIMITS_H 24 # include <limits.h> 25 #endif /* HAVE_LIMITS_H */ 26 27 /* 28 ** version -- 0xrrMMmmpp 29 ** 30 ** rr == release number 31 ** MM == major revision number 32 ** mm == minor revision number 33 ** pp == patch number 34 */ 35 36 #define OPENDKIM_LIB_VERSION 0x020a0300 37 38 #ifdef __STDC__ 39 # ifndef __P 40 # define __P(x) x 41 # endif /* ! __P */ 42 #else /* __STDC__ */ 43 # ifndef __P 44 # define __P(x) () 45 # endif /* ! __P */ 46 #endif /* __STDC__ */ 47 48 /* definitions */ 49 #define DKIM_ATPSTAG "atps" /* ATPS tag name */ 50 #define DKIM_ATPSHTAG "atpsh" /* ATPS tag name */ 51 #define DKIM_HDRMARGIN 75 /* "standard" header margin */ 52 #define DKIM_MAXHEADER 4096 /* buffer for caching one header */ 53 #define DKIM_MAXHOSTNAMELEN 256 /* max. FQDN we support */ 54 #define DKIM_REPORTTAG "r" /* DKIM reporting request tag */ 55 #define DKIM_REPORTTAGVAL "y" /* DKIM reporting request tag value */ 56 #define DKIM_SIGNHEADER "DKIM-Signature" 57 /* DKIM signature header */ 58 59 /* special DNS tokens */ 60 #define DKIM_DNSKEYNAME "_domainkey" 61 /* reserved DNS sub-zone */ 62 63 /* macros */ 64 #define DKIM_SIG_CHECK(x) ((dkim_sig_getflags((x)) & DKIM_SIGFLAG_PASSED != 0) && (dkim_sig_getbh((x)) == DKIM_SIGBH_MATCH)) 65 66 /* 67 ** DKIM_STAT -- status code type 68 */ 69 70 typedef int DKIM_STAT; 71 72 #define DKIM_STAT_OK 0 /* function completed successfully */ 73 #define DKIM_STAT_BADSIG 1 /* signature available but failed */ 74 #define DKIM_STAT_NOSIG 2 /* no signature available */ 75 #define DKIM_STAT_NOKEY 3 /* public key not found */ 76 #define DKIM_STAT_CANTVRFY 4 /* can't get domain key to verify */ 77 #define DKIM_STAT_SYNTAX 5 /* message is not valid syntax */ 78 #define DKIM_STAT_NORESOURCE 6 /* resource unavailable */ 79 #define DKIM_STAT_INTERNAL 7 /* internal error */ 80 #define DKIM_STAT_REVOKED 8 /* key found, but revoked */ 81 #define DKIM_STAT_INVALID 9 /* invalid function parameter */ 82 #define DKIM_STAT_NOTIMPLEMENT 10 /* function not implemented */ 83 #define DKIM_STAT_KEYFAIL 11 /* key retrieval failed */ 84 #define DKIM_STAT_CBREJECT 12 /* callback requested reject */ 85 #define DKIM_STAT_CBINVALID 13 /* callback gave invalid result */ 86 #define DKIM_STAT_CBTRYAGAIN 14 /* callback says try again later */ 87 #define DKIM_STAT_CBERROR 15 /* callback error */ 88 #define DKIM_STAT_MULTIDNSREPLY 16 /* multiple DNS replies */ 89 #define DKIM_STAT_SIGGEN 17 /* signature generation failed */ 90 91 /* 92 ** DKIM_CBSTAT -- callback status code type 93 */ 94 95 typedef int DKIM_CBSTAT; 96 97 #define DKIM_CBSTAT_CONTINUE 0 /* continue */ 98 #define DKIM_CBSTAT_REJECT 1 /* reject */ 99 #define DKIM_CBSTAT_TRYAGAIN 2 /* try again later */ 100 #define DKIM_CBSTAT_NOTFOUND 3 /* requested record not found */ 101 #define DKIM_CBSTAT_ERROR 4 /* error requesting record */ 102 #define DKIM_CBSTAT_DEFAULT 5 /* bypass; use default handling */ 103 104 /* 105 ** DKIM_SIGERROR -- signature errors 106 */ 107 108 typedef int DKIM_SIGERROR; 109 110 #define DKIM_SIGERROR_UNKNOWN (-1) /* unknown error */ 111 #define DKIM_SIGERROR_OK 0 /* no error */ 112 #define DKIM_SIGERROR_VERSION 1 /* unsupported version */ 113 #define DKIM_SIGERROR_DOMAIN 2 /* invalid domain (d=/i=) */ 114 #define DKIM_SIGERROR_EXPIRED 3 /* signature expired */ 115 #define DKIM_SIGERROR_FUTURE 4 /* signature in the future */ 116 #define DKIM_SIGERROR_TIMESTAMPS 5 /* x= < t= */ 117 #define DKIM_SIGERROR_UNUSED 6 /* OBSOLETE */ 118 #define DKIM_SIGERROR_INVALID_HC 7 /* c= invalid (header) */ 119 #define DKIM_SIGERROR_INVALID_BC 8 /* c= invalid (body) */ 120 #define DKIM_SIGERROR_MISSING_A 9 /* a= missing */ 121 #define DKIM_SIGERROR_INVALID_A 10 /* a= invalid */ 122 #define DKIM_SIGERROR_MISSING_H 11 /* h= missing */ 123 #define DKIM_SIGERROR_INVALID_L 12 /* l= invalid */ 124 #define DKIM_SIGERROR_INVALID_Q 13 /* q= invalid */ 125 #define DKIM_SIGERROR_INVALID_QO 14 /* q= option invalid */ 126 #define DKIM_SIGERROR_MISSING_D 15 /* d= missing */ 127 #define DKIM_SIGERROR_EMPTY_D 16 /* d= empty */ 128 #define DKIM_SIGERROR_MISSING_S 17 /* s= missing */ 129 #define DKIM_SIGERROR_EMPTY_S 18 /* s= empty */ 130 #define DKIM_SIGERROR_MISSING_B 19 /* b= missing */ 131 #define DKIM_SIGERROR_EMPTY_B 20 /* b= empty */ 132 #define DKIM_SIGERROR_CORRUPT_B 21 /* b= corrupt */ 133 #define DKIM_SIGERROR_NOKEY 22 /* no key found in DNS */ 134 #define DKIM_SIGERROR_DNSSYNTAX 23 /* DNS reply corrupt */ 135 #define DKIM_SIGERROR_KEYFAIL 24 /* DNS query failed */ 136 #define DKIM_SIGERROR_MISSING_BH 25 /* bh= missing */ 137 #define DKIM_SIGERROR_EMPTY_BH 26 /* bh= empty */ 138 #define DKIM_SIGERROR_CORRUPT_BH 27 /* bh= corrupt */ 139 #define DKIM_SIGERROR_BADSIG 28 /* signature mismatch */ 140 #define DKIM_SIGERROR_SUBDOMAIN 29 /* unauthorized subdomain */ 141 #define DKIM_SIGERROR_MULTIREPLY 30 /* multiple records returned */ 142 #define DKIM_SIGERROR_EMPTY_H 31 /* h= empty */ 143 #define DKIM_SIGERROR_INVALID_H 32 /* h= missing req'd entries */ 144 #define DKIM_SIGERROR_TOOLARGE_L 33 /* l= value exceeds body size */ 145 #define DKIM_SIGERROR_MBSFAILED 34 /* "must be signed" failure */ 146 #define DKIM_SIGERROR_KEYVERSION 35 /* unknown key version */ 147 #define DKIM_SIGERROR_KEYUNKNOWNHASH 36 /* unknown key hash */ 148 #define DKIM_SIGERROR_KEYHASHMISMATCH 37 /* sig-key hash mismatch */ 149 #define DKIM_SIGERROR_NOTEMAILKEY 38 /* not an e-mail key */ 150 #define DKIM_SIGERROR_UNUSED2 39 /* OBSOLETE */ 151 #define DKIM_SIGERROR_KEYTYPEMISSING 40 /* key type missing */ 152 #define DKIM_SIGERROR_KEYTYPEUNKNOWN 41 /* key type unknown */ 153 #define DKIM_SIGERROR_KEYREVOKED 42 /* key revoked */ 154 #define DKIM_SIGERROR_KEYDECODE 43 /* key couldn't be decoded */ 155 #define DKIM_SIGERROR_MISSING_V 44 /* v= tag missing */ 156 #define DKIM_SIGERROR_EMPTY_V 45 /* v= tag empty */ 157 #define DKIM_SIGERROR_KEYTOOSMALL 46 /* too few key bits */ 158 159 /* generic DNS error codes */ 160 #define DKIM_DNS_ERROR (-1) /* error in transit */ 161 #define DKIM_DNS_SUCCESS 0 /* reply available */ 162 #define DKIM_DNS_NOREPLY 1 /* reply not available (yet) */ 163 #define DKIM_DNS_EXPIRED 2 /* no reply, query expired */ 164 #define DKIM_DNS_INVALID 3 /* invalid request */ 165 166 /* 167 ** DKIM_CANON -- canonicalization method 168 */ 169 170 typedef int dkim_canon_t; 171 172 #define DKIM_CANON_UNKNOWN (-1) /* unknown method */ 173 #define DKIM_CANON_SIMPLE 0 /* as specified in DKIM spec */ 174 #define DKIM_CANON_RELAXED 1 /* as specified in DKIM spec */ 175 176 #define DKIM_CANON_DEFAULT DKIM_CANON_SIMPLE 177 178 /* 179 ** DKIM_SIGN -- signing method 180 */ 181 182 typedef int dkim_alg_t; 183 184 #define DKIM_SIGN_UNKNOWN (-2) /* unknown method */ 185 #define DKIM_SIGN_DEFAULT (-1) /* use internal default */ 186 #define DKIM_SIGN_RSASHA1 0 /* an RSA-signed SHA1 digest */ 187 #define DKIM_SIGN_RSASHA256 1 /* an RSA-signed SHA256 digest */ 188 189 /* 190 ** DKIM_QUERY -- query method 191 */ 192 193 typedef int dkim_query_t; 194 195 #define DKIM_QUERY_UNKNOWN (-1) /* unknown method */ 196 #define DKIM_QUERY_DNS 0 /* DNS query method (per the draft) */ 197 #define DKIM_QUERY_FILE 1 /* text file method (for testing) */ 198 199 #define DKIM_QUERY_DEFAULT DKIM_QUERY_DNS 200 201 /* 202 ** DKIM_PARAM -- known signature parameters 203 */ 204 205 typedef int dkim_param_t; 206 207 #define DKIM_PARAM_UNKNOWN (-1) /* unknown */ 208 #define DKIM_PARAM_SIGNATURE 0 /* b */ 209 #define DKIM_PARAM_SIGNALG 1 /* a */ 210 #define DKIM_PARAM_DOMAIN 2 /* d */ 211 #define DKIM_PARAM_CANONALG 3 /* c */ 212 #define DKIM_PARAM_QUERYMETHOD 4 /* q */ 213 #define DKIM_PARAM_SELECTOR 5 /* s */ 214 #define DKIM_PARAM_HDRLIST 6 /* h */ 215 #define DKIM_PARAM_VERSION 7 /* v */ 216 #define DKIM_PARAM_IDENTITY 8 /* i */ 217 #define DKIM_PARAM_TIMESTAMP 9 /* t */ 218 #define DKIM_PARAM_EXPIRATION 10 /* x */ 219 #define DKIM_PARAM_COPIEDHDRS 11 /* z */ 220 #define DKIM_PARAM_BODYHASH 12 /* bh */ 221 #define DKIM_PARAM_BODYLENGTH 13 /* l */ 222 223 /* 224 ** DKIM_MODE -- mode of a handle 225 */ 226 227 #define DKIM_MODE_UNKNOWN (-1) 228 #define DKIM_MODE_SIGN 0 229 #define DKIM_MODE_VERIFY 1 230 231 /* 232 ** DKIM_OPTS -- library-specific options 233 */ 234 235 typedef int dkim_opt_t; 236 237 #define DKIM_OP_GETOPT 0 238 #define DKIM_OP_SETOPT 1 239 240 typedef int dkim_opts_t; 241 242 #define DKIM_OPTS_FLAGS 0 243 #define DKIM_OPTS_TMPDIR 1 244 #define DKIM_OPTS_TIMEOUT 2 245 #define DKIM_OPTS_SENDERHDRS 3 /* obsolete */ 246 #define DKIM_OPTS_SIGNHDRS 4 247 #define DKIM_OPTS_OVERSIGNHDRS 5 248 #define DKIM_OPTS_QUERYMETHOD 6 249 #define DKIM_OPTS_QUERYINFO 7 250 #define DKIM_OPTS_FIXEDTIME 8 251 #define DKIM_OPTS_SKIPHDRS 9 252 #define DKIM_OPTS_ALWAYSHDRS 10 /* obsolete */ 253 #define DKIM_OPTS_SIGNATURETTL 11 254 #define DKIM_OPTS_CLOCKDRIFT 12 255 #define DKIM_OPTS_MUSTBESIGNED 13 256 #define DKIM_OPTS_MINKEYBITS 14 257 #define DKIM_OPTS_REQUIREDHDRS 15 258 259 #define DKIM_LIBFLAGS_NONE 0x00000000 260 #define DKIM_LIBFLAGS_TMPFILES 0x00000001 261 #define DKIM_LIBFLAGS_KEEPFILES 0x00000002 262 #define DKIM_LIBFLAGS_SIGNLEN 0x00000004 263 #define DKIM_LIBFLAGS_CACHE 0x00000008 264 #define DKIM_LIBFLAGS_ZTAGS 0x00000010 265 #define DKIM_LIBFLAGS_DELAYSIGPROC 0x00000020 266 #define DKIM_LIBFLAGS_EOHCHECK 0x00000040 267 #define DKIM_LIBFLAGS_ACCEPTV05 0x00000080 268 #define DKIM_LIBFLAGS_FIXCRLF 0x00000100 269 #define DKIM_LIBFLAGS_ACCEPTDK 0x00000200 270 #define DKIM_LIBFLAGS_BADSIGHANDLES 0x00000400 271 #define DKIM_LIBFLAGS_VERIFYONE 0x00000800 272 #define DKIM_LIBFLAGS_STRICTHDRS 0x00001000 273 #define DKIM_LIBFLAGS_REPORTBADADSP 0x00002000 274 #define DKIM_LIBFLAGS_DROPSIGNER 0x00004000 275 #define DKIM_LIBFLAGS_STRICTRESIGN 0x00008000 276 #define DKIM_LIBFLAGS_REQUESTREPORTS 0x00010000 277 278 #define DKIM_LIBFLAGS_DEFAULT DKIM_LIBFLAGS_NONE 279 280 /* 281 ** DKIM_DNSSEC -- results of DNSSEC queries 282 */ 283 284 #define DKIM_DNSSEC_UNKNOWN (-1) 285 #define DKIM_DNSSEC_BOGUS 0 286 #define DKIM_DNSSEC_INSECURE 1 287 #define DKIM_DNSSEC_SECURE 2 288 289 /* 290 ** DKIM_ATPS -- ATPS result codes 291 */ 292 293 #define DKIM_ATPS_UNKNOWN (-1) 294 #define DKIM_ATPS_NOTFOUND 0 295 #define DKIM_ATPS_FOUND 1 296 297 typedef int dkim_atps_t; 298 299 /* 300 ** DKIM_LIB -- library handle 301 */ 302 303 struct dkim_lib; 304 typedef struct dkim_lib DKIM_LIB; 305 306 /* 307 ** DKIM -- DKIM context 308 */ 309 310 struct dkim; 311 typedef struct dkim DKIM; 312 313 /* 314 ** DKIM_SIGKEY_T -- private/public key (unencoded) 315 */ 316 317 typedef unsigned char * dkim_sigkey_t; 318 319 /* 320 ** DKIM_SIGINFO -- signature information for use by the caller 321 */ 322 323 struct dkim_siginfo; 324 typedef struct dkim_siginfo DKIM_SIGINFO; 325 326 #define DKIM_SIGFLAG_IGNORE 0x01 327 #define DKIM_SIGFLAG_PROCESSED 0x02 328 #define DKIM_SIGFLAG_PASSED 0x04 329 #define DKIM_SIGFLAG_TESTKEY 0x08 330 #define DKIM_SIGFLAG_NOSUBDOMAIN 0x10 331 #define DKIM_SIGFLAG_KEYLOADED 0x20 332 333 #define DKIM_SIGBH_UNTESTED (-1) 334 #define DKIM_SIGBH_MATCH 0 335 #define DKIM_SIGBH_MISMATCH 1 336 337 /* 338 ** DKIM_QUERYINFO -- information about a DNS query that is/may be needed 339 */ 340 341 struct dkim_queryinfo; 342 typedef struct dkim_queryinfo DKIM_QUERYINFO; 343 344 /* 345 ** DKIM_HDRDIFF -- header differences 346 */ 347 348 struct dkim_hdrdiff 349 { 350 u_char * hd_old; 351 u_char * hd_new; 352 }; 353 354 /* 355 ** PROTOTYPES 356 */ 357 358 /* 359 ** DKIM_INIT -- initialize the DKIM package 360 ** 361 ** Parameters: 362 ** mallocf -- a function to receive malloc()-like calls, or NULL 363 ** freef -- a function to receive corresponding free()-like calls, or NULL 364 ** 365 ** Return value: 366 ** A new DKIM library instance handle, or NULL on failure. 367 */ 368 369 extern DKIM_LIB *dkim_init __P((void *(*mallocf)(void *closure, size_t nbytes), 370 void (*freef)(void *closure, void *p))); 371 372 /* 373 ** DKIM_CLOSE -- shut down the DKIM package 374 ** 375 ** Parameters: 376 ** lib -- DKIM_LIB handle to shut down 377 ** 378 ** Return value: 379 ** None. 380 */ 381 382 extern void dkim_close __P((DKIM_LIB *lib)); 383 384 /* 385 ** DKIM_SIGN -- make a new DKIM context for signing 386 ** 387 ** Parameters: 388 ** libhandle -- library handle, returned by dkim_init() 389 ** id -- an opaque printable string for identifying this message, suitable 390 ** for use in logging or debug output; may not be NULL 391 ** memclosure -- memory closure, for use by user-provided malloc/free 392 ** secretkey -- pointer to secret key data to use; if NULL, it will be 393 ** obtained from disk 394 ** selector -- selector being used to sign 395 ** domain -- domain on behalf of which we're signing 396 ** hdr_canon_alg -- canonicalization algorithm to use for headers; 397 ** one of the DKIM_CANON_* macros, or -1 for default 398 ** body_canon_alg -- canonicalization algorithm to use for body; 399 ** one of the DKIM_CANON_* macros, or -1 for default 400 ** sign_alg -- signing algorithm to use; one of the DKIM_SIGN_* macros, 401 ** or -1 for default 402 ** length -- number of bytes of the body to sign (-1 == all) 403 ** statp -- pointer to a DKIM_STAT which is updated by this call 404 ** 405 ** Return value: 406 ** A newly-allocated DKIM handle, or NULL on failure. "statp" will be 407 ** updated. 408 */ 409 410 extern DKIM *dkim_sign __P((DKIM_LIB *libhandle, const unsigned char *id, 411 void *memclosure, const dkim_sigkey_t secretkey, 412 const unsigned char *selector, 413 const unsigned char *domain, 414 dkim_canon_t hdr_canon_alg, 415 dkim_canon_t body_canon_alg, 416 dkim_alg_t sign_alg, 417 ssize_t length, DKIM_STAT *statp)); 418 419 /* 420 ** DKIM_VERIFY -- make a new DKIM context for verifying 421 ** 422 ** Parameters: 423 ** libhandle -- library handle, returned by dkim_init() 424 ** id -- an opaque printable string for identifying this message, suitable 425 ** for use in logging or debug output; may not be NULL 426 ** memclosure -- memory closure, for use by user-provided malloc/free 427 ** statp -- pointer to a DKIM_STAT which is updated by this call 428 ** 429 ** Return value: 430 ** A newly-allocated DKIM handle, or NULL on failure. "statp" will be 431 ** updated. 432 */ 433 434 extern DKIM *dkim_verify __P((DKIM_LIB *libhandle, const unsigned char *id, 435 void *memclosure, DKIM_STAT *statp)); 436 437 /* 438 ** DKIM_RESIGN -- bind a new signing handle to a verifying handle 439 ** 440 ** Parameters: 441 ** new -- new signing handle 442 ** old -- old signing/verifying handle 443 ** hdrbind -- bind headers as well as body 444 ** 445 ** Return value: 446 ** DKIM_STAT_OK -- success 447 ** DKIM_STAT_INVALID -- invalid state of one or both handles 448 ** DKIM_STAT_NOTIMPLEMENT -- not enabled at compile-time 449 ** 450 ** Side effects: 451 ** Sets up flags such that the two are bound; dkim_free() on "old" 452 ** now does nothing, and dkim_free() on "new" will free "old" once 453 ** its reference count reaches zero. See documentation for details. 454 */ 455 456 extern DKIM_STAT dkim_resign __P((DKIM *news, DKIM *olds, _Bool hdrbind)); 457 458 /* 459 ** DKIM_HEADER -- process a header 460 ** 461 ** Parameters: 462 ** dkim -- a DKIM handle previously returned by dkim_sign() or 463 ** dkim_verify() 464 ** hdr -- the header to be processed, in canonical format 465 ** len -- number of bytes to process starting at "hdr" 466 ** 467 ** Return value: 468 ** A DKIM_STAT value. 469 */ 470 471 extern DKIM_STAT dkim_header __P((DKIM *dkim, u_char *hdr, size_t len)); 472 473 /* 474 ** DKIM_EOH -- identify end of headers 475 ** 476 ** Parameters: 477 ** dkim -- a DKIM handle previously returned by dkim_sign() or 478 ** dkim_verify() 479 ** 480 ** Return value: 481 ** A DKIM_STAT value. DKIM_STAT_NOSIG will be returned if we're 482 ** validating a signature but no DKIM signature was found in the headers. 483 */ 484 485 extern DKIM_STAT dkim_eoh __P((DKIM *dkim)); 486 487 /* 488 ** DKIM_BODY -- process a body chunk 489 ** 490 ** Parameters: 491 ** dkim -- a DKIM handle previously returned by dkim_sign() or 492 ** dkim_verify() 493 ** buf -- the body chunk to be processed, in canonical format 494 ** len -- number of bytes to process starting at "hdr" 495 ** 496 ** Return value: 497 ** A DKIM_STAT value. 498 */ 499 500 extern DKIM_STAT dkim_body __P((DKIM *dkim, u_char *buf, size_t len)); 501 502 /* 503 ** DKIM_CHUNK -- process a message chunk 504 ** 505 ** Parameters: 506 ** dkim -- DKIM handle 507 ** buf -- data to process 508 ** buflen -- number of bytes at "buf" to process 509 ** 510 ** Return value: 511 ** A DKIM_STAT_* constant. 512 */ 513 514 extern DKIM_STAT dkim_chunk __P((DKIM *dkim, u_char *buf, size_t buflen)); 515 516 /* 517 ** DKIM_EOM -- identify end of body 518 ** 519 ** Parameters: 520 ** dkim -- a DKIM handle previously returned by dkim_sign() or 521 ** dkim_verify() 522 ** testkey -- TRUE iff the a matching key was found but is marked as a 523 ** test key (returned) 524 ** 525 ** Return value: 526 ** A DKIM_STAT value. 527 */ 528 529 extern DKIM_STAT dkim_eom __P((DKIM *dkim, _Bool *testkey)); 530 531 /* 532 ** DKIM_KEY_SYNTAX -- process a key record parameter set for valid syntax 533 ** 534 ** Parameters: 535 ** dkim -- DKIM context in which this is performed 536 ** str -- string to be scanned 537 ** len -- number of bytes available at "str" 538 ** 539 ** Return value: 540 ** A DKIM_STAT constant. 541 */ 542 543 extern DKIM_STAT dkim_key_syntax __P((DKIM *dkim, u_char *str, size_t len)); 544 545 /* 546 ** DKIM_SIG_SYNTAX -- process a signature parameter set for valid syntax 547 ** 548 ** Parameters: 549 ** dkim -- DKIM context in which this is performed 550 ** str -- string to be scanned 551 ** len -- number of bytes available at "str" 552 ** 553 ** Return value: 554 ** A DKIM_STAT constant. 555 */ 556 557 extern DKIM_STAT dkim_sig_syntax __P((DKIM *dkim, u_char *str, size_t len)); 558 559 /* 560 ** DKIM_GETID -- retrieve "id" pointer from a handle 561 ** 562 ** Parameters: 563 ** dkim -- DKIM handle 564 ** 565 ** Return value: 566 ** The "id" pointer from inside the handle, stored when it was created. 567 */ 568 569 extern const char *dkim_getid __P((DKIM *dkim)); 570 571 /* 572 ** DKIM_GETCACHESTATS -- retrieve cache statistics 573 ** 574 ** Parameters: 575 ** lib -- DKIM library handle 576 ** queries -- number of queries handled (returned) 577 ** hits -- number of cache hits (returned) 578 ** expired -- number of expired hits (returned) 579 ** reset -- if true, reset the queries, hits, and expired counters 580 ** 581 ** Return value: 582 ** DKIM_STAT_OK -- statistics returned 583 ** DKIM_STAT_INVALID -- cache not initialized 584 ** DKIM_STAT_NOTIMPLEMENT -- function not implemented 585 ** 586 ** Notes: 587 ** Any of the parameters may be NULL if the corresponding datum 588 ** is not of interest. 589 */ 590 591 extern DKIM_STAT dkim_getcachestats __P((DKIM_LIB *, u_int *queries, u_int *hits, 592 u_int *expired, u_int *keys, 593 _Bool reset)); 594 595 /* 596 ** DKIM_FLUSH_CACHE -- purge expired records from the database, reclaiming 597 ** space for use by new data 598 ** 599 ** Parameters: 600 ** lib -- DKIM library whose cache should be flushed 601 ** 602 ** Return value: 603 ** -1 -- caching is not in effect 604 ** >= 0 -- number of flushed records 605 */ 606 607 extern int dkim_flush_cache __P((DKIM_LIB *lib)); 608 609 /* 610 ** DKIM_MINBODY -- return number of bytes still expected 611 ** 612 ** Parameters: 613 ** dkim -- DKIM handle 614 ** 615 ** Return value: 616 ** 0 -- all canonicalizations satisfied 617 ** ULONG_MAX -- at least one canonicalization wants the whole message 618 ** other -- bytes required to satisfy all canonicalizations 619 */ 620 621 extern u_long dkim_minbody __P((DKIM *dkim)); 622 623 /* 624 ** DKIM_GETSIGLIST -- retrieve the list of signatures 625 ** 626 ** Parameters: 627 ** dkim -- DKIM handle 628 ** sigs -- pointer to a vector of DKIM_SIGINFO pointers (updated) 629 ** nsigs -- pointer to an integer to receive the pointer count (updated) 630 ** 631 ** Return value: 632 ** A DKIM_STAT_* constant. 633 */ 634 635 extern DKIM_STAT dkim_getsiglist __P((DKIM *dkim, DKIM_SIGINFO ***sigs, 636 int *nsigs)); 637 638 /* 639 ** DKIM_GETSIGNATURE -- retrieve the "final" signature 640 ** 641 ** Parameters: 642 ** dkim -- DKIM handle 643 ** 644 ** Return value: 645 ** Pointer to a DKIM_SIGINFO handle which is the one libopendkim will 646 ** use to return a "final" result; NULL if none could be determined. 647 */ 648 649 extern DKIM_SIGINFO *dkim_getsignature __P((DKIM *dkim)); 650 651 /* 652 ** DKIM_GETSIGHDR -- compute and return a signature header for a message 653 ** 654 ** Parameters: 655 ** dkim -- a DKIM handle previously returned by dkim_sign() 656 ** buf -- buffer into which to write the signature 657 ** len -- number of bytes available at "buf" 658 ** initial -- width of the first line 659 ** 660 ** Return value: 661 ** A DKIM_STAT value. 662 */ 663 664 extern DKIM_STAT dkim_getsighdr __P((DKIM *dkim, u_char *buf, size_t len, 665 size_t initial)); 666 667 /* 668 ** DKIM_GETSIGHDR_D -- compute and return a signature header for a message, 669 ** but do it dynamically 670 ** 671 ** Parameters: 672 ** dkim -- a DKIM handle previously returned by dkim_sign() 673 ** initial -- width of the first line 674 ** buf -- location of generated header (returned) 675 ** len -- number of bytes available at "buf" (returned) 676 ** 677 ** Return value: 678 ** A DKIM_STAT value. 679 */ 680 681 extern DKIM_STAT dkim_getsighdr_d __P((DKIM *dkim, size_t initial, 682 u_char **buf, size_t *len)); 683 684 /* 685 ** DKIM_SIG_HDRSIGNED -- retrieve the header list from a signature 686 ** 687 ** Parameters: 688 ** sig -- DKIM_SIGINFO handle 689 ** hdr -- header name to find 690 ** 691 ** Return value: 692 ** TRUE iff "sig" had a header list in it and the header "hdr" 693 ** appeared in that list. 694 */ 695 696 extern _Bool dkim_sig_hdrsigned __P((DKIM_SIGINFO *sig, u_char *hdr)); 697 698 /* 699 ** DKIM_SIG_GETQUERIES -- retrieve the queries needed to validate a signature 700 ** 701 ** Parameters: 702 ** dkim -- DKIM handle 703 ** sig -- DKIM_SIGINFO handle 704 ** qi -- DKIM_QUERYINFO handle array (returned) 705 ** nqi -- number of entries in the "qi" array 706 ** 707 ** Return value: 708 ** A DKIM_STAT_* constant. 709 */ 710 711 extern DKIM_STAT dkim_sig_getqueries __P((DKIM *dkim, DKIM_SIGINFO *sig, 712 DKIM_QUERYINFO ***qi, 713 unsigned int *nqi)); 714 715 /* 716 ** DKIM_SIG_GETDNSSEC -- retrieve DNSSEC results for a signature 717 ** 718 ** Parameters: 719 ** sig -- DKIM_SIGINFO handle 720 ** 721 ** Return value: 722 ** A DKIM_DNSSEC_* constant. 723 */ 724 725 extern int dkim_sig_getdnssec __P((DKIM_SIGINFO *sig)); 726 727 /* 728 ** DKIM_SIG_SETDNSSEC -- set DNSSEC results for a signature 729 ** 730 ** Parameters: 731 ** sig -- DKIM_SIGINFO handle 732 ** dnssec_status -- A DKIM_DNSSEC_* constant 733 */ 734 735 extern void dkim_sig_setdnssec __P((DKIM_SIGINFO *sig, int dnssec_status)); 736 737 /* 738 ** DKIM_SIG_GETREPORTINFO -- retrieve reporting information from a key 739 ** 740 ** Parameters: 741 ** dkim -- DKIM handle 742 ** sig -- DKIM_SIGINFO handle 743 ** hfd -- canonicalized header descriptor (or NULL) (returned) 744 ** bfd -- canonicalized body descriptor (or NULL) (returned) 745 ** addr -- address buffer (or NULL) 746 ** addrlen -- size of addr 747 ** opts -- options buffer (or NULL) 748 ** optslen -- size of opts 749 ** smtp -- SMTP prefix buffer (or NULL) 750 ** smtplen -- size of smtp 751 ** interval -- requested report interval (or NULL) 752 ** 753 ** Return value: 754 ** A DKIM_STAT_* constant. 755 */ 756 757 extern DKIM_STAT dkim_sig_getreportinfo __P((DKIM *dkim, DKIM_SIGINFO *sig, 758 int *hfd, int *bfd, 759 u_char *addr, size_t addrlen, 760 u_char *opts, size_t optslen, 761 u_char *smtp, size_t smtplen, 762 u_int *interval)); 763 764 /* 765 ** DKIM_SIG_GETIDENTITY -- retrieve identity of the signer 766 ** 767 ** Parameters: 768 ** dkim -- DKIM handle 769 ** sig -- DKIM_SIGINFO handle (or NULL to choose final one) 770 ** val -- destination buffer 771 ** vallen -- size of destination buffer 772 ** 773 ** Return value: 774 ** A DKIM_STAT_* constant. 775 */ 776 777 extern DKIM_STAT dkim_sig_getidentity __P((DKIM *dkim, DKIM_SIGINFO *sig, 778 u_char *val, size_t vallen)); 779 780 /* 781 ** DKIM_SIG_GETCANONLEN -- report number of (canonicalized) body bytes that 782 ** were signed 783 ** 784 ** Parameters: 785 ** dkim -- a DKIM handle previously returned by dkim_sign() or 786 ** dkim_verify() 787 ** sig -- a DKIM_SIGINFO handle 788 ** msglen -- total size of the message body (returned) 789 ** canonlen -- total number of canonicalized bytes (returned) 790 ** signlen -- restricted signature length (returned) 791 ** 792 ** Return value: 793 ** A DKIM_STAT value. 794 ** 795 ** Notes: 796 ** msglen or canonlen can be NULL if that information is not of interest 797 ** to the caller. 798 */ 799 800 extern DKIM_STAT dkim_sig_getcanonlen __P((DKIM *dkim, DKIM_SIGINFO *sig, 801 ssize_t *msglen, ssize_t *canonlen, 802 ssize_t *signlen)); 803 804 /* 805 ** DKIM_OPTIONS -- set/get options 806 ** 807 ** Parameters: 808 ** dkimlib -- DKIM library handle 809 ** op -- operation (DKIM_OP_GET or DKIM_OP_SET) 810 ** opt -- which option (a DKIM_OPTS_* constant) 811 ** ptr -- value (in or out) 812 ** len -- bytes available at "ptr" 813 ** 814 ** Return value: 815 ** A DKIM_STAT value. 816 */ 817 818 extern DKIM_STAT dkim_options __P((DKIM_LIB *dkimlib, int op, dkim_opts_t opt, 819 void *ptr, size_t len)); 820 821 /* 822 ** DKIM_SIG_GETFLAGS -- retreive signature handle flags 823 ** 824 ** Parameters: 825 ** sig -- DKIM_SIGINFO handle 826 ** 827 ** Return value: 828 ** An unsigned integer which is a bitwise-OR of the DKIM_SIGFLAG_* 829 ** constants currently set in the provided handle. 830 */ 831 832 extern unsigned int dkim_sig_getflags __P((DKIM_SIGINFO *sig)); 833 834 /* 835 ** DKIM_SIG_GETBH -- retreive signature handle "bh" test state 836 ** 837 ** Parameters: 838 ** sig -- DKIM_SIGINFO handle 839 ** 840 ** Return value: 841 ** An integer that is one of the DKIM_SIGBH_* constants 842 ** indicating the current state of "bh" evaluation of the signature. 843 */ 844 845 extern int dkim_sig_getbh __P((DKIM_SIGINFO *sig)); 846 847 /* 848 ** DKIM_SIG_GETKEYSIZE -- retreive key size after verifying 849 ** 850 ** Parameters: 851 ** sig -- DKIM_SIGINFO handle 852 ** bits -- size of the key in bits (returned) 853 ** 854 ** Return value: 855 ** A DKIM_STAT value. 856 */ 857 858 extern DKIM_STAT dkim_sig_getkeysize __P((DKIM_SIGINFO *sig, 859 unsigned int *bits)); 860 861 /* 862 ** DKIM_SIG_GETSIGNALG -- retreive signature algorithm after verifying 863 ** 864 ** Parameters: 865 ** sig -- DKIM_SIGINFO handle 866 ** alg -- a DKIM_SIGN_* value (returned) 867 ** 868 ** Return value: 869 ** A DKIM_STAT value. 870 */ 871 872 extern DKIM_STAT dkim_sig_getsignalg __P((DKIM_SIGINFO *sig, dkim_alg_t *alg)); 873 874 /* 875 ** DKIM_SIG_GETSIGNTIME -- retreive signature timestamp after verifying 876 ** 877 ** Parameters: 878 ** sig -- DKIM_SIGINFO handle 879 ** when -- timestamp on the signature (returned) 880 ** 881 ** Return value: 882 ** A DKIM_STAT value. 883 */ 884 885 extern DKIM_STAT dkim_sig_getsigntime __P((DKIM_SIGINFO *sig, uint64_t *when)); 886 887 /* 888 ** DKIM_SIG_GETSELECTOR -- retrieve selector used to generate the signature 889 ** 890 ** Parameters: 891 ** sig -- DKIM_SIGINFO handle from which to retrieve selector 892 ** 893 ** Return value: 894 ** Selector found in the signature. 895 */ 896 897 extern unsigned char *dkim_sig_getselector __P((DKIM_SIGINFO *sig)); 898 899 /* 900 ** DKIM_SIG_GETDOMAIN -- retrieve signing domain after verifying 901 ** 902 ** Parameters: 903 ** sig -- DKIM_SIGINFO handle 904 ** 905 ** Return value: 906 ** Pointer to the signing domain. 907 */ 908 909 extern unsigned char *dkim_sig_getdomain __P((DKIM_SIGINFO *sig)); 910 911 /* 912 ** DKIM_SIG_GETCANONS -- retrieve canonicaliztions after verifying 913 ** 914 ** Parameters: 915 ** sig -- DKIM_SIGINFO handle 916 ** 917 ** Return value: 918 ** DKIM_STAT_OK -- success 919 */ 920 921 extern DKIM_STAT dkim_sig_getcanons __P((DKIM_SIGINFO *sig, dkim_canon_t *hdr, 922 dkim_canon_t *body)); 923 924 /* 925 ** DKIM_SET_USER_CONTEXT -- set DKIM handle user context 926 ** 927 ** Parameters: 928 ** dkim -- DKIM signing handle 929 ** ctx -- user context pointer to store 930 ** 931 ** Parameters: 932 ** A DKIM_STAT_* constant. 933 */ 934 935 extern DKIM_STAT dkim_set_user_context __P((DKIM *dkim, void *ctx)); 936 937 /* 938 ** DKIM_GET_USER_CONTEXT -- retrieve DKIM handle user context 939 ** 940 ** Parameters: 941 ** dkim -- DKIM signing handle 942 ** 943 ** Parameters: 944 ** User context pointer. 945 */ 946 947 extern void *dkim_get_user_context __P((DKIM *dkim)); 948 949 /* 950 ** DKIM_GETMODE -- return the mode (signing, verifying, etc.) of a handle 951 ** 952 ** Parameters: 953 ** dkim -- DKIM handle 954 ** 955 ** Return value: 956 ** A DKIM_MODE_* constant. 957 */ 958 959 extern int dkim_getmode __P((DKIM *dkim)); 960 961 /* 962 ** DKIM_GETDOMAIN -- retrieve policy domain from a DKIM context 963 ** 964 ** Parameters: 965 ** dkim -- DKIM handle 966 ** 967 ** Return value: 968 ** Pointer to the domain used for policy checking (if any) or NULL if 969 ** no domain could be determined. 970 */ 971 972 extern u_char *dkim_getdomain __P((DKIM *dkim)); 973 974 /* 975 ** DKIM_GETUSER -- retrieve sending user (local-part) from a DKIM context 976 ** 977 ** Parameters: 978 ** dkim -- DKIM handle 979 ** 980 ** Return value: 981 ** Pointer to the apparent sending user (local-part) or NULL if not known. 982 */ 983 984 extern u_char *dkim_getuser __P((DKIM *dkim)); 985 986 /* 987 ** DKIM_GET_SIGNER -- get DKIM signature's signer 988 ** 989 ** Parameters: 990 ** dkim -- DKIM signing handle 991 ** 992 ** Parameters: 993 ** Pointer to a buffer containing the signer previously requested, 994 ** or NULL if none. 995 */ 996 997 extern const unsigned char *dkim_get_signer __P((DKIM *dkim)); 998 999 /* 1000 ** DKIM_SET_SIGNER -- set DKIM signature's signer 1001 ** 1002 ** Parameters: 1003 ** dkim -- DKIM signing handle 1004 ** signer -- signer to store 1005 ** 1006 ** Parameters: 1007 ** A DKIM_STAT_* constant. 1008 */ 1009 1010 extern DKIM_STAT dkim_set_signer __P((DKIM *dkim, const u_char *signer)); 1011 1012 /* 1013 ** DKIM_SET_DNS_CALLBACK -- set the DNS wait callback 1014 ** 1015 ** Parameters: 1016 ** libopendkim -- DKIM library handle 1017 ** func -- function to call; should take an opaque context pointer 1018 ** interval -- how often to call back 1019 ** 1020 ** Return value: 1021 ** DKIM_STAT_OK -- success 1022 ** DKIM_STAT_INVALID -- invalid use 1023 ** DKIM_STAT_NOTIMPLEMENT -- underlying resolver doesn't support callbacks 1024 */ 1025 1026 extern DKIM_STAT dkim_set_dns_callback __P((DKIM_LIB *libopendkim, 1027 void (*func)(const void *context), 1028 unsigned int interval)); 1029 1030 /* 1031 ** DKIM_SET_KEY_LOOKUP -- set the key lookup function 1032 ** 1033 ** Parameters: 1034 ** libopendkim -- DKIM library handle 1035 ** func -- function to call 1036 ** 1037 ** Return value: 1038 ** DKIM_STAT_OK 1039 */ 1040 1041 extern DKIM_STAT dkim_set_key_lookup __P((DKIM_LIB *libopendkim, 1042 DKIM_CBSTAT (*func)(DKIM *dkim, 1043 DKIM_SIGINFO *sig, 1044 u_char *buf, 1045 size_t buflen))); 1046 1047 /* 1048 ** DKIM_SET_SIGNATURE_HANDLE -- set the signature handle creator function 1049 ** 1050 ** Parameters: 1051 ** libopendkim -- DKIM library handle 1052 ** func -- function to call 1053 ** 1054 ** Return value: 1055 ** Pointer to the user-side handle thus created, or NULL. 1056 */ 1057 1058 extern DKIM_STAT dkim_set_signature_handle __P((DKIM_LIB *libopendkim, 1059 void * (*func)(void *closure))); 1060 1061 /* 1062 ** DKIM_SET_SIGNATURE_HANDLE_FREE -- set the signature handle destroyer 1063 ** function 1064 ** 1065 ** Parameters: 1066 ** libopendkim -- DKIM library handle 1067 ** func -- function to call 1068 ** 1069 ** Return value: 1070 ** None. 1071 */ 1072 1073 extern DKIM_STAT dkim_set_signature_handle_free __P((DKIM_LIB *libopendkim, 1074 void (*func)(void *closure, 1075 void *user))); 1076 1077 /* 1078 ** DKIM_SET_SIGNATURE_TAGVALUES -- set the signature handle populator function 1079 ** 1080 ** Parameters: 1081 ** libopendkim -- DKIM library handle 1082 ** func -- function to call 1083 ** 1084 ** Return value: 1085 ** DKIM_STAT_OK 1086 */ 1087 1088 extern DKIM_STAT dkim_set_signature_tagvalues __P((DKIM_LIB *libopendkim, 1089 void (*func)(void *user, 1090 dkim_param_t pcode, 1091 const u_char *param, 1092 const u_char *value))); 1093 1094 /* 1095 ** DKIM_SET_PRESCREEN -- set the prescreen function 1096 ** 1097 ** Parameters: 1098 ** libopendkim -- DKIM library handle 1099 ** func -- function to call 1100 ** 1101 ** Return value: 1102 ** DKIM_STAT_OK 1103 */ 1104 1105 extern DKIM_STAT dkim_set_prescreen __P((DKIM_LIB *libopendkim, 1106 DKIM_CBSTAT (*func)(DKIM *dkim, 1107 DKIM_SIGINFO **sigs, 1108 int nsigs))); 1109 1110 /* 1111 ** DKIM_SET_FINAL -- set the final processing function 1112 ** 1113 ** Parameters: 1114 ** libopendkim -- DKIM library handle 1115 ** func -- function to call 1116 ** 1117 ** Return value: 1118 ** DKIM_STAT_OK 1119 */ 1120 1121 extern DKIM_STAT dkim_set_final __P((DKIM_LIB *libopendkim, 1122 DKIM_CBSTAT (*func)(DKIM *dkim, 1123 DKIM_SIGINFO **sigs, 1124 int nsigs))); 1125 1126 /* 1127 ** DKIM_SIG_GETCONTEXT -- get user-specific context from a DKIM_SIGINFO 1128 ** 1129 ** Parameters: 1130 ** siginfo -- a pointer to a DKIM_SIGINFO 1131 ** 1132 ** Return value: 1133 ** The user-provided pointer stored in the named "siginfo", or NULL 1134 ** if none was ever set. 1135 */ 1136 1137 extern void *dkim_sig_getcontext __P((DKIM_SIGINFO *siginfo)); 1138 1139 /* 1140 ** DKIM_SIG_GETERROR -- get error code from a DKIM_SIGINFO 1141 ** 1142 ** Parameters: 1143 ** siginfo -- a pointer to a DKIM_SIGINFO 1144 ** 1145 ** Return value: 1146 ** A DKIM_SIGERROR_* constant. 1147 */ 1148 1149 extern int dkim_sig_geterror __P((DKIM_SIGINFO *siginfo)); 1150 1151 /* 1152 ** DKIM_SIG_SETERROR -- set error code in a DKIM_SIGINFO 1153 ** 1154 ** Parameters: 1155 ** siginfo -- a pointer to a DKIM_SIGINFO 1156 ** err -- error code 1157 ** 1158 ** Return value: 1159 ** A DKIM_STAT_* constant. 1160 */ 1161 1162 extern DKIM_STAT dkim_sig_seterror __P((DKIM_SIGINFO *siginfo, int err)); 1163 1164 /* 1165 ** DKIM_SIG_GETERRORSTR -- translate a DKIM_SIGERROR into a string 1166 ** 1167 ** Parameters: 1168 ** sigerr -- a DKIM_SIGERROR constant 1169 ** 1170 ** Return value: 1171 ** A pointer to a human-readable string translation of "sigerr", or NULL 1172 ** if no such translation exists. 1173 */ 1174 1175 extern const char *dkim_sig_geterrorstr __P((DKIM_SIGERROR sigerr)); 1176 1177 /* 1178 ** DKIM_SIG_IGNORE -- mark a signature referenced by a DKIM_SIGINFO with 1179 ** an "ignore" flag 1180 ** 1181 ** Parameters: 1182 ** siginfo -- pointer to a DKIM_SIGINFO to update 1183 ** 1184 ** Return value: 1185 ** None. 1186 */ 1187 1188 extern void dkim_sig_ignore __P((DKIM_SIGINFO *siginfo)); 1189 1190 /* 1191 ** DKIM_SIG_PROCESS -- process a signature 1192 ** 1193 ** Parameters: 1194 ** dkim -- DKIM handle 1195 ** sig -- DKIM_SIGINFO handle 1196 ** 1197 ** Return value: 1198 ** A DKIM_STAT_* constant. 1199 */ 1200 1201 extern DKIM_STAT dkim_sig_process __P((DKIM *dkim, DKIM_SIGINFO *sig)); 1202 1203 /* 1204 ** DKIM_FREE -- release resources associated with a DKIM handle 1205 ** 1206 ** Parameters: 1207 ** dkim -- a DKIM handle previously returned by dkim_sign() or 1208 ** dkim_verify() 1209 ** 1210 ** Return value: 1211 ** A DKIM_STAT value. 1212 */ 1213 1214 extern DKIM_STAT dkim_free __P((DKIM *dkim)); 1215 1216 /* 1217 ** DKIM_GETERROR -- return any stored error string from within the DKIM 1218 ** context handle 1219 ** 1220 ** Parameters: 1221 ** dkim -- DKIM handle from which to retrieve an error string 1222 ** 1223 ** Return value: 1224 ** A pointer to the stored string, or NULL if none was stored. 1225 */ 1226 1227 extern const char *dkim_geterror __P((DKIM *dkim)); 1228 1229 /* 1230 ** DKIM_GETRESULTSTR -- translate a DKIM_STAT_* constant to a string 1231 ** 1232 ** Parameters: 1233 ** result -- DKIM_STAT_* constant to translate 1234 ** 1235 ** Return value: 1236 ** Pointer to a text describing "result", or NULL if none exists 1237 */ 1238 1239 extern const char *dkim_getresultstr __P((DKIM_STAT result)); 1240 1241 /* 1242 ** DKIM_OHDRS -- extract and decode original headers 1243 ** 1244 ** Parameters: 1245 ** dkim -- DKIM handle 1246 ** sig -- DKIM_SIGINFO handle 1247 ** ptrs -- user-provided array of pointers to header strings (updated) 1248 ** pcnt -- number of pointers available (updated) 1249 ** 1250 ** Return value: 1251 ** A DKIM_STAT_* constant. 1252 */ 1253 1254 extern DKIM_STAT dkim_ohdrs __P((DKIM *dkim, DKIM_SIGINFO *sig, u_char **ptrs, 1255 int *pcnt)); 1256 1257 /* 1258 ** DKIM_DIFFHEADERS -- compare original headers with received headers 1259 ** 1260 ** Parameters: 1261 ** dkim -- DKIM handle 1262 ** canon -- canonicalization mode in use 1263 ** maxcost -- maximum "cost" of changes to be reported 1264 ** ohdrs -- original headers, presumably extracted from a "z" tag 1265 ** nohdrs -- number of headers at "ohdrs" available 1266 ** out -- pointer to an array of struct dkim_hdrdiff objects (updated) 1267 ** nout -- counter of handles returned (updated) 1268 ** 1269 ** Return value: 1270 ** A DKIM_STAT_* constant. 1271 ** 1272 ** Side effects: 1273 ** A series of DKIM_HDRDIFF handles is allocated and must later be 1274 ** destroyed. 1275 */ 1276 1277 extern DKIM_STAT dkim_diffheaders __P((DKIM *dkim, dkim_canon_t canon, 1278 int maxcost, 1279 char **ohdrs, int nohdrs, 1280 struct dkim_hdrdiff **out, int *nout)); 1281 1282 /* 1283 ** DKIM_GETPARTIAL -- return a DKIM handle's "body length tag" flag 1284 ** 1285 ** Parameters: 1286 ** dkim -- DKIM handle 1287 ** 1288 ** Return value: 1289 ** True iff the signature is to include a body length tag 1290 */ 1291 1292 extern _Bool dkim_getpartial __P((DKIM *dkim)); 1293 1294 /* 1295 ** DKIM_SETPARTIAL -- set the DKIM handle to sign using the DKIM body length 1296 ** tag (l=) 1297 ** 1298 ** Parameters: 1299 ** dkim -- DKIM handle 1300 ** value -- new flag value 1301 ** 1302 ** Return value: 1303 ** DKIM_STAT_OK 1304 */ 1305 1306 extern DKIM_STAT dkim_setpartial __P((DKIM *dkim, _Bool value)); 1307 1308 /* 1309 ** DKIM_SET_MARGIN -- set the margin to use when generating signatures 1310 ** 1311 ** Parameters: 1312 ** dkim -- DKIM handle 1313 ** value -- new margin value 1314 ** 1315 ** Return value: 1316 ** DKIM_STAT_INVALID -- "dkim" referenced a verification handle, or 1317 ** "value" was negative 1318 ** DKIM_STAT_OK -- otherwise 1319 */ 1320 1321 extern DKIM_STAT dkim_set_margin __P((DKIM *dkim, int value)); 1322 1323 /* 1324 ** DKIM_MAIL_PARSE -- extract the local-part and domain-name from a structured 1325 ** header field 1326 ** 1327 ** Parameters: 1328 ** addr -- the header to parse; see RFC2822 for format 1329 ** user -- local-part of the parsed header (returned) 1330 ** domain -- domain part of the parsed header (returned) 1331 ** 1332 ** Return value: 1333 ** 0 on success; other on error (see source) 1334 */ 1335 1336 extern int dkim_mail_parse __P((u_char *addr, u_char **user, u_char **domain)); 1337 1338 /* 1339 ** DKIM_SSL_VERSION -- return the version of the OpenSSL library against 1340 ** which this library was compiled 1341 ** 1342 ** Parameters: 1343 ** None. 1344 ** 1345 ** Return value: 1346 ** The OPENSSL_VERSION_NUMBER constant as defined by OpenSSL. 1347 */ 1348 1349 extern unsigned long dkim_ssl_version __P((void)); 1350 1351 /* 1352 ** DKIM_LIBFEATURE -- check for a library feature 1353 ** 1354 ** Parameters: 1355 ** lib -- DKIM_LIB handle 1356 ** fc -- feature code 1357 ** 1358 ** Return value: 1359 ** TRUE iff the library was compiled with the requested feature 1360 */ 1361 1362 #define DKIM_FEATURE_DIFFHEADERS 0 1363 #define DKIM_FEATURE_UNUSED 1 1364 #define DKIM_FEATURE_PARSE_TIME 2 1365 #define DKIM_FEATURE_QUERY_CACHE 3 1366 #define DKIM_FEATURE_SHA256 4 1367 #define DKIM_FEATURE_OVERSIGN 5 1368 #define DKIM_FEATURE_DNSSEC 6 1369 #define DKIM_FEATURE_RESIGN 7 1370 #define DKIM_FEATURE_ATPS 8 1371 #define DKIM_FEATURE_XTAGS 9 1372 1373 #define DKIM_FEATURE_MAX 9 1374 1375 extern _Bool dkim_libfeature __P((DKIM_LIB *lib, u_int fc)); 1376 1377 1378 /* 1379 ** DKIM_LIBVERSION -- return version of libopendkim at runtime 1380 ** 1381 ** Parameters: 1382 ** None. 1383 ** 1384 ** Return value: 1385 ** Library version, i.e. value of the OPENDKIM_LIB_VERSION macro. 1386 */ 1387 1388 extern uint32_t dkim_libversion __P((void)); 1389 1390 /* 1391 ** DKIM_GET_SIGSUBSTRING -- retrieve a minimal signature substring for 1392 ** disambiguation 1393 ** 1394 ** Parameters: 1395 ** dkim -- DKIM handle 1396 ** sig -- DKIM_SIGINFO handle 1397 ** buf -- buffer into which to put the substring 1398 ** buflen -- bytes available at "buf" 1399 ** 1400 ** Return value: 1401 ** A DKIM_STAT_* constant. 1402 */ 1403 1404 extern DKIM_STAT dkim_get_sigsubstring __P((DKIM *, DKIM_SIGINFO *, 1405 char *, size_t *)); 1406 1407 /* 1408 ** DKIM_TEST_KEY -- retrieve a public key and verify it against a provided 1409 ** private key 1410 ** 1411 ** Parameters: 1412 ** lib -- DKIM library handle 1413 ** selector -- selector 1414 ** domain -- domain name 1415 ** key -- private key to verify (PEM format) 1416 ** keylen -- size of private key 1417 ** dnssec -- DNSSEC result (may be NULL) 1418 ** err -- error buffer (may be NULL) 1419 ** errlen -- size of error buffer 1420 ** 1421 ** Return value: 1422 ** 1 -- keys don't match 1423 ** 0 -- keys match (or no key provided) 1424 ** -1 -- error 1425 */ 1426 1427 extern int dkim_test_key __P((DKIM_LIB *, char *, char *, char *, size_t, 1428 int *, char *, size_t)); 1429 1430 /* 1431 ** DKIM_SIG_GETTAGVALUE -- retrieve a tag's value from a signature or its key 1432 ** 1433 ** Parameters: 1434 ** sig -- DKIM_SIGINFO handle 1435 ** keytag -- TRUE iff we want a key's tag 1436 ** tag -- name of the tag of interest 1437 ** 1438 ** Return value: 1439 ** Pointer to the string containing the value of the requested key, 1440 ** or NULL if not present. 1441 ** 1442 ** Notes: 1443 ** This was added for use in determining whether or not a key or 1444 ** signature contained particular data, for gathering general statistics 1445 ** about DKIM use. It is not intended to give applications direct access 1446 ** to unprocessed signature or key data. The data returned has not 1447 ** necessarily been vetted in any way. Caveat emptor. 1448 */ 1449 1450 extern u_char *dkim_sig_gettagvalue __P((DKIM_SIGINFO *, _Bool, u_char *)); 1451 1452 /* 1453 ** DKIM_SIG_GETSIGNEDHDRS -- retrieve the signed header fields covered by 1454 ** a signature that passed 1455 ** 1456 ** Parameters: 1457 ** dkim -- DKIM instance 1458 ** sig -- signature 1459 ** hdrs -- rectangular array of header field strings 1460 ** hdrlen -- length of each element of "hdrs" 1461 ** nhdrs -- size of "hdrs" array (updated) 1462 ** 1463 ** Return value: 1464 ** A DKIM_STAT_* constant. 1465 */ 1466 1467 extern DKIM_STAT dkim_sig_getsignedhdrs __P((DKIM *, DKIM_SIGINFO *, 1468 u_char *, size_t, u_int *)); 1469 1470 /* 1471 ** DKIM_QP_DECODE -- decode a quoted-printable string 1472 ** 1473 ** Parameters: 1474 ** in -- input 1475 ** out -- output 1476 ** outlen -- bytes available at "out" 1477 ** 1478 ** Return value: 1479 ** >= 0 -- number of bytes in output 1480 ** -1 -- parse error 1481 */ 1482 1483 extern int dkim_qp_decode __P((unsigned char *, unsigned char *, int)); 1484 1485 /* 1486 ** DKIM_DNS_SET_QUERY_SERVICE -- stores a handle representing the DNS 1487 ** query service to be used, returning any 1488 ** previous handle 1489 ** 1490 ** Parameters: 1491 ** lib -- DKIM library handle 1492 ** h -- handle to be used 1493 ** 1494 ** Return value: 1495 ** Previously stored handle, or NULL if none. 1496 */ 1497 1498 extern void *dkim_dns_set_query_service __P((DKIM_LIB *, void *)); 1499 1500 /* 1501 ** DKIM_DNS_SET_QUERY_START -- stores a pointer to a query start function 1502 ** 1503 ** Parameters: 1504 ** lib -- DKIM library handle 1505 ** func -- function to use to start queries 1506 ** 1507 ** Return value: 1508 ** None. 1509 ** 1510 ** Notes: 1511 ** "func" should match the following prototype: 1512 ** returns int (status) 1513 ** void *dns -- receives handle stored by 1514 ** dkim_dns_set_query_service() 1515 ** int type -- DNS RR query type (C_IN assumed) 1516 ** char *query -- question to ask 1517 ** char *buf -- buffer into which to write reply 1518 ** size_t buflen -- size of buf 1519 ** void **qh -- returned query handle 1520 */ 1521 1522 extern void dkim_dns_set_query_start __P((DKIM_LIB *, 1523 int (*)(void *, int, 1524 unsigned char *, 1525 unsigned char *, 1526 size_t, void **))); 1527 1528 /* 1529 ** DKIM_DNS_SET_QUERY_CANCEL -- stores a pointer to a query cancel function 1530 ** 1531 ** Parameters: 1532 ** lib -- DKIM library handle 1533 ** func -- function to use to cancel running queries 1534 ** 1535 ** Return value: 1536 ** None. 1537 ** 1538 ** Notes: 1539 ** "func" should match the following prototype: 1540 ** returns int (status) 1541 ** void *dns -- DNS service handle 1542 ** void *qh -- query handle to be canceled 1543 */ 1544 1545 extern void dkim_dns_set_query_cancel __P((DKIM_LIB *, 1546 int (*)(void *, void *))); 1547 1548 /* 1549 ** DKIM_DNS_SET_QUERY_WAITREPLY -- stores a pointer to wait for a DNS reply 1550 ** 1551 ** Parameters: 1552 ** lib -- DKIM library handle 1553 ** func -- function to use to wait for a reply 1554 ** 1555 ** Return value: 1556 ** None. 1557 ** 1558 ** Notes: 1559 ** "func" should match the following prototype: 1560 ** returns int (status) 1561 ** void *dns -- DNS service handle 1562 ** void *qh -- handle of query that has completed 1563 ** struct timeval *timeout -- how long to wait 1564 ** size_t *bytes -- bytes returned 1565 ** int *error -- error code returned 1566 ** int *dnssec -- DNSSEC status returned 1567 */ 1568 1569 extern void dkim_dns_set_query_waitreply __P((DKIM_LIB *, 1570 int (*)(void *, void *, 1571 struct timeval *, 1572 size_t *, int *, 1573 int *))); 1574 1575 /* 1576 ** DKIM_DNS_SET_INIT -- initializes the resolver 1577 ** 1578 ** Parameters: 1579 ** lib -- DKIM library handle 1580 ** func -- function to use to initialize the resolver 1581 ** 1582 ** Return value: 1583 ** None. 1584 ** 1585 ** Notes: 1586 ** "func" should match the following prototype: 1587 ** returns int (status) 1588 ** void **srv -- DNS service handle (updated) 1589 */ 1590 1591 extern void dkim_dns_set_init __P((DKIM_LIB *, 1592 int (*)(void **))); 1593 1594 /* 1595 ** DKIM_DNS_SET_CLOSE -- shuts down the resolver 1596 ** 1597 ** Parameters: 1598 ** lib -- DKIM library handle 1599 ** func -- function to use to shut down the resolver 1600 ** 1601 ** Return value: 1602 ** None. 1603 ** 1604 ** Notes: 1605 ** "func" should match the following prototype: 1606 ** returns void 1607 ** void *srv -- DNS service handle 1608 */ 1609 1610 extern void dkim_dns_set_close __P((DKIM_LIB *, 1611 void (*)(void *))); 1612 1613 /* 1614 ** DKIM_DNS_SET_NSLIST -- set function that updates resolver nameserver list 1615 ** 1616 ** Parameters: 1617 ** lib -- DKIM library handle 1618 ** func -- function to use to update the nameserver list 1619 ** 1620 ** Return value: 1621 ** None. 1622 ** 1623 ** Notes: 1624 ** "func" should match the following prototype: 1625 ** returns int 1626 ** void *srv -- DNS service handle 1627 ** const char *nslist -- nameserver list, as a comma-separated 1628 ** string 1629 */ 1630 1631 extern void dkim_dns_set_nslist __P((DKIM_LIB *, 1632 int (*)(void *, const char *))); 1633 1634 /* 1635 ** DKIM_DNS_SET_CONFIG -- set function that passes configuration data to 1636 ** the active resolver 1637 ** 1638 ** Parameters: 1639 ** lib -- DKIM library handle 1640 ** func -- function to use to configure the active resolver 1641 ** 1642 ** Return value: 1643 ** None. 1644 ** 1645 ** Notes: 1646 ** "func" should match the following prototype: 1647 ** returns int 1648 ** void *srv -- DNS service handle 1649 ** const char *config -- arbitrary configuration data 1650 */ 1651 1652 extern void dkim_dns_set_config __P((DKIM_LIB *, 1653 int (*)(void *, const char *))); 1654 1655 /* 1656 ** DKIM_DNS_SET_TRUSTANCHOR -- set function that passes trust anchor data to 1657 ** the active resolver 1658 ** 1659 ** Parameters: 1660 ** lib -- DKIM library handle 1661 ** func -- function to use to pass trust anchor data to the resolver 1662 ** 1663 ** Return value: 1664 ** None. 1665 ** 1666 ** Notes: 1667 ** "func" should match the following prototype: 1668 ** returns int 1669 ** void *srv -- DNS service handle 1670 ** const char *trustanchor -- arbitrary trust anchor data 1671 */ 1672 1673 extern void dkim_dns_set_trustanchor __P((DKIM_LIB *, 1674 int (*)(void *, const char *))); 1675 1676 /* 1677 ** DKIM_DNS_NSLIST -- update resolver nameserver list 1678 ** 1679 ** Parameters: 1680 ** lib -- DKIM library handle 1681 ** nslist -- comma-separated nameserver list, as IP addresses 1682 ** 1683 ** Return value: 1684 ** A DKIM_DNS_* constant. 1685 ** 1686 ** Notes: 1687 ** The underlying API may not return a failure status, in which case 1688 ** this always returns DKIM_DNS_SUCCESS. The underlying API might also 1689 ** not use all of the nameservers provided. 1690 */ 1691 1692 extern int dkim_dns_nslist __P((DKIM_LIB *, const char *)); 1693 1694 /* 1695 ** DKIM_DNS_INIT -- force resolver (re)initialization 1696 ** 1697 ** Parameters: 1698 ** lib -- DKIM library handle 1699 ** 1700 ** Return value: 1701 ** A DKIM_DNS_* constant. 1702 */ 1703 1704 extern int dkim_dns_init __P((DKIM_LIB *)); 1705 1706 /* 1707 ** DKIM_DNS_CLOSE -- force resolver shutdown 1708 ** 1709 ** Parameters: 1710 ** lib -- DKIM library handle 1711 ** 1712 ** Return value: 1713 ** A DKIM_DNS_* constant. 1714 */ 1715 1716 extern int dkim_dns_close __P((DKIM_LIB *)); 1717 1718 /* 1719 ** DKIM_DNS_CONFIG -- requests a change to resolver configuration 1720 ** 1721 ** Parameters: 1722 ** lib -- DKIM library handle 1723 ** config -- opaque configuration string 1724 ** 1725 ** Return value: 1726 ** A DKIM_DNS_* constant. 1727 */ 1728 1729 extern int dkim_dns_config __P((DKIM_LIB *, const char *)); 1730 1731 /* 1732 ** DKIM_DNS_TRUSTANCHOR -- requests a change to trust anchor configuration 1733 ** 1734 ** Parameters: 1735 ** lib -- DKIM library handle 1736 ** trust -- opaque trust anchor string 1737 ** 1738 ** Return value: 1739 ** A DKIM_DNS_* constant. 1740 */ 1741 1742 extern int dkim_dns_trustanchor __P((DKIM_LIB *, const char *)); 1743 1744 /* 1745 ** DKIM_ADD_QUERYMETHOD -- add a query method 1746 ** 1747 ** Parameters: 1748 ** dkim -- DKIM signing handle to extend 1749 ** type -- type of query to add 1750 ** options -- options to include 1751 ** 1752 ** Return value: 1753 ** A DKIM_STAT_* constant. 1754 */ 1755 1756 extern DKIM_STAT dkim_add_querymethod __P((DKIM *, const char *, 1757 const char *)); 1758 1759 /* 1760 ** DKIM_ADD_XTAG -- add an extension tag/value 1761 ** 1762 ** Parameters: 1763 ** dkim -- DKIM signing handle to extend 1764 ** tag -- name of tag to add 1765 ** value -- value to include 1766 ** 1767 ** Return value: 1768 ** A DKIM_STAT_* constant. 1769 */ 1770 1771 extern DKIM_STAT dkim_add_xtag __P((DKIM *, const char *, const char *)); 1772 1773 /* 1774 ** DKIM_PRIVKEY_LOAD -- explicitly try to load the private key 1775 ** 1776 ** Parameters: 1777 ** dkim -- DKIM signing handle 1778 ** 1779 ** Return value: 1780 ** A DKIM_STAT_* constant. 1781 */ 1782 1783 extern DKIM_STAT dkim_privkey_load __P((DKIM *)); 1784 1785 /* 1786 ** DKIM_ATPS_CHECK -- check for Authorized Third Party Signing 1787 ** 1788 ** Parameters: 1789 ** dkim -- DKIM message handle 1790 ** sig -- signature information handle 1791 ** timeout -- timeout (can be NULL) 1792 ** res -- ATPS result code 1793 ** 1794 ** Return value: 1795 ** A DKIM_STAT_* constant. 1796 */ 1797 1798 extern DKIM_STAT dkim_atps_check __P((DKIM *, DKIM_SIGINFO *, 1799 struct timeval *, dkim_atps_t *res)); 1800 1801 /* 1802 ** DKIM_QI_GETNAME -- retrieve the DNS name from a DKIM_QUERYINFO object 1803 ** 1804 ** Parameters: 1805 ** query -- DKIM_QUERYINFO handle 1806 ** 1807 ** Return value: 1808 ** A pointer to a NULL-terminated string indicating the name to be 1809 ** queried, or NULL on error. 1810 */ 1811 1812 extern const char *dkim_qi_getname __P((DKIM_QUERYINFO *)); 1813 1814 /* 1815 ** DKIM_QI_GETTYPE -- retrieve the DNS RR type from a DKIM_QUERYINFO object 1816 ** 1817 ** Parameters: 1818 ** query -- DKIM_QUERYINFO handle 1819 ** 1820 ** Return value: 1821 ** The DNS RR type to be queried, or -1 on error. 1822 */ 1823 1824 extern int dkim_qi_gettype __P((DKIM_QUERYINFO *)); 1825 1826 /* 1827 ** DKIM_BASE32_ENCODE -- encode a string using base32 1828 ** 1829 ** Parameters: 1830 ** buf -- destination buffer 1831 ** buflen -- bytes available at buf (updated) 1832 ** data -- pointer to data to encode 1833 ** size -- bytes at "data" to encode 1834 ** 1835 ** Return value: 1836 ** Length of encoding. 1837 ** 1838 ** Notes: 1839 ** buf should be at least a byte more than *buflen to hold the trailing 1840 ** '\0'. 1841 ** 1842 ** *buflen is updated to count the number of bytes read from "data". 1843 */ 1844 1845 extern int dkim_base32_encode __P((char *, size_t *, const void *, size_t)); 1846 1847 /* 1848 ** DKIM_SIG_GETHASHES -- retrieve hashes 1849 ** 1850 ** Parameters: 1851 ** sig -- signature from which to get completed hashes 1852 ** hh -- pointer to header hash buffer (returned) 1853 ** hhlen -- bytes used at hh (returned) 1854 ** bh -- pointer to body hash buffer (returned) 1855 ** bhlen -- bytes used at bh (returned) 1856 ** 1857 ** Return value: 1858 ** DKIM_STAT_OK -- successful completion 1859 ** DKIM_STAT_INVALID -- hashing hasn't been completed 1860 */ 1861 1862 extern DKIM_STAT dkim_sig_gethashes __P((DKIM_SIGINFO *, void **, size_t *, 1863 void **, size_t *)); 1864 1865 /* 1866 ** DKIM_SIGNHDRS -- set the list of header fields to sign for a signature, 1867 ** overriding the library default 1868 ** 1869 ** Parameters: 1870 ** dkim -- DKIM signing handle to be affected 1871 ** hdrlist -- array of names of header fields that should be signed 1872 ** 1873 ** Return value: 1874 ** A DKIM_STAT_* constant. 1875 ** 1876 ** Notes: 1877 ** "hdrlist" can be NULL if the library's default is to be used. 1878 */ 1879 1880 extern DKIM_STAT dkim_signhdrs __P((DKIM *, const char **)); 1881 1882 /* 1883 ** DKIM_GETSSLBUF -- get the SSL error buffer, if any, from a DKIM handle 1884 ** 1885 ** Parameters: 1886 ** dkim -- DKIM handle from which to get SSL error 1887 ** 1888 ** Return value: 1889 ** Pointer to the string, if defined, or NULL otherwise. 1890 */ 1891 1892 extern const char *dkim_getsslbuf __P((DKIM *dkim)); 1893 1894 /* 1895 ** DKIM_SIG_GETSSLBUF -- get the SSL error buffer, if any, from a signature 1896 ** 1897 ** Parameters: 1898 ** sig -- signature handle from which to get SSL error 1899 ** 1900 ** Return value: 1901 ** Pointer to the string, if defined, or NULL otherwise. 1902 */ 1903 1904 extern const char *dkim_sig_getsslbuf __P((DKIM_SIGINFO *sig)); 1905 1906 /* list of headers that should be signed, per RFC6376 Section 5.4 */ 1907 extern const u_char *dkim_should_signhdrs[]; 1908 1909 /* list of headers that should not be signed, per RFC6376 Section 5.4 */ 1910 extern const u_char *dkim_should_not_signhdrs[]; 1911 1912 1913 #ifdef __cplusplus 1914 } 1915 #endif /* __cplusplus */ 1916 1917 #endif /* ! _DKIM_H_ */ 1918