From 765abbc1078b6ca326ea0c8d8b5b8dc998940925 Mon Sep 17 00:00:00 2001 From: Karl Cunningham Date: Thu, 21 Jul 2005 14:54:13 +0000 Subject: [PATCH] Adapted for use within Developer's Manual --- docs/developers/tls-techdoc.tex | 139 ++++++++++++++++++++++++-------- 1 file changed, 105 insertions(+), 34 deletions(-) diff --git a/docs/developers/tls-techdoc.tex b/docs/developers/tls-techdoc.tex index ad5a0714..c6015f6c 100644 --- a/docs/developers/tls-techdoc.tex +++ b/docs/developers/tls-techdoc.tex @@ -1,22 +1,20 @@ -\documentclass{article} -\usepackage{graphics} % Packages to allow inclusion of graphics -\usepackage{color} % For creating coloured text and background -\usepackage{hyperref} % For creating hyperlinks in cross references -\usepackage{graphicx} - -\textwidth = 6.5 in -\headheight = 0.0 in -\topmargin = 0.0 in -\oddsidemargin = 0.0 in -\evensidemargin = 0.0 in - -\author{Landon Fuller} -\title{Bacula TLS Additions} -\date{\today} -\begin{document} -\maketitle -\tableofcontents -\section{Introduction} +%% +%% + +%\author{Landon Fuller} +%\title{Bacula TLS Additions} + +\section{TLS} +\label{_Chapter_TLS} +\index{TLS} +\addcontentsline{toc}{section}{TLS} + +Written by Landon Fuller + +\subsection{Introduction to TLS} +\index{TLS Introduction} +\index{Introduction!TLS} +\addcontentsline{toc}{subsection}{TLS Introduction} This patch includes all the back-end code necessary to add complete TLS support to Bacula. In addition, support for TLS in Console/Director @@ -50,7 +48,11 @@ I have submitted the code in \emph{src/lib/tls.c} under the 3 clause BSD license. I prefer the stronger warranty disclaimer of an actual license, but I'm also willing to provide access to the code under the public domain. -\section{New Configuration Directives} +\subsection{New Configuration Directives} +\index{TLS Configuration Directives} +\index{Directives!TLS Configuration} +\addcontentsline{toc}{subsection}{New Configuration Directives} + Additional configuration directives have been added to both the Console and Director resources. These new directives are defined as follows: @@ -100,36 +102,56 @@ Path to PEM encoded Diffie-Hellman parameter file. If this directive is specified, DH ephemeral keying will be enabled, allowing for forward secrecy of communications. This directive is only valid within a server context. To generate the parameter file, you may use openssl: -\begin{verbatim} openssl dhparam -out dh1024.pem -5 1024 \end{verbatim} +\footnotesize +\begin{verbatim} +openssl dhparam -out dh1024.pem -5 1024 +\end{verbatim} +\normalsize \end{itemize} -\section{TLS API Implementation} +\subsection{TLS API Implementation} +\index{TLS API Implimentation} +\index{API Implimentation!TLS} +\addcontentsline{toc}{subsection}{TLS API Implementation} To facilitate the use of additional TLS libraries, all OpenSSL-specific code has been implemented within \emph{src/lib/tls.c}. In turn, a generic TLS API is exported. -\subsection{Library Initialization and Cleanup} +\subsubsection{Library Initialization and Cleanup} +\index{Library Initialization and Cleanup} +\index{Initialization and Cleanup!Library} +\addcontentsline{toc}{subsubsection}{Library Initialization and Cleanup} + +\footnotesize \begin{verbatim} int init_tls (void); \end{verbatim} +\normalsize Performs TLS library initialization, including seeding of the PRNG. PRNG seeding has not yet been implemented for win32. +\footnotesize \begin{verbatim} int cleanup_tls (void); \end{verbatim} +\normalsize Performs TLS library cleanup. -\subsection{Manipulating TLS Contexts} +\subsubsection{Manipulating TLS Contexts} +\index{TLS Context Manipulation} +\index{Contexts!Manipulating TLS} +\addcontentsline{toc}{subsubsection}{Manipulating TLS Contexts} +\footnotesize \begin{verbatim} 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); \end{verbatim} +\normalsize Allocates and initalizes a new opaque \emph{TLS\_CONTEXT} structure. The \emph{TLS\_CONTEXT} structure maintains default TLS settings from which @@ -142,70 +164,96 @@ private key. If \emph{dhfile} is non-NULL, it is used to initialize Diffie-Hellman ephemeral keying. If \emph{verify\_peer} is \emph{true} , client certificate validation is enabled. +\footnotesize \begin{verbatim} void free_tls_context (TLS_CONTEXT *ctx); \end{verbatim} +\normalsize Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. -\subsection{Performing Post-Connection Verification} +\subsubsection{Performing Post-Connection Verification} +\index{TLS Post-Connection Verification} +\index{Verification!TLS Post-Connection} +\addcontentsline{toc}{subsubsection}{Performing Post-Connection Verification} + +\footnotesize \begin{verbatim} bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host); \end{verbatim} +\normalsize Performs post-connection verification of the peer-supplied x509 certificate. Checks whether the \emph{subjectAltName} and \emph{commonName} attributes match the supplied \emph{host} string. Returns \emph{true} if there is a match, \emph{false} otherwise. +\footnotesize \begin{verbatim} bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list); \end{verbatim} +\normalsize Performs post-connection verification of the peer-supplied x509 certificate. Checks whether the \emph{commonName} attribute matches any strings supplied via the \emph{verify\_list} parameter. Returns \emph{true} if there is a match, \emph{false} otherwise. -\subsection{Manipulating TLS Connections} +\subsubsection{Manipulating TLS Connections} +\index{TLS Connection Manipulation} +\index{Connections!Manipulating TLS} +\addcontentsline{toc}{subsubsection}{Manipulating TLS Connections} + +\footnotesize \begin{verbatim} TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd); \end{verbatim} +\normalsize Allocates and initializes a new \emph{TLS\_CONNECTION} structure with context \emph{ctx} and file descriptor \emph{fd}. +\footnotesize \begin{verbatim} void free_tls_connection (TLS_CONNECTION *tls); \end{verbatim} +\normalsize Deallocates memory associated with the \emph{tls} structure. +\footnotesize \begin{verbatim} bool tls_bsock_connect (BSOCK *bsock); \end{verbatim} +\normalsize Negotiates a a TLS client connection via \emph{bsock}. Returns \emph{true} if successful, \emph{false} otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented +\footnotesize \begin{verbatim} bool tls_bsock_accept (BSOCK *bsock); \end{verbatim} +\normalsize Accepts a TLS client connection via \emph{bsock}. Returns \emph{true} if successful, \emph{false} otherwise. Will fail if there is a TLS protocol error or an invalid certificate is presented. +\footnotesize \begin{verbatim} bool tls_bsock_shutdown (BSOCK *bsock); \end{verbatim} +\normalsize Issues a blocking TLS shutdown request to the peer via \emph{bsock}. This function may not wait for the peer's reply. +\footnotesize \begin{verbatim} int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes); \end{verbatim} +\normalsize Writes \emph{nbytes} from \emph{ptr} via the \emph{TLS\_CONNECTION} associated with \emph{bsock}. Due to OpenSSL's handling of \emph{EINTR}, @@ -214,9 +262,11 @@ to its original blocking state before the function returns. Less than \emph{nbytes} may be written if an error occurs. The actual number of bytes written will be returned. +\footnotesize \begin{verbatim} int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes); \end{verbatim} +\normalsize Reads \emph{nbytes} from the \emph{TLS\_CONNECTION} associated with \emph{bsock} and stores the result in \emph{ptr}. Due to OpenSSL's @@ -225,7 +275,10 @@ the function, and restored to its original blocking state before the function returns. Less than \emph{nbytes} may be read if an error occurs. The actual number of bytes read will be returned. -\section{Bnet API Changes} +\subsection{Bnet API Changes} +\index{Bnet API Changes} +\index{API Changes!Bnet} +\addcontentsline{toc}{subsection}{Bnet API Changes} A minimal number of changes were required in the Bnet socket API. The BSOCK structure was expanded to include an associated TLS\_CONNECTION structure, @@ -233,27 +286,38 @@ as well as a flag to designate the current blocking state of the socket. The blocking state flag is required for win32, where it does not appear possible to discern the current blocking state of a socket. -\subsection{Negotiating a TLS Connection} +\subsubsection{Negotiating a TLS Connection} +\index{Negotiating a TLS Connection} +\index{TLS Connection!Negotiating} +\addcontentsline{toc}{subsubsection}{Negotiating a TLS Connection} \emph{bnet\_tls\_server()} and \emph{bnet\_tls\_client()} were both implemented using the new TLS API as follows: +\footnotesize \begin{verbatim} int bnet_tls_client(TLS_CONTEXT *ctx, BSOCK * bsock); \end{verbatim} +\normalsize Negotiates a TLS session via \emph{bsock} using the settings from \emph{ctx}. Returns 1 if successful, 0 otherwise. +\footnotesize \begin{verbatim} int bnet_tls_server(TLS_CONTEXT *ctx, BSOCK * bsock, alist *verify_list); \end{verbatim} +\normalsize Accepts a TLS client session via \emph{bsock} using the settings from \emph{ctx}. If \emph{verify\_list} is non-NULL, it is passed to \emph{tls\_postconnect\_verify\_cn()} for client certificate verification. -\subsection{Manipulating Socket Blocking State} +\subsubsection{Manipulating Socket Blocking State} +\index{Manipulating Socket Blocking State} +\index{Socket Blocking State!Manipulating} +\index{Blocking State!Socket!Manipulating} +\addcontentsline{toc}{subsubsection}{Manipulating Socket Blocking State} Three functions were added for manipulating the blocking state of a socket on both Win32 and Unix-like systems. The Win32 code was written according @@ -261,23 +325,29 @@ to the MSDN documentation, but has not been tested. These functions are prototyped as follows: +\footnotesize \begin{verbatim} int bnet_set_nonblocking (BSOCK *bsock); \end{verbatim} +\normalsize Enables non-blocking I/O on the socket associated with \emph{bsock}. Returns a copy of the socket flags prior to modification. +\footnotesize \begin{verbatim} int bnet_set_blocking (BSOCK *bsock); \end{verbatim} +\normalsize Enables blocking I/O on the socket associated with \emph{bsock}. Returns a copy of the socket flags prior to modification. +\footnotesize \begin{verbatim} void bnet_restore_blocking (BSOCK *bsock, int flags); \end{verbatim} +\normalsize Restores blocking or non-blocking IO setting on the socket associated with \emph{bsock}. The \emph{flags} argument must be the return value of either @@ -285,7 +355,10 @@ Restores blocking or non-blocking IO setting on the socket associated with \pagebreak -\section{Authentication Negotiation} +\subsection{Authentication Negotiation} +\index{Authentication Negotiation} +\index{Negotiation!TLS Authentication} +\addcontentsline{toc}{subsection}{Authentication Negotiation} Backwards compatibility with the existing SSL negotiation hooks implemented in src/lib/cram-md5.c have been maintained. The @@ -296,12 +369,11 @@ advertised by the remote host is returned via this pointer. After exchanging cram-md5 authentication and TLS requirements, both the client and server independently decide whether to continue: +\footnotesize \begin{verbatim} if (!cram_md5_get_auth(dir, password, &tls_remote_need) || !cram_md5_auth(dir, password, tls_local_need)) { -\end{verbatim} [snip] -\begin{verbatim} /* Verify that the remote host is willing to meet our TLS requirements */ if (tls_remote_need < tls_local_need && tls_local_need != BNET_TLS_OK && tls_remote_need != BNET_TLS_OK) { @@ -320,5 +392,4 @@ if (tls_remote_need > tls_local_need && tls_local_need != BNET_TLS_OK && goto auth_done; } \end{verbatim} - -\end{document} +\normalsize -- 2.39.5