An implementation of the Transport Layer Security Protocols

cl-tls

CL-TLS is a prototype Common Lisp implementation 
of TLS and related protocols and standards including:
* RFC5246
* ASN.1
* x{501,509}
* PKCS{1,3,5,8}

TLS is the IETF-standardized successor of Netscape's SSL
protocol. Sometimes TLS/SSL are used interchangeably.
At this point, there is no intention to support the
older versions of the protocols (SSLv3 and below)

The project is currently in its early development
phase and should only be used for experimental
purposes.

CL-TLS uses Ironclad as its cryptographic 
back-end (at the time of writing, the ironclad in quicklisp
has not yet been updated to the new maintained repo,
use sharplispers/ironclad).
See the system definition file for other dependencies

The project started as an attempt to create a 
network-based TLS fuzzer, but soon
morphed of its own volition into a full-fledged 
TLS implementation.

Extensive testing, fuzzing, and code review is needed.
Style guidelines, optimizations, feature-completion 
patches, bug fixes, and other contributions are 
welcome.

For an overview of known attacks against TLS and other
issues relevant to implementors and users, see
https://tools.ietf.org/html/rfc7457
At a minimum, CL-TLS will follow the recommendations
and considerations in the aforementioned document before
a proper alpha release is announced.

I also intend to fully document the internals of CL-TLS.

So far:
* You can initiate sessions and exchange data through a TLS tunnel
  either as a server or a client, for RSA, DSA, and Diffie-Hellman 
  cipher suites. There is no support for ECDSA suites yet.
* Certificate path validation works for 
  certificates signed using RSA or DSA. As above, no support 
  for ECDSA signature verification yet.
* Support for PEM-encoded certificate chains.
* Support for most features of the TLS 1.2 spec such as
  fragmentation and session renegotiation.

Major TODOs before alpha release:
* Finalizing work on hello extensions.
* Fuzzing.
* Speed/Memory optimizations.

Features that would be nice, but are not essential
* Support for initializing with multiple certificates
* ECDSA/ECDH/ECDHE support
* Session resumption support
* Support for post-RFC5246 cipher suites
* rfc{4346,2246,6520}
* pkcs#{7,12}
* DTLS
* Tools for the generation and management of public/private keys and
  certificates
* DANE

CL-TLS does not offer gray streams, threading, sockets, event-loop, or
compression functionality. This limits the code of CL-TLS to simply opening
and managing a TLS tunnel through an octet stream and enhances portability
and extensibility. However, libraries that offer this functionality
(such as threaded or evented servers), can be built trivially
on top of CL-TLS.
See https://github.com/shrdlu68/secure-sockets as an example.

Here is an example of a simple text echo server that
implements a simple one-thread-per-request model using usocket
and bordeaux-threads:

```
(require :cl-tls)

(ql:quickload :bordeaux-threads)
(ql:quickload :usockets)
(ql:quickload :babel)

(defun echo-server (port &optional (host "localhost"))
  (let ((sock (usocket:socket-listen host port
				     :reuse-address t
				     :element-type '(unsigned-byte 8))))
    (cl-tls:initialize-listener
     :certificate "/path/to/cert.pem"
     :private-key "/path/to/key.pem")
    (loop
      for thread-id upfrom 0
      for new-sock = (usocket:socket-accept sock)
      for session-stream = (usocket:socket-stream new-sock)
      for handler = (multiple-value-bind (reader writer)
			(cl-tls:accept-tunnel :io-stream session-stream)
		      (lambda ()
			(loop
			  with id = thread-id
			  for in = (funcall reader)
			  for line = (and in
					  (babel:octets-to-string in))
			  if line do
			    (format t "~&~:R thread received data: ~A~%"
				    id line)
			    (funcall writer in)
			  else do
			    (format t
				    "~&Peer closed tunnel, ~:R thread exiting~%" id)
			    (return nil))))
      do
	 (bordeaux-threads:make-thread handler))))
```

And here is an example using client functionality:

```
(require :cl-tls)
(ql:quickload :babel)

(defun client-test (port &optional (host "localhost"))
  (let* ((sock (usocket:socket-connect
		host port
		:protocol :stream
		:element-type '(unsigned-byte 8))))
    (multiple-value-bind (reader writer close-callback)
	(cl-tls:request-tunnel
	 :certificate "/path/to/cert.pem"
	 :private-key "/path/to/key.pem"
	 :io-stream (usocket:socket-stream sock)
	 :peer-ip-addresses '((127 0 0 1))
	 :ca-certificates "/path/to/CA/ca-cert.pem")
      (loop
	for out = (read-line *standard-input* nil nil)
	for line = (and out
			(babel:string-to-octets out))
	if line do
	  (funcall writer line)
	  (let ((in (funcall reader)))
	    (cond (in
		   (format t "~&Received data: ~A~%"
			   (babel:octets-to-string in)))
		  (t
		   (funcall close-callback)
		   (return nil))))
	else do
	  (format t "~&Closing tunnel...~%")
	  (funcall close-callback)
	  (return nil)))))
```

Preliminary API documentation:

```
request-tunnel (&key certificate private-key ca-certificates
	       	     io-stream input-stream output-stream
		     include-ciphers exclude-ciphers
		     peer-dns-name peer-ip-addresses)

		Attempts to request a TLS tunnel from a server
		through an octet stream
		
		:io-stream A duplex octet stream
		
		:input-stream In the case where separate input and output
			      streams are used, an octet input stream
			      
		:output-stream An octet output stream

		:private-key A (DER/PEM-encoded) private key
			     (currently only DSA, RSA and DH private keys are supported)
			     If the private key is encrypted, you will be prompted for
			     the passphrase
			     
		:certificate A file containing a PEM-encoded list of one
			     or more cerificates
			     The file should consist of one or more
			     ----- BEGIN CERTIFICATE -----
			     ----- END CERTIFICATE -----
			     blocks. White space and other information around these blocks
			     is permitted and will be ignored. Support for PKCS#12-encoded
			     certificate chains is not yet implemented.
		:ca-certificates Either: 1. A directory to look for .crt, .pem, and .der
				 	    CA certificates in
					 2. A PEM-encoded file containing CA certificates,
					    encoded as explained above.
				 For servers, these are only needed if the server
				 needs to authenticate clients, i.e the clients are
				 expected to have client certificates issued to them.
				 This is not used very widely in practice.
				 For clients, CA certificates are used to authenticate
				 servers.
				 TLS clients such as browsers typically use a collection
				 of root certificates that are included by some means of
				 vetting, either provided by the operating system or
				 by the creators/maintainers of the browser.
				 You can use the CAs that your OS/browser has vetted,
				 or you can select which CAs to trust by yourself.
				 For example, most GNU/Linux systems have a package that
				 provides vetted root certificates, typically found in
				 the file "/etc/ssl/certs/ca-certificates.crt"
				 See also: https://curl.haxx.se/docs/sslcerts.html
				 
				 If you want to or have issued your own certificates,
				 include your CA certificate here, either in
				 addition to other CA certificates or as the sole
				 CA certificates. The client and server will only
				 be able to validate remote endpoints whose certificates
				 are signed by a CA certificate that is included,
				 there is no way to "accept" unvalidated certificates.

		
		:include-ciphers A list of symbols of cipher suites to add to the
				 default cipher list.
				 The symbols denote one of the cryptographic characteristics
				 of a cipher suite: key exchange, authentication
				 bulk encryption, mac, digest algorithms, prf, and key sizes.
				 Currently supported options:
				 :rsa-ke (RSA key exchange)
				 :rsa-auth (RSA authentication)
				 :dh (static dh) :dhe (ephemeral dh)
				 :dsa :anon (no authentication-vulnerable to MITM attacks!)
				 :rc4 (broken and prohibited) :3des (broken and prohibited)
				 :aes128 :aes256 :cbc (cipher block chaining mode)
				 :md5 :sha1 :sha256
				 
		:exclude-ciphers A list of symbols of cipher suites to exclude
				 from the default cipher list.
				 :anon, :rc4 and :3des should be excluded by default
				 
		:peer-dns-name DNS-name of the peer. This is checked against
			       the dns-name values in the subject alternative name extension
			       of the certificate presented by the peer.
			       It is also used in the SNI extension, which is important
			       for virtual servers to determine which server the client
			       wants to contact.
		
		:peer-ip-addresses List of IP addresses of the peer
				   This is checked against the ip-address values
				   in the subject alternative name extension
			       	   of the certificate presented by the peer.
```

```
initialize-listener (&key certificate private-key ca-certificates
				include-ciphers exclude-ciphers force-reinitialize
				authenticate-client-p require-authentication-p
				dh-params)
			
		Loads resources needed for a server session and
		sets configuration options
		Servers need to call this once when initializing.
						 
		:authenticate-client-p When true, an attempt to authenticate the client
				       will be made. However, the client may send back an
				       empty certificate if it does not have
				       (an appropriate) certificate. This option defaults
				       to nil
				       
		:require-authentication-p When true, the server will be asked for a
					  certificate, and the connection will
					  fail if the client fails to provide a certificate.
					  This option defaults to nil.

accept-tunnel (&key io-stream input-stream output-stream)
	      => read-callback,write-callback,close-callback

	      Attempts to accept a client's request for a
	      TLS tunnel through an octet stream

		read-callback A closure whose argument list is in the form
			      (&key (eof-error-p nil) (eof-value nil))
			      that returns the contents
			      of one TLS record (2^14 bytes or less).
			      If :eof-error-p is true, the condition cl:end-of-file
			      will be signaled if the TLS tunnel is closed properly
			      (i.e a close_notify alert is received)
			      If :eof-error-p is false, eof-value is returned rather
			      than isgnalling end-of-file.
			      If an error is encountered while attempting to read from
			      the underlying stream (for example is a socket connection
			      is terminated without properly closing the TLS tunnel),
			      the condition cl:stream-error will be signalled.
		write-callback A closure of one argument, an octet vector of arbitrary size,
			       to be sent down the tunnel
			       Attempting to write to a closed TLS tunnel will
			       signal the condition cl:stream-error
			       If an error is encountered while attempting to write to
			       the underlying stream (for example is a socket connection
			       is terminated without properly closing the TLS tunnel),
			       the condition cl:stream-error will be signalled.
		close-callback A closure of no arguments that politely closes the TLS
			       connection by sending a close_notify alert.
```

```
(defclass address ()
  ((host :initarg :host
	 :accessor host)
   (port :initarg :port
	 :accessor port)))
```

```
request-stream-to-address (address)
		 =>octet stream
	Specialize this generic function and provide socket functionality.
	This is needed by some of the functionality in cl-tls that may need
	to open sockets, such as contacting OCSP responders.
	For example, to if you are using usockets:
	(defmethod cl-tls:request-stream-to-address ((addr cl-tls:address))
	  (usocket:socket-stream (usocket:socket-connect
	  (cl-tls:host addr) (cl-tls:port addr)
	  :protocol :stream
	  :element-type '(unsigned-byte 8))))
```

This API will likely change as development continues.


cl-tls

Upstream URL

Author

License

cl-tls

License:

Authors:

Dependencies:

Dependencies (5)

Dependents (2)