channelbinding

README

go-channelbinding: Go library to create TLS channel binding data for use with authentcation protocols

go-channelbinding provides TLS Channel Binding support as defined in RFC 5929:

• tls-unique: binds to an individual TLS connection
• tls-endpoint: binds to the server's TLS certificate

These bindings are available for TLS versions prior to TLS1.3 only, and are subject to issues related to session resumption and renegotiation, as described in this miTLS paper. Please take time to read and understand the limitations before relying on channel bindings to secure authentication protocols.

Example

package main

import (
	"crypto/tls"
	"fmt"
	"os"

	cb "github.com/golang-auth/go-channelbinding"
)

func main() {
	tlsConf := tls.Config{MaxVersion: tls.VersionTLS12}

	conn, err := tls.Dial("tcp", "ldap.example.com:636", &tlsConf)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	tlsState := conn.ConnectionState()
	data, err := cb.MakeTLSChannelBinding(tlsState, tlsState.PeerCertificates[0], cb.TLSChannelBindingEndpoint)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

	// use data...
	_ = data
}

TLS 1.3

TLS 1.3 does not define the tls-unqiue and tls-endpoint bindings due to the security concerns outlined in the referenced miTLS paper. A draft proposal has been created to close that gap, and that is experimentially supported by the TLSChannelBindingExporter binding type. Note however that at this time the author knows of no test vectors or other implemtations.

Documentation

Overview

Package channelbinding provides TLS Channel Binding support as defined in RFC 5929:

tls-unique:   binds to an individual TLS connection
tls-endpoint: binds to the server's TLS certificate

These bindings are available for TLS versions prior to TLS1.3 only, and are subject to issues related to session resumption and renegotiation, as described in https://mitls.org/pages/attacks/3SHAKE#channelbindings. Please take time to read and understand the limitations before relying on channel bindings to secure authentication protocols.

Index

• Constants
• func MakeTLSChannelBinding(state tls.ConnectionState, serverCert *x509.Certificate, ...) (cbData []byte, err error)
• type TLSChannelBindingType

Constants

const (
	TLSChannelBindingNone = iota
	TLSChannelBindingUnique
	TLSChannelBindingEndpoint
	TLSChannelBindingExporter
)

Supported TLS channel binding types

Functions

func MakeTLSChannelBinding

func MakeTLSChannelBinding(state tls.ConnectionState, serverCert *x509.Certificate, bindingType TLSChannelBindingType) (cbData []byte, err error)

MakeTLSChannelBinding creates the TLS channel binding data for a given binding type.

Unfortunately it is not possible to determine whether the caller is the client or server from the ConncetionState alone. Therefore, serverCert must be passed when requesting TLSCHannelBindingEndpoint binding. For a client, this value is state.PeerCertificates[0]. Determining which certificate to use for a server is more complex when multiple server certs are used (eg. when making use of SNI), and this is left to the caller to determine.

serverCert may be nil when requesting TLSChannelBindingUnique binding.

A request for TLSChannelBindingUnique will fail if TLS1.3 is in use, or if session resumption is enabled.

A request for TLSChannelBindingEndpoint will fail if TLS1.3 is in use or no serverCert is supplied.

The returned data is suitable for passing to SASL or GSSAPI authentication mechanisms.

Note that it is the caller's responsibility to ensure that session renegotiation does not occur between the time that MakeTLSChannelBinding() is called and the end of the authentication phase of the application protocol.

The TLSChannelBindingExporter binding type is experimental.

Types

type TLSChannelBindingType

type TLSChannelBindingType int

TLSChannelBindingType defines a TLS Channel Binding type