Overview

[back to index]

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

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

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.