4 %\author{Landon Fuller}
5 %\title{Bacula TLS Additions}
10 \addcontentsline{toc}{section}{TLS}
12 Written by Landon Fuller
14 \subsection{Introduction to TLS}
15 \index{TLS Introduction}
16 \index{Introduction!TLS}
17 \addcontentsline{toc}{subsection}{TLS Introduction}
19 This patch includes all the back-end code necessary to add complete TLS
20 support to Bacula. In addition, support for TLS in Console/Director
21 communications has been added as a proof of concept. Adding support for
22 the remaining daemons will be straight-forward. Supported features of this
25 \item Client/Server TLS Requirement Negotiation
26 \item TLSv1 Connections with Server and Client Certificate
28 \item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying
31 This document will refer to both ``server'' and ``client'' contexts. These
32 terms refer to the accepting and initiating peer, respectively.
34 Diffie-Hellman anonymous ciphers are not supported by this patchset. The
35 use of DH anonymous ciphers increases the code complexity and places
36 explicit trust upon the two-way Cram-MD5 implementation. Cram-MD5 is
37 subject to known plaintext attacks, and is should be considered
38 considerably less secure than PKI certificate-based authentication.
40 Appropriate autoconf macros have been added to detect and use OpenSSL. Two
41 additional preprocessor defines have been added: \emph{HAVE\_TLS} and
42 \emph{HAVE\_OPENSSL}. All changes not specific to OpenSSL rely on
43 \emph{HAVE\_TLS}. OpenSSL-specific code is constrained to
44 \emph{src/lib/tls.c} to facilitate the support of alternative TLS
47 I have submitted the code in \emph{src/lib/tls.c} under the 3 clause BSD
48 license. I prefer the stronger warranty disclaimer of an actual license,
49 but I'm also willing to provide access to the code under the public domain.
51 \subsection{New Configuration Directives}
52 \index{TLS Configuration Directives}
53 \index{Directives!TLS Configuration}
54 \addcontentsline{toc}{subsection}{New Configuration Directives}
56 Additional configuration directives have been added to both the Console and
57 Director resources. These new directives are defined as follows:
60 \item \underline{TLS Enable} \emph{(yes/no)}
63 \item \underline{TLS Require} \emph{(yes/no)}
64 Require TLS connections.
66 \item \underline{TLS Certificate} \emph{(path)}
67 Path to PEM encoded TLS certificate. Used as either a client or server
70 \item \underline{TLS Key} \emph{(path)}
71 Path to PEM encoded TLS private key. Must correspond with the TLS
74 \item \underline{TLS Verify Peer} \emph{(yes/no)}
75 Verify peer certificate. Instructs server to request and verify the
76 client's x509 certificate. Any client certificate signed by a known-CA
77 will be accepted unless the TLS Allowed CN configuration directive is used.
78 Not valid in a client context.
80 \item \underline{TLS Allowed CN} \emph{(string list)}
81 Common name attribute of allowed peer certificates. If directive is
82 specified, all client certificates will be verified against this list.
83 This directive may be specified more than once. Not valid in a client
86 \item \underline{TLS CA Certificate File} \emph{(path)}
87 Path to PEM encoded TLS CA certificate(s). Multiple certificates are
88 permitted in the file. One of \emph{TLS CA Certificate File} or \emph{TLS
89 CA Certificate Dir} are required in a server context if \underline{TLS
90 Verify Peer} is also specified, and are always required in a client
93 \item \underline{TLS CA Certificate Dir} \emph{(path)}
94 Path to TLS CA certificate directory. In the current implementation,
95 certificates must be stored PEM encoded with OpenSSL-compatible hashes.
96 One of \emph{TLS CA Certificate File} or \emph{TLS CA Certificate Dir} are
97 required in a server context if \emph{TLS Verify Peer} is also specified,
98 and are always required in a client context.
100 \item \underline{TLS DH File} \emph{(path)}
101 Path to PEM encoded Diffie-Hellman parameter file. If this directive is
102 specified, DH ephemeral keying will be enabled, allowing for forward
103 secrecy of communications. This directive is only valid within a server
104 context. To generate the parameter file, you may use openssl:
107 openssl dhparam -out dh1024.pem -5 1024
112 \subsection{TLS API Implementation}
113 \index{TLS API Implimentation}
114 \index{API Implimentation!TLS}
115 \addcontentsline{toc}{subsection}{TLS API Implementation}
117 To facilitate the use of additional TLS libraries, all OpenSSL-specific
118 code has been implemented within \emph{src/lib/tls.c}. In turn, a generic
121 \subsubsection{Library Initialization and Cleanup}
122 \index{Library Initialization and Cleanup}
123 \index{Initialization and Cleanup!Library}
124 \addcontentsline{toc}{subsubsection}{Library Initialization and Cleanup}
132 Performs TLS library initialization, including seeding of the PRNG. PRNG
133 seeding has not yet been implemented for win32.
137 int cleanup_tls (void);
141 Performs TLS library cleanup.
143 \subsubsection{Manipulating TLS Contexts}
144 \index{TLS Context Manipulation}
145 \index{Contexts!Manipulating TLS}
146 \addcontentsline{toc}{subsubsection}{Manipulating TLS Contexts}
150 TLS_CONTEXT *new_tls_context (const char *ca_certfile,
151 const char *ca_certdir, const char *certfile,
152 const char *keyfile, const char *dhfile, bool verify_peer);
156 Allocates and initalizes a new opaque \emph{TLS\_CONTEXT} structure. The
157 \emph{TLS\_CONTEXT} structure maintains default TLS settings from which
158 \emph{TLS\_CONNECTION} structures are instantiated. In the future the
159 \emph{TLS\_CONTEXT} structure may be used to maintain the TLS session
160 cache. \emph{ca\_certfile} and \emph{ca\_certdir} arguments are used to
161 initialize the CA verification stores. The \emph{certfile} and
162 \emph{keyfile} arguments are used to initialize the local certificate and
163 private key. If \emph{dhfile} is non-NULL, it is used to initialize
164 Diffie-Hellman ephemeral keying. If \emph{verify\_peer} is \emph{true} ,
165 client certificate validation is enabled.
169 void free_tls_context (TLS_CONTEXT *ctx);
173 Deallocated a previously allocated \emph{TLS\_CONTEXT} structure.
175 \subsubsection{Performing Post-Connection Verification}
176 \index{TLS Post-Connection Verification}
177 \index{Verification!TLS Post-Connection}
178 \addcontentsline{toc}{subsubsection}{Performing Post-Connection Verification}
182 bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host);
186 Performs post-connection verification of the peer-supplied x509
187 certificate. Checks whether the \emph{subjectAltName} and
188 \emph{commonName} attributes match the supplied \emph{host} string.
189 Returns \emph{true} if there is a match, \emph{false} otherwise.
193 bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list);
197 Performs post-connection verification of the peer-supplied x509
198 certificate. Checks whether the \emph{commonName} attribute matches any
199 strings supplied via the \emph{verify\_list} parameter. Returns
200 \emph{true} if there is a match, \emph{false} otherwise.
202 \subsubsection{Manipulating TLS Connections}
203 \index{TLS Connection Manipulation}
204 \index{Connections!Manipulating TLS}
205 \addcontentsline{toc}{subsubsection}{Manipulating TLS Connections}
209 TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd);
213 Allocates and initializes a new \emph{TLS\_CONNECTION} structure with
214 context \emph{ctx} and file descriptor \emph{fd}.
218 void free_tls_connection (TLS_CONNECTION *tls);
222 Deallocates memory associated with the \emph{tls} structure.
226 bool tls_bsock_connect (BSOCK *bsock);
230 Negotiates a a TLS client connection via \emph{bsock}. Returns \emph{true}
231 if successful, \emph{false} otherwise. Will fail if there is a TLS
232 protocol error or an invalid certificate is presented
236 bool tls_bsock_accept (BSOCK *bsock);
240 Accepts a TLS client connection via \emph{bsock}. Returns \emph{true} if
241 successful, \emph{false} otherwise. Will fail if there is a TLS protocol
242 error or an invalid certificate is presented.
246 bool tls_bsock_shutdown (BSOCK *bsock);
250 Issues a blocking TLS shutdown request to the peer via \emph{bsock}. This function may not wait for the peer's reply.
254 int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes);
258 Writes \emph{nbytes} from \emph{ptr} via the \emph{TLS\_CONNECTION}
259 associated with \emph{bsock}. Due to OpenSSL's handling of \emph{EINTR},
260 \emph{bsock} is set non-blocking at the start of the function, and restored
261 to its original blocking state before the function returns. Less than
262 \emph{nbytes} may be written if an error occurs. The actual number of
263 bytes written will be returned.
267 int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes);
271 Reads \emph{nbytes} from the \emph{TLS\_CONNECTION} associated with
272 \emph{bsock} and stores the result in \emph{ptr}. Due to OpenSSL's
273 handling of \emph{EINTR}, \emph{bsock} is set non-blocking at the start of
274 the function, and restored to its original blocking state before the
275 function returns. Less than \emph{nbytes} may be read if an error occurs.
276 The actual number of bytes read will be returned.
278 \subsection{Bnet API Changes}
279 \index{Bnet API Changes}
280 \index{API Changes!Bnet}
281 \addcontentsline{toc}{subsection}{Bnet API Changes}
283 A minimal number of changes were required in the Bnet socket API. The BSOCK
284 structure was expanded to include an associated TLS\_CONNECTION structure,
285 as well as a flag to designate the current blocking state of the socket.
286 The blocking state flag is required for win32, where it does not appear
287 possible to discern the current blocking state of a socket.
289 \subsubsection{Negotiating a TLS Connection}
290 \index{Negotiating a TLS Connection}
291 \index{TLS Connection!Negotiating}
292 \addcontentsline{toc}{subsubsection}{Negotiating a TLS Connection}
294 \emph{bnet\_tls\_server()} and \emph{bnet\_tls\_client()} were both
295 implemented using the new TLS API as follows:
299 int bnet_tls_client(TLS_CONTEXT *ctx, BSOCK * bsock);
303 Negotiates a TLS session via \emph{bsock} using the settings from
304 \emph{ctx}. Returns 1 if successful, 0 otherwise.
308 int bnet_tls_server(TLS_CONTEXT *ctx, BSOCK * bsock, alist *verify_list);
312 Accepts a TLS client session via \emph{bsock} using the settings from
313 \emph{ctx}. If \emph{verify\_list} is non-NULL, it is passed to
314 \emph{tls\_postconnect\_verify\_cn()} for client certificate verification.
316 \subsubsection{Manipulating Socket Blocking State}
317 \index{Manipulating Socket Blocking State}
318 \index{Socket Blocking State!Manipulating}
319 \index{Blocking State!Socket!Manipulating}
320 \addcontentsline{toc}{subsubsection}{Manipulating Socket Blocking State}
322 Three functions were added for manipulating the blocking state of a socket
323 on both Win32 and Unix-like systems. The Win32 code was written according
324 to the MSDN documentation, but has not been tested.
326 These functions are prototyped as follows:
330 int bnet_set_nonblocking (BSOCK *bsock);
334 Enables non-blocking I/O on the socket associated with \emph{bsock}.
335 Returns a copy of the socket flags prior to modification.
339 int bnet_set_blocking (BSOCK *bsock);
343 Enables blocking I/O on the socket associated with \emph{bsock}. Returns a
344 copy of the socket flags prior to modification.
348 void bnet_restore_blocking (BSOCK *bsock, int flags);
352 Restores blocking or non-blocking IO setting on the socket associated with
353 \emph{bsock}. The \emph{flags} argument must be the return value of either
354 \emph{bnet\_set\_blocking()} or \emph{bnet\_restore\_blocking()}.
358 \subsection{Authentication Negotiation}
359 \index{Authentication Negotiation}
360 \index{Negotiation!TLS Authentication}
361 \addcontentsline{toc}{subsection}{Authentication Negotiation}
363 Backwards compatibility with the existing SSL negotiation hooks implemented
364 in src/lib/cram-md5.c have been maintained. The
365 \emph{cram\_md5\_get\_auth()} function has been modified to accept an
366 integer pointer argument, tls\_remote\_need. The TLS requirement
367 advertised by the remote host is returned via this pointer.
369 After exchanging cram-md5 authentication and TLS requirements, both the
370 client and server independently decide whether to continue:
374 if (!cram_md5_get_auth(dir, password, &tls_remote_need) ||
375 !cram_md5_auth(dir, password, tls_local_need)) {
377 /* Verify that the remote host is willing to meet our TLS requirements */
378 if (tls_remote_need < tls_local_need && tls_local_need != BNET_TLS_OK &&
379 tls_remote_need != BNET_TLS_OK) {
380 sendit(_("Authorization problem:"
381 " Remote server did not advertise required TLS support.\n"));
382 auth_success = false;
386 /* Verify that we are willing to meet the remote host's requirements */
387 if (tls_remote_need > tls_local_need && tls_local_need != BNET_TLS_OK &&
388 tls_remote_need != BNET_TLS_OK) {
389 sendit(_("Authorization problem:"
390 " Remote server requires TLS.\n"));
391 auth_success = false;