<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 2008 (1.71)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>TLS API Implementation</TITLE>
<META NAME="description" CONTENT="TLS API Implementation">
<META NAME="keywords" CONTENT="developers">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="developers.css">
<LINK REL="next" HREF="Bnet_API_Changes.html">
<LINK REL="previous" HREF="New_Configuration_Directive.html">
<LINK REL="up" HREF="TLS.html">
<LINK REL="next" HREF="Bnet_API_Changes.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html1386"
HREF="Bnet_API_Changes.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1380"
HREF="TLS.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1374"
HREF="New_Configuration_Directive.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1382"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html1384"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1387"
HREF="Bnet_API_Changes.html">Bnet API Changes</A>
<B> Up:</B> <A NAME="tex2html1381"
HREF="TLS.html">TLS</A>
<B> Previous:</B> <A NAME="tex2html1375"
HREF="New_Configuration_Directive.html">New Configuration Directives</A>
<B> <A NAME="tex2html1383"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html1385"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html1388"
HREF="TLS_API_Implementation.html#SECTION001431000000000000000">Library Initialization and Cleanup</A>
<LI><A NAME="tex2html1389"
HREF="TLS_API_Implementation.html#SECTION001432000000000000000">Manipulating TLS Contexts</A>
<LI><A NAME="tex2html1390"
HREF="TLS_API_Implementation.html#SECTION001433000000000000000">Performing Post-Connection Verification</A>
<LI><A NAME="tex2html1391"
HREF="TLS_API_Implementation.html#SECTION001434000000000000000">Manipulating TLS Connections</A>
</UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION001430000000000000000"></A>
<A NAME="4734"></A>
<A NAME="4735"></A>
<BR>
TLS API Implementation
</H1>
<P>
To facilitate the use of additional TLS libraries, all OpenSSL-specific
code has been implemented within <I>src/lib/tls.c</I>. In turn, a generic
TLS API is exported.
<P>
<H2><A NAME="SECTION001431000000000000000"></A>
<A NAME="4741"></A>
<A NAME="4742"></A>
<BR>
Library Initialization and Cleanup
</H2>
<P>
<PRE>
int init_tls (void);
</PRE>
<P>
Performs TLS library initialization, including seeding of the PRNG. PRNG
seeding has not yet been implemented for win32.
<P>
<PRE>
int cleanup_tls (void);
</PRE>
<P>
Performs TLS library cleanup.
<P>
<H2><A NAME="SECTION001432000000000000000"></A>
<A NAME="4751"></A>
<A NAME="4752"></A>
<BR>
Manipulating TLS Contexts
</H2>
<P>
<PRE>
TLS_CONTEXT *new_tls_context (const char *ca_certfile,
const char *ca_certdir, const char *certfile,
const char *keyfile, const char *dhfile, bool verify_peer);
</PRE>
<P>
Allocates and initalizes a new opaque <I>TLS_CONTEXT</I> structure. The
<I>TLS_CONTEXT</I> structure maintains default TLS settings from which
<I>TLS_CONNECTION</I> structures are instantiated. In the future the
<I>TLS_CONTEXT</I> structure may be used to maintain the TLS session
cache. <I>ca_certfile</I> and <I>ca_certdir</I> arguments are used to
initialize the CA verification stores. The <I>certfile</I> and
<I>keyfile</I> arguments are used to initialize the local certificate and
private key. If <I>dhfile</I> is non-NULL, it is used to initialize
Diffie-Hellman ephemeral keying. If <I>verify_peer</I> is <I>true</I> ,
client certificate validation is enabled.
<P>
<PRE>
void free_tls_context (TLS_CONTEXT *ctx);
</PRE>
<P>
Deallocated a previously allocated <I>TLS_CONTEXT</I> structure.
<P>
<H2><A NAME="SECTION001433000000000000000"></A>
<A NAME="4773"></A>
<A NAME="4774"></A>
<BR>
Performing Post-Connection Verification
</H2>
<P>
<PRE>
bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host);
</PRE>
<P>
Performs post-connection verification of the peer-supplied x509
certificate. Checks whether the <I>subjectAltName</I> and
<I>commonName</I> attributes match the supplied <I>host</I> string.
Returns <I>true</I> if there is a match, <I>false</I> otherwise.
<P>
<PRE>
bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list);
</PRE>
<P>
Performs post-connection verification of the peer-supplied x509
certificate. Checks whether the <I>commonName</I> attribute matches any
strings supplied via the <I>verify_list</I> parameter. Returns
<I>true</I> if there is a match, <I>false</I> otherwise.
<P>
<H2><A NAME="SECTION001434000000000000000"></A>
<A NAME="4792"></A>
<A NAME="4793"></A>
<BR>
Manipulating TLS Connections
</H2>
<P>
<PRE>
TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd);
</PRE>
<P>
Allocates and initializes a new <I>TLS_CONNECTION</I> structure with
context <I>ctx</I> and file descriptor <I>fd</I>.
<P>
<PRE>
void free_tls_connection (TLS_CONNECTION *tls);
</PRE>
<P>
Deallocates memory associated with the <I>tls</I> structure.
<P>
<PRE>
bool tls_bsock_connect (BSOCK *bsock);
</PRE>
<P>
Negotiates a a TLS client connection via <I>bsock</I>. Returns <I>true</I>
if successful, <I>false</I> otherwise. Will fail if there is a TLS
protocol error or an invalid certificate is presented
<P>
<PRE>
bool tls_bsock_accept (BSOCK *bsock);
</PRE>
<P>
Accepts a TLS client connection via <I>bsock</I>. Returns <I>true</I> if
successful, <I>false</I> otherwise. Will fail if there is a TLS protocol
error or an invalid certificate is presented.
<P>
<PRE>
bool tls_bsock_shutdown (BSOCK *bsock);
</PRE>
<P>
Issues a blocking TLS shutdown request to the peer via <I>bsock</I>. This function may not wait for the peer's reply.
<P>
<PRE>
int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes);
</PRE>
<P>
Writes <I>nbytes</I> from <I>ptr</I> via the <I>TLS_CONNECTION</I>
associated with <I>bsock</I>. Due to OpenSSL's handling of <I>EINTR</I>,
<I>bsock</I> is set non-blocking at the start of the function, and restored
to its original blocking state before the function returns. Less than
<I>nbytes</I> may be written if an error occurs. The actual number of
bytes written will be returned.
<P>
<PRE>
int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes);
</PRE>
<P>
Reads <I>nbytes</I> from the <I>TLS_CONNECTION</I> associated with
<I>bsock</I> and stores the result in <I>ptr</I>. Due to OpenSSL's
handling of <I>EINTR</I>, <I>bsock</I> is set non-blocking at the start of
the function, and restored to its original blocking state before the
function returns. Less than <I>nbytes</I> may be read if an error occurs.
The actual number of bytes read will be returned.
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html1386"
HREF="Bnet_API_Changes.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1380"
HREF="TLS.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1374"
HREF="New_Configuration_Directive.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1382"
HREF="Contents.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html1384"
HREF="GNU_Free_Documentation_Lice.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1387"
HREF="Bnet_API_Changes.html">Bnet API Changes</A>
<B> Up:</B> <A NAME="tex2html1381"
HREF="TLS.html">TLS</A>
<B> Previous:</B> <A NAME="tex2html1375"
HREF="New_Configuration_Directive.html">New Configuration Directives</A>
<B> <A NAME="tex2html1383"
HREF="Contents.html">Contents</A></B>
<B> <A NAME="tex2html1385"
HREF="GNU_Free_Documentation_Lice.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
2012-01-24
</ADDRESS>
</BODY>
</HTML>
