auth

Documentation

Overview

Package auth provides methods to perform authorization on incoming or outgoing TLS connections by checking the X.509 certificate of the client or server.

Index

• type ACL
  • func (a ACL) VerifyPeerCertificateClient(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
  • func (a ACL) VerifyPeerCertificateServer(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
• type Logger

Examples

• ACL (Client)
• ACL (Server)

Types

type ACL

type ACL struct {
	// AllowAll will allow all authenticated pricipals. If this option is set,
	// all other options are ignored as all principals with valid certificates
	// will be allowed no matter the subject.
	AllowAll bool
	// AllowCNs lists common names that should be allowed access. If a principal
	// has a valid certificate with at least one of these CNs, we grant access.
	AllowedCNs []string
	// AllowOUs lists organizational units that should be allowed access. If a
	// principal has a valid certificate with at least one of these OUs, we grant
	// access.
	AllowedOUs []string
	// AllowDNSs lists DNS SANs that should be allowed access. If a principal
	// has a valid certificate with at least one of these DNS SANs, we grant
	// access.
	AllowedDNSs []string
	// AllowIPs lists IP SANs that should be allowed access. If a principal
	// has a valid certificate with at least one of these IP SANs, we grant
	// access.
	AllowedIPs []net.IP
	// AllowURIs lists URI SANs that should be allowed access. If a principal
	// has a valid certificate with at least one of these URI SANs, we grant
	// access.
	AllowedURIs []wildcard.Matcher
	// Logger is used to log authorization decisions.
	Logger Logger
}

ACL represents an access control list for mutually-authenticated TLS connections. These options are disjunctive, if at least one attribute matches access will be granted.

Example (Client)

// Configure an access control list for incoming connections.
acl := ACL{
	AllowedCNs: []string{
		// Allow peers with CN 'server1' or 'server2'
		"server1",
		"server2",
	},
}

// Example tls.Config for a TLS server.
_ = tls.Config{
	// Set VerifyPeerCertificate on our tls.Config to point to our access
	// control list. When initiating connections to a TLS server with this
	// config, Go will call our verify function and pass the peer certificates
	// as an argument. The ACL implementation will check that the peer has one
	// of the attributes configured in the ACL before allowing the connection
	// to proceed.
	VerifyPeerCertificate: acl.VerifyPeerCertificateClient,
}

Example (Server)

// Configure an access control list for incoming connections.
acl := ACL{
	AllowedCNs: []string{
		// Allow peers with CN 'client1' or 'client2'
		"client1",
		"client2",
	},
}

// Example tls.Config for a TLS server.
_ = tls.Config{
	// Set VerifyPeerCertificate on our tls.Config to point to our access
	// control list. When accepting connections on a TLS listener with this
	// config, Go will call our verify function and pass the peer certificates
	// as an argument. The ACL implementation will check that the peer has one
	// of the attributes configured in the ACL before allowing the connection
	// to proceed.
	VerifyPeerCertificate: acl.VerifyPeerCertificateServer,
}

func (ACL) VerifyPeerCertificateClient

func (a ACL) VerifyPeerCertificateClient(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error

VerifyPeerCertificateClient is an implementation of VerifyPeerCertificate for crypto/tls.Config for clients initiating TLS connections that will validate the server certificate based on the given ACL. If the ACL is empty, all servers will be allowed (this function assumes that DNS name verification has already taken place, and therefore fails open).

func (ACL) VerifyPeerCertificateServer

func (a ACL) VerifyPeerCertificateServer(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error

VerifyPeerCertificateServer is an implementation of VerifyPeerCertificate for crypto/tls.Config for servers terminating TLS connections that will enforce access controls based on the given ACL. If the given ACL is empty, no clients will be allowed (fails closed).

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

Logger is used by this package to log messages