Sendmail DomainKeys Identified Mail (DKIM) Library

Introduction

DomainKeys Identified Mail ("DKIM") is a specification for signing messages at the domain level using simple cryptographic methods to prevent the falsification of sender domains. While the most obvious application of this is to defense against spam, other applications can make use of this capability.

DKIM is an amalgamation of DomainKeys, created by Yahoo!, Inc., and Internet Identified Mail (IIM) created by Cisco, Inc. Both can be found as historical RFCs documents via the IETF web sites. More information about DomainKeys can be found here.

This API (libdkim) allows an application to sign or verify messages according to the DKIM proposed standard. Also provided is an implementation of a filter, using Sendmail's milter package, that uses libdkim to implement this facility.

Data Types

Data Type Description
DKIM A signing/verifying context for a message.
dkim_alg_t A signature generation/verification method.
dkim_canon_t A canonicalization method.
DKIM_CBSTAT Return value/status from user-provided callbacks.
DKIM_LIB An instance of the libdkim service.
dkim_param_t A signature parameter.
dkim_query_t A key query method.
DKIM_SIGINFO Private handle referencing information about a particular signature on a signed message.
dkim_sigkey_t Private key data.
DKIM_STAT Return value/status.

Functions

Function Description
Administration
dkim_init() Initialize an instance of the DKIM service.
dkim_set_dns_callback() Request a call back into the main program from time to time while waiting for DNS results.
dkim_set_key_lookup() Provide a function to perform key lookups, replacing the internal implementation.
dkim_set_policy_lookup() Provide a function to perform policy lookups, replacing the internal implementation.
dkim_set_prescreen() Provide a function to perform signature prescreening and or re-ordering during verifications.
dkim_set_signature_handle() Provide a function to allocate a user-side signature description structure and return a pointer to it.
dkim_set_signature_handle_free() Provide a function to deallocate a user-side signature description structure.
dkim_set_signature_tagvalues() Provide a function to receive signature-specific tags and values for user-side analysis.
dkim_ssl_version() Retrieve the OpenSSL version used when the library was compiled.
dkim_close() Terminate an instance of the DKIM service.
Signing
dkim_sign() Allocate a new DKIM handle for signing a message.
dkim_getsighdr() Generate and return a signature header.
dkim_getidentity() Retrieve sender identity information extracted from headers.
Verifying
dkim_verify() Allocate a new DKIM handle for verifying a message.
dkim_policy() Retrieve signer policy information.
dkim_reportinfo() Retrieve information required to generate a verification failure report.
dkim_getcanonlen() Retrieve information regarding total canonicalized body length, and the size of what was actually signed.
dkim_geterror() Retrieve the most recent internal error message associated with a DKIM handle.
dkim_getkeysize() Retrieve the size in bits of the key used to verify a message.
dkim_getselector() Retrieve the selector found in the signature for a message.
dkim_getsigdomain() Retrieve the domain name found in the signature for a message.
dkim_getsignalg() Retrieve the signature algorithm used to sign a message.
dkim_getsigntime() Retrieve the timestamp on the signature of a message.
dkim_ohdrs() Retrieve the original header set from the signature if it was present.
dkim_set_user_context() Set a specific user context pointer for a sign or verify operation which will be passed to user callbacks.
dkim_sig_getcontext() Retrieve user-side context specific to a signature.
dkim_sig_ignore() Flag a signature to be ignored when verifying.
Processing
dkim_header() Process a header.
dkim_eoh() Identify end of headers.
dkim_body() Process a body chunk.
dkim_eom() Identify end of message.
Utility
dkim_options() Get or set library options.
rfc2822_mailbox_split() Parse an RFC2822 header, e.g. From:, to get user and domain.
Cleanup
dkim_free() Destroy a per-message handle of the DKIM service.

An overview of the general use of this API is available here.