mint

README

mint - A Minimal TLS 1.3 stack

This project is primarily a learning effort for me to understand the TLS 1.3 protocol. The goal is to arrive at a pretty complete implementation of TLS 1.3, with minimal, elegant code that demonstrates how things work. Testing is a priority to ensure correctness, but otherwise, the quality of the software engineering might not be at a level where it makes sense to integrate this with other libraries. Backward compatibility is not an objective.

We borrow liberally from the Go TLS library, especially where TLS 1.3 aligns with earlier TLS versions. However, unnecessary parts will be ruthlessly cut off.

Quickstart

Installation is the same as for any other Go package:

go get github.com/bifurcation/mint

The API is pretty much the same as for the TLS module, with Dial and Listen methods wrapping the underlying socket APIs.

conn, err := mint.Dial("tcp", "localhost:4430", &mint.Config{...})
...
listener, err := mint.Listen("tcp", "localhost:4430", &mint.Config{...})

Documentation is available on godoc.org

Interoperability testing

The mint-client and mint-server executables are included to make it easy to do basic interoperability tests with othe TLS 1.3 implementations. The steps for testing against NSS are as follows.

# Install mint
go get github.com/bifurcation/mint

# Install and build NSS
cd $NSS_ROOT # wherever you want to put NSS
hg clone $nss
hg clone $nspr
cd nss
USE_64=1 ENABLE_TLS_1_3=1 BUILD_GTESTS=1 make nss_build_all

# Run NSS tests (this creates data for the server to use)
cd tests
NSS_TESTS=ssl_gtests NSS_CYCLES=standard ./all.sh

# Test with client=mint server=NSS (fill in $PLATFORM and $HOST as needed)
cd $NSS_ROOT
SSLTRACE=100 DYLD_LIBRARY_PATH=dist/$PLATFORM/lib/ dist/$PLATFORM/bin/selfserv -d tests_results/security/$HOST/ssl_gtests/ -n server -p 4430
# ...
go run $GOPATH/src/github.com/bifurcation/mint/bin/mint-client/main.go

# Test with client=NSS server=mint (fill in $PLATFORM and $HOST as needed)
cd $NSS_ROOT
SSLTRACE=100 DYLD_LIBRARY_PATH=dist/$PLATFORM/lib/ dist/$PLATFORM/bin/tstclnt -d tests_results/security/$HOST/ssl_gtests/ -V tls1.3:tls1.3 -h 127.0.0.1 -p 4430 -o -O
# ...
go run $GOPATH/src/github.com/bifurcation/mint/bin/mint-server/main.go

Documentation

Index

• Constants
• func Listen(network, laddr string, config *Config) (net.Listener, error)
• func NewListener(inner net.Listener, config *Config) net.Listener
• type Config
• type Conn
  • func Client(conn net.Conn, config *Config) *Conn
  • func Dial(network, addr string, config *Config) (*Conn, error)
  • func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error)
  • func Server(conn net.Conn, config *Config) *Conn
  • func (c *Conn) Close() error
  • func (c *Conn) Handshake() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(buffer []byte) (int, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(buffer []byte) (int, error)

Constants

const (
	// REQUIRED
	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 cipherSuite = 0xC02B
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   cipherSuite = 0xC02F
	// RECOMMENDED
	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       cipherSuite = 0xC02C
	TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 cipherSuite = 0xCCA9
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         cipherSuite = 0xC030
	TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   cipherSuite = 0xCCA8
)

Functions

func Listen

func Listen(network, laddr string, config *Config) (net.Listener, error)

Listen creates a TLS listener accepting connections on the given network address using net.Listen. The configuration config must be non-nil and must include at least one certificate or else set GetCertificate.

func NewListener

func NewListener(inner net.Listener, config *Config) net.Listener

NewListener creates a Listener which accepts connections from an inner Listener and wraps each connection with Server. The configuration config must be non-nil and must include at least one certificate or else set GetCertificate.

Types

type Config

type Config struct {
	// TODO
	ServerName string
}

Config is the struct used to pass configuration settings to a TLS client or server instance. The settings for client and server are pretty different, but we just throw them all in here.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn implements the net.Conn interface, as with "crypto/tls" * Read, Write, and Close are provided locally * LocalAddr, RemoteAddr, and Set*Deadline are forwarded to the inner Conn

func Client

func Client(conn net.Conn, config *Config) *Conn

Client returns a new TLS client side connection using conn as the underlying transport. The config cannot be nil: users must set either ServerName or InsecureSkipVerify in the config.

func Dial

func Dial(network, addr string, config *Config) (*Conn, error)

Dial connects to the given network address using net.Dial and then initiates a TLS handshake, returning the resulting TLS connection. Dial interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults.

func DialWithDialer

func DialWithDialer(dialer *net.Dialer, network, addr string, config *Config) (*Conn, error)

DialWithDialer connects to the given network address using dialer.Dial and then initiates a TLS handshake, returning the resulting TLS connection. Any timeout or deadline given in the dialer apply to connection and TLS handshake as a whole.

DialWithDialer interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults.

func Server

func Server(conn net.Conn, config *Config) *Conn

Server returns a new TLS server side connection using conn as the underlying transport. The configuration config must be non-nil and must include at least one certificate or else set GetCertificate.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) Handshake

func (c *Conn) Handshake() error

Handshake causes a TLS handshake on the connection. The `isClient` member determines whether a client or server handshake is performed. If a handshake has already been performed, then its result will be returned.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Conn) Read

func (c *Conn) Read(buffer []byte) (int, error)

Read application data until the buffer is full. Handshake and alert records are consumed by the Conn object directly.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. A zero value for t means Read and Write will not time out. After a Write has timed out, the TLS state is corrupt and all future writes will return the same error.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline on the underlying connection. A zero value for t means Read will not time out.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline on the underlying connection. A zero value for t means Write will not time out. After a Write has timed out, the TLS state is corrupt and all future writes will return the same error.

func (*Conn) Write

func (c *Conn) Write(buffer []byte) (int, error)

Write application data