<!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> 2010-06-14 </ADDRESS> </BODY> </HTML>