Overview
To sign a message under DomainKeys Identified Mail ("DKIM"), make the
following calls:
- 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
- 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
- stat = dkim_header(dkim, ...);
- pass a header to libdkim
- this should be done once for each header that should be
included in computation of the signature (currently
all of them)
- stat = dkim_eoh(dkim);
- notify libdkim that the end of this message's headers has
been reached
- stat = dkim_body(dkim, ...);
- pass to libdkim 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
- stat = dkim_eom(dkim);
- notify libdkim that the end of this message has been
reached
- 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 is generated and returned into a
buffer provided by the caller, so it can be added to the message
- stat = dkim_free(dk);
- free resources related to this message
To verify a message under DKIM, make the following calls:
- 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
- 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
- stat = dkim_header(dkim, ...);
- pass a header to libdkim
- this should be done once for each header that should be
included in computation of the digest to be verified (currently
all of them)
- stat = dkim_eoh(dkim);
- notify libdkim that the end of this message's headers has
been reached
- stat = dkim_body(dkim, ...);
- pass to libdkim a chunk of the body that should be
included in computation of the digest to be verified (currently
all of it)
- stat = dkim_eom(dkim);
- notify libdkim that the end of this message has been
reached
- see if stat is DK_STAT_OK (verification OK)
or DK_STAT_BADSIG (verification failed)
- stat = dkim_free(dkim);
- free resources related to this message
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.