pktls

README

pktls

DO NOT USE THIS (YET), UNAUDITED, PRE-RELEASE.

Description

A Go library to allow using wireguard-style asymmetric keys to configure mutual TLS authentication.

.-------------.
| Server      |
|-------------|                      .--------------.
| server.priv |                      | Client 1     |
|             | <---- TLS -----.---- |--------------|
| client1.pub |                |     | client1.priv |
| client2.pub |                |     | server.pub   |
'-------------'                |     '--------------'
                               |     .--------------.
                               |     | Client 2     |
                               '---- |--------------|
                                     | client2.priv |
                                     | server.pub   |
                                     '--------------'

No more having to deal with openssl, CAs, expiring certificates, and complex x509 bootstrap - just use genkey/pubkey!

Under the hood, it uses ED25519 to generate self-signed certificates for both sides.o

Key Generation

go get code.hackerspace.pl/q3k/pktls
go build code.hackerspace.pl/q3k/pktls/cmd/pktls

./pktls genkey > server.priv
./pktls pubkey < server.priv > server.pub

The resulting keys look very much like wireguard keys, but are not compatible. pktls keys will not work as wireguard keys, and vice-versa.

Library usage

On the server side:

pk, err := pktls.ServerFromString("<private key>", []string{"<client public key>", "<client public key>"}) 
config := tls.Config{}
pk.Configure(&config)
// Use config with tls.Listen, grpc/credentials.NewTLS, etc.

On the client side:

pk, err := pktls.ClientFromString("<private key>", "<server public key>")
config := tls.Config{}
pk.Configure(&config)
// Use config with tls.Dial, grpc/credentials.NewTLS, etc.

For example code, see cmd/test{srv,cl}.

Sample client/server

To test this library without writing Go, you can run a pktls server/client pair as following:

go get code.hackerspace.pl/q3k/pktls
go build code.hackerspace.pl/q3k/pktls/cmd/pktls

./pktls genkey > server.priv
./pktls pubkey < server.priv > server.pub
./pktls genkey > client.priv
./pktls pubkey < client.priv > client.pub

# dependency required for test{srv,cl}, but 'go get' outside of a module won't
# download it for us.
go get github.com/golang/glog

go build code.hackerspace.pl/q3k/pktls/cmd/testsrv
./testsrv -private_key $(cat server.priv) -allowed $(cat client.pub) -listen 127.0.0.1:1337

# and on another terminal:
go build code.hackerspace.pl/q3k/pktls/cmd/testcl
./testcl -private_key $(cat client.priv) -remote_key $(cat server.pub) -remote 127.0.0.1:1337

You should observe the client receiving a hello message from the server (”yo”), and the server being able to introspect the identity of the client.

Documentation

Index

• Variables
• type ClientConfig
  • func ClientFromString(privkey string, server string) (*ClientConfig, error)
  • func (c *ClientConfig) Configure(config *tls.Config) error
  • func (c *ClientConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error
• type Config
• type PrivateKey
  • func PrivateFromString(s string) (PrivateKey, error)
  • func PrivateGenerate() (PrivateKey, error)
  • func (p PrivateKey) GenerateTLS(mode TLSMode) (*tls.Certificate, error)
  • func (p PrivateKey) Public() PublicKey
  • func (p PrivateKey) String() string
• type PublicKey
  • func ClientPubkey(c net.Conn) (*PublicKey, error)
  • func PublicFromString(s string) (PublicKey, error)
  • func (p PublicKey) String() string
  • func (p PublicKey) Verify(mode TLSMode, pem []byte) error
• type ServerConfig
  • func ServerFromString(privkey string, allowed []string) (*ServerConfig, error)
  • func (s *ServerConfig) Configure(config *tls.Config) error
  • func (s *ServerConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error
• type TLSMode

Variables

var (
	ErrWrongIdentity = errors.New("unknown identity")
)

Types

type ClientConfig

type ClientConfig struct {
	Config
	Server PublicKey
}

func ClientFromString

func ClientFromString(privkey string, server string) (*ClientConfig, error)

func (*ClientConfig) Configure

func (c *ClientConfig) Configure(config *tls.Config) error

func (*ClientConfig) VerifyPeerCertificate

func (c *ClientConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error

type Config

type Config struct {
	PrivateKey PrivateKey
}

type PrivateKey

type PrivateKey ed25519.PrivateKey

func PrivateFromString

func PrivateFromString(s string) (PrivateKey, error)

func PrivateGenerate

func PrivateGenerate() (PrivateKey, error)

func (PrivateKey) GenerateTLS

func (p PrivateKey) GenerateTLS(mode TLSMode) (*tls.Certificate, error)

func (PrivateKey) Public

func (p PrivateKey) Public() PublicKey

func (PrivateKey) String

func (p PrivateKey) String() string

type PublicKey

type PublicKey ed25519.PublicKey

func ClientPubkey

func ClientPubkey(c net.Conn) (*PublicKey, error)

func PublicFromString

func PublicFromString(s string) (PublicKey, error)

func (PublicKey) String

func (p PublicKey) String() string

func (PublicKey) Verify

func (p PublicKey) Verify(mode TLSMode, pem []byte) error

type ServerConfig

type ServerConfig struct {
	Config
	Allowed []PublicKey
}

func ServerFromString

func ServerFromString(privkey string, allowed []string) (*ServerConfig, error)

func (*ServerConfig) Configure

func (s *ServerConfig) Configure(config *tls.Config) error

func (*ServerConfig) VerifyPeerCertificate

func (s *ServerConfig) VerifyPeerCertificate(rawCerts [][]byte, _ [][]*x509.Certificate) error

type TLSMode

type TLSMode int

const (
	TLSServer TLSMode = iota
	TLSClient
)