# Overview

[back to index]

To sign a message under DomainKeys Identified Mail ("DKIM"), make the following calls:

1. `lib = dkim_init(...);`
   - initialize an instance of the library
   - this must be done once before any of the other calls are made
   - this needs to be called once when the application is started, but its result can be reused at the start of processing of each message
   - the remaining steps can use the same value of `lib`, even in multiple threads and over multiple messages
2. `dkim = dkim_sign(lib, ...);`
   - initialize a handle set up for signing the message
   - at this point a canonicalization, signing algorithm and secret key are selected by the caller
3. `stat = dkim_header(dkim, ...);`
   - pass a header field to `libopendkim`
   - this should be done once for each header field that should be included in computation of the signature
4. `stat = dkim_eoh(dkim);`
   - notify `libopendkim` that the end of this message's header has been reached
5. `stat = dkim_body(dkim, ...);`
   - pass to `libopendkim` a chunk of the body that should be included in computation of the signature (currently all of it)
   - repeat for each body chunk that arrives
6. `stat = dkim_eom(dkim);`
   - notify `libopendkim` that the end of this message has been reached
7. `stat = dkim_getsighdr(dkim, ...);`
   - compute the base64-encoded signature for the message
   - the signing algorithm was selected in the call to `dkim_sign()` above
   - the entire signature header field is generated and returned into a buffer provided by the caller, so it can be added to the message
8. `stat = dkim_free(dkim);`
   - free resources related to this message
9. `dkim_close(lib);`
   - free resources related to this library instance

To verify a message under DKIM, make the following calls:

1. `lib = dkim_init(...);`
   - initialize an instance of the library
   - this must be done once before any of the other calls are made
   - this needs to be called once when the application is started, but its result can be reused at the start of processing of each message
   - the remaining steps can use the same value of `lib`, even in multiple threads and over multiple messages
2. `dkim = dkim_verify(lib, ...);`
   - initialize a handle set up for verifying the message
   - the canonicalization and signing algorithms and public key were selected by the agent that signed the message, and so don't need to be provided here
3. `stat = dkim_header(dkim, ...);`
   - pass a header field to `libopendkim`
   - this should be done once for each header field that should be included in computation of the digest to be verified (currently all of them)
4. `stat = dkim_eoh(dkim);`
   - notify `libopendkim` that the end of this message's header has been reached
5. `stat = dkim_body(dkim, ...);`
   - pass to `libopendkim` a chunk of the body that should be included in computation of the digest to be verified (currently all of it)
6. `stat = dkim_eom(dkim);`
   - notify `libopendkim` that the end of this message has been reached
   - see if `stat` is `DKIM_STAT_OK` (verification OK) or `DKIM_STAT_BADSIG` (verification failed)
7. `stat = dkim_free(dkim);`
   - free resources related to this message
8. `dkim_close(lib);`
   - free resources related to this library instance

One application, having called `dkim_init()` once, can call `dkim_sign()` or `dkim_verify()` more than once each, and furthermore can have more than one signing/verifying handle in existence at any given time.

Note that new `dkim_chunk()` interface can replace the `dkim_header()`-`dkim_eoh()`-`dkim_body()` sequence for applications that don't have the header fields individually separated.

One can also use new `dkim_getsighdr_d()` in place of `dkim_getsighdr()` to allow larger-than-normal signatures to be generated.

Copyright (c) 2005, 2007, 2008 Sendmail, Inc. and its suppliers. All rights reserved.
Copyright (c) 2009, 2010, The Trusted Domain Project. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the respective licenses.