Overview
[back to index]
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 field to libopendkim
       
-  this should be done once for each header field that should be
            included in computation of the signature 
      
 
-  stat = dkim_eoh(dkim);
      
       -  notify libopendkim that the end of this message's header
            has been reached
      
 
-  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
      
 
-  stat = dkim_eom(dkim);
      
       -  notify libopendkim 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 field is generated and returned into a
            buffer provided by the caller, so it can be added to the message
      
 
-  stat = dkim_free(dkim);
      
       -  free resources related to this message
      
 
-  dkim_close(lib);
      
       -  free resources related to this library instance
      
 
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 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)
      
 
-  stat = dkim_eoh(dkim);
      
       -  notify libopendkim that the end of this message's header
            has been reached
      
 
-  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)
      
 
-  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)
      
 
-  stat = dkim_free(dkim);
      
       -  free resources related to this message
      
 
-  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.