# Sendmail DomainKeys Library

## Introduction

DomainKeys is a specification for signing messages at the domain level using simple crypto 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.

The specification of DomainKeys is contained in an Internet Draft from Yahoo!, Inc. More information can be found here.

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

## Data Types

Data Type | Description
`DK` | A signing/verifying context for a message.
`dk_alg_t` | A signature generation/verification method.
`dk_canon_t` | A canonicalization method.
`DK_FLAGS` | Flags; a union the following macros, representing flag bits:
`DK_LIB` | An instance of the `libdk` service.
`dk_query_t` | Query method.
`dk_sigkey_t` | Private key data.
`DK_STAT` | Return value/status.

## Functions

Function | Description
Administration
`dk_close()` | Shut down an instance of the DomainKeys service.
`dk_init()` | Initialize an instance of the DomainKeys service.
Signing
`dk_sign()` | Allocate a new DomainKeys handle for signing a message.
`dk_getsig()` | Generate and return a signature.
`dk_gethdrs()` | Retrieve a list of headers included in the computation of the signature.
`dk_getidentity()` | Retrieve sender identity information extracted from headers.
Verifying
`dk_verify()` | Allocate a new DomainKeys handle for verifying a message.
`dk_reportinfo()` | Retrieve information required to generate a verification failure report. (EXPERIMENTAL)
`dkim_geterror()` | Retrieve the most recent internal error message associated with a DK handle.
Processing
`dk_header()` | Process a header.
`dk_eoh()` | Identify end of headers.
`dk_body()` | Process a body chunk.
`dk_eom()` | Identify end of message.
Utility
`dk_options()` | Get or set library options.
`dk_timeout()` | Get or set DNS timeout value.
`rfc2822_mailbox_split()` | Parse an RFC2822 header, e.g. `From:`, to get user and domain.
Cleanup
`dk_free()` | Destroy a per-message handle of the DomainKeys service.

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