README
¶
package peerauth 
Package peerauth implements utility functions for TLS peer authentication.
See godoc.org for documentation and example/ for a code example.
Documentation
¶
Overview ¶
Package peerauth implements utility functions for TLS peer authentication.
Peer Authentication vs Client Authentication ¶
TLS client authentication is a mechanism to ensure authenticated and encrypted communication between a client and a server.
The client verifies the signer of the server's certificate against its trusted certificate authority pool (RootCA pool). If the server's certificate was signed by a trusted RootCA, the client will usually validate the certificate's CommonName and SubjectAlternativeName.
To authenticate the client towards the server, the client presents a certificate signed by a ClientCA, and the server checks if that ClientCA is in the server's trusted ClientCAs pool. If so, the server can base further policy decisions on the information contained in the client's certificate, e.g. from the CommonName field.
However, situation exist in which no centrally trusted authorities like the RootCA or ClientCA exist, and other TLS functionality like centralized revocation, etc., is not required. In those cases, it may be desirable to avoid the burden of managing a CA, and use TLS peer authentication instead.
Key Generation ¶
Each node generates a key-pair and a self-signs a certificate containing the public key with its private key. An out-of-band mechanism is then used to distribute the certificates of each node to each other.
Mutual Authentication ¶
A server S that wishes to accept connections from a node N adds N's certificate to its client certificate pool. A client C that wishes to connect to a server S adds S's certificate to its root CA pool. Under the assumption that keypairs are never shared, this configuration authenticates server to client and client to server.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateFiles ¶
func GenerateFiles(g Generator, args GeneratorArgs, outpathStem string) (crtPath, keyPath string, err error)
GenerateFiles generates a keypair + certificate with the given generator and writes the generated PEM data out to `outpathStem + {.crt,.key}` with restrictive permissions (0444,0400). It does not overwrite files, and rolls back (=removes) files it generated if one write fails. Remove failures are silently ignored.
Example ¶
genArgs := GeneratorArgs{
CommonName: "client1",
NotBefore: time.Now(),
NotAfter: time.Now().Add(365 * 24 * time.Hour),
}
cert, key, err := GenerateFiles(RSA096, genArgs, "client1")
if err != nil {
log.Panic(err)
}
log.Printf("crt: %q", cert)
log.Printf("key: %q", key)
Output: crt: "client1.crt" key: "client1.key"
func TLSConfigClient ¶
Example ¶
conf, err := TLSConfigClient("client.crt", "client.key", "server.crt")
if err != nil {
log.Panic(err)
}
tls.Dial("tcp", "server:12345", conf)
func TLSConfigServer ¶
TLSConfigServer generates a *tls.Config for peer authentication. All arguments specify paths to PEM-encoded files, e.g. generated by one of this package's Generators.
`cert` is the certificate of the server, `key` is the corresponding private key. Each entry in `remotes` is a path to an acceptable certificate of a client.
Example ¶
conf, err := TLSConfigServer("server.crt", "server.key", []string{"client1.crt", "client2.crt"})
if err != nil {
log.Panic(err)
}
tls.Listen("tcp", ":12345", conf)
Types ¶
type Generator ¶
type Generator func(args GeneratorArgs) (certPEM, keyPEM []byte, err error)
A Generator produces a keypair + certificate encoded in PEM format, parametrized by GeneratorArgs.
var ( // RSA4096 generates a 4096bit RSA keypair + certificate. RSA096 Generator = rsa4096 )
type GeneratorArgs ¶
type GeneratorArgs struct {
// The CommonName in the certificate.
CommonName string
// The validity dates of the certificate.
NotBefore, NotAfter time.Time
}
func (*GeneratorArgs) Validate ¶
func (a *GeneratorArgs) Validate() error
Source Files
Directories