-\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
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:
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
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},
\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
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,
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
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
\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
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) {
goto auth_done;
}
\end{verbatim}
-
-\end{document}
+\normalsize
projects / bacula / docs / commitdiff