<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>
