<html> <head> <title>Overview</title> </head> <body> <!-- $Id: overview.html,v 1.4 2010/07/24 04:52:15 cm-msk Exp $ --> <h1>Overview</h1> <p align="right"><a href="index.html">[back to index]</a></p> To sign a message under <b>DomainKeys Identified Mail</b> ("DKIM"), make the following calls: <ol> <li> <tt>lib = <a href="dkim_init.html">dkim_init(...)</a>;</tt> <ul> <li> initialize an instance of the library <li> this must be done once before any of the other calls are made <li> 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 <li> the remaining steps can use the same value of <tt>lib</tt>, even in multiple threads and over multiple messages </ul> <li> <tt>dkim = <a href="dkim_sign.html">dkim_sign(lib, ...)</a>;</tt> <ul> <li> initialize a handle set up for signing the message <li> at this point a canonicalization, signing algorithm and secret key are selected by the caller </ul> <li> <tt>stat = <a href="dkim_header.html">dkim_header(dkim, ...)</a>;</tt> <ul> <li> pass a header field to <tt>libopendkim</tt> <li> this should be done once for each header field that should be included in computation of the signature </ul> <li> <tt>stat = <a href="dkim_eoh.html">dkim_eoh(dkim)</a>;</tt> <ul> <li> notify <tt>libopendkim</tt> that the end of this message's header has been reached </ul> <li> <tt>stat = <a href="dkim_body.html">dkim_body(dkim, ...)</a>;</tt> <ul> <li> pass to <tt>libopendkim</tt> a chunk of the body that should be included in computation of the signature (currently all of it) <li> repeat for each body chunk that arrives </ul> <li> <tt>stat = <a href="dkim_eom.html">dkim_eom(dkim)</a>;</tt> <ul> <li> notify <tt>libopendkim</tt> that the end of this message has been reached </ul> <li> <tt>stat = <a href="dkim_getsighdr.html">dkim_getsighdr(dkim, ...)</a>;</tt> <ul> <li> compute the base64-encoded signature for the message <li> the signing algorithm was selected in the call to <tt>dkim_sign()</tt> above <li> the entire signature header field is generated and returned into a buffer provided by the caller, so it can be added to the message </ul> <li> <tt>stat = <a href="dkim_free.html">dkim_free(dkim)</a>;</tt> <ul> <li> free resources related to this message </ul> <li> <tt><a href="dkim_close.html">dkim_close(lib)</a>;</tt> <ul> <li> free resources related to this library instance </ul> </ol> <br> To verify a message under <b>DKIM</b>, make the following calls: <ol> <li> <tt>lib = <a href="dkim_init.html">dkim_init(...)</a>;</tt> <ul> <li> initialize an instance of the library <li> this must be done once before any of the other calls are made <li> 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 <li> the remaining steps can use the same value of <tt>lib</tt>, even in multiple threads and over multiple messages </ul> <li> <tt>dkim = <a href="dkim_verify.html">dkim_verify(lib, ...)</a>;</tt> <ul> <li> initialize a handle set up for verifying the message <li> 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 </ul> <li> <tt>stat = <a href="dkim_header.html">dkim_header(dkim, ...)</a>;</tt> <ul> <li> pass a header field to <tt>libopendkim</tt> <li> 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) </ul> <li> <tt>stat = <a href="dkim_eoh.html">dkim_eoh(dkim)</a>;</tt> <ul> <li> notify <tt>libopendkim</tt> that the end of this message's header has been reached </ul> <li> <tt>stat = <a href="dkim_body.html">dkim_body(dkim, ...)</a>;</tt> <ul> <li> pass to <tt>libopendkim</tt> a chunk of the body that should be included in computation of the digest to be verified (currently all of it) </ul> <li> <tt>stat = <a href="dkim_eom.html">dkim_eom(dkim)</a>;</tt> <ul> <li> notify <tt>libopendkim</tt> that the end of this message has been reached <li> see if <tt>stat</tt> is <tt>DKIM_STAT_OK</tt> (verification OK) or <tt>DKIM_STAT_BADSIG</tt> (verification failed) </ul> <li> <tt>stat = <a href="dkim_free.html">dkim_free(dkim)</a>;</tt> <ul> <li> free resources related to this message </ul> <li> <tt><a href="dkim_close.html">dkim_close(lib)</a>;</tt> <ul> <li> free resources related to this library instance </ul> </ol> <br> One application, having called <tt>dkim_init()</tt> once, can call <tt>dkim_sign()</tt> or <tt>dkim_verify()</tt> more than once each, and furthermore can have more than one signing/verifying handle in existence at any given time. <p> Note that new <tt>dkim_chunk()</tt> interface can replace the <tt>dkim_header()</tt>-<tt>dkim_eoh()</tt>-<tt>dkim_body()</tt> sequence for applications that don't have the header fields individually separated. <p> One can also use new <tt>dkim_getsighdr_d()</tt> in place of <tt>dkim_getsighdr()</tt> to allow larger-than-normal signatures to be generated. <p> <hr size="1"> <font size="-1"> Copyright (c) 2005, 2007, 2008 Sendmail, Inc. and its suppliers. All rights reserved. <br> Copyright (c) 2009, 2010, The OpenDKIM Project. All rights reserved. <br> By using this file, you agree to the terms and conditions set forth in the respective licenses. </font> </body> </html>