README
¶
mtls - TLS Mutual Authentication
What is it?
A small Go library and utility for generating TLS mutual authentication certificates and key pairs.
Per Wikipedia:
Mutual authentication or two-way authentication refers to two parties
authenticating each other at the same time, being a default mode of
authentication in some protocols (IKE, SSH) and optional in others (TLS).
In other words, the server will reject the client if the client does not provide the correct certificate and key, and the client will reject the server if the server does not provide the correct certificate and key.
This authentication method is particularly useful for services running on an end user's machine, or for services with only one consumer. This package provides automation for generating the certificate and private key.
How do I use the application?
By default, the application creates a certificate.crt and a
private-key.pem in the current working directory. These two files are
needed to facilitate TLS mutual authentication by both the client and
the server.
There are several use cases which may change how you use the application.
If you would like to generate a mTLS pair for an IP address, do the following:
$ mtls -o "Junk, Inc." -i 127.0.0.1
If you would like to generate a mTLS pair that supports several organizations,
separate them by pipes |:
$ mtls -o 'Junk, Inc.|Better Junk LLC.' -i 127.0.0.1
If you would like to generate a mTLS pair that supports several IP addresses,
separate them by commas ,:
$ mtls -o "Junk, Inc." -i 192.168.1.10,192.168.2.5
If you would like to generate a mTLS pair for a DNS address:
$ mtls -o "Junk, Inc." -d mycoolsite.com
If you would like to generate a mTLS pair that supports several DNS addresses,
separate them by commas ,:
$ mtls -o "Junk, Inc." -d mycoolsite.com,anothersite.net
You can view additional examples by running the application with -x:
$ mtls -x
TLS mutual authentication in a server
The following steps describe how to run a web server that uses mTLS.
- Run the included example server:
$ go run cmd/mtls-server-example/main.go
- In a separate terminal, execute
curl:
$ curl \
--cacert certificate.crt \
--cert certificate.crt \
--key private-key.pem \
-X 'GET' \
https://127.0.0.1:8888/test
TLS mutual authentication in a client
Please refer to the mtls-client-example application.
Documentation
¶
Overview ¶
Package mtls provides both a library and an application for creating TLS mutual authentication certificate and private key pairs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateBlocks ¶
func CreateBlocks(organizationNames []string, optionalIps []net.IP, optionalDomainNames []string, expiration time.Time) (certificate *pem.Block, privateKey *pem.Block, err error)
CreateBlocks creates a certificate and private key pair for TLS mutual authentication in the block format. Domain names and IP addresses are optional. If you do not wish to specify one or the other, simply set the value to nil or to an empty list.
func CreateFiles ¶
func CreateFiles(organizationNames []string, optionalIps []net.IP, optionalDomainNames []string, expiration time.Time, privateKeyOutPath string, certOutPath string) error
CreateFiles creates a certificate and private key pair for TLS mutual authentication at the specified locations. If the specified files already exist, then they will be overwritten. Domain names and IP addresses are optional. If you do not wish to specify one or the other, simply set the value to nil or to an empty list.
Types ¶
This section is empty.
Source Files
Directories