tls

Documentation

Index

• func CipherProtectedPrivateKeyPEMToDER(pemData, passphrase []byte) ([]byte, string, error)
• func NewConfig(options ...Option) (*tls.Config, error)
• func NewConfigWithKeyAndCert(certFile, keyFile string, passphrase []byte, options ...Option) (*tls.Config, error)
• func NewConfigWithP12(p12File string, passphrase []byte, options ...Option) (*tls.Config, error)
• func TLSCertificateFromP12(p12File string, passphrase []byte) (tls.Certificate, error)
• type Option
  • func CipherSuitesOption(cipherSuites ...uint16) Option
  • func ClientAuthTypeOption(clientAuth tls.ClientAuthType) Option
  • func ClientCAsOption(clientCAs ...string) Option
  • func CurvePreferencesOption(curvePreferences ...tls.CurveID) Option
  • func DynamicRecordSizingDisabledOption(dynamicRecordSizingDisabled bool) Option
  • func GetConfigForClientOption(getConfigForClientFunc func(*tls.ClientHelloInfo) (*tls.Config, error)) Option
  • func InsecureSkipVerifyOption(insecureSkipVerify bool) Option
  • func KeyLogWriterOption(keyLogWriter io.Writer) Option
  • func MaxVersionOption(maxVersion uint16) Option
  • func MinVersionOption(minVersion uint16) Option
  • func RenegotiationOption(renegotiation tls.RenegotiationSupport) Option
  • func RootCAsOption(rootCAs ...string) Option
  • func ServerNameOption(serverName string) Option
  • func SessionTicketsDisabledOption(sessionTicketsDisabled bool) Option
  • func VerifyConnectionOption(verifyConnectionFunc func(tls.ConnectionState) error) Option
  • func VerifyPeerCertificateOption(...) Option

Functions

func CipherProtectedPrivateKeyPEMToDER

func CipherProtectedPrivateKeyPEMToDER(pemData, passphrase []byte) ([]byte, string, error)

CipherProtectedPrivateKeyPEMToDER decrypts a passphrase-protected, PEM-encoded private-key and returns its unprotected DER representation and its block type.

func NewConfig

func NewConfig(options ...Option) (*tls.Config, error)

NewConfig ...

func NewConfigWithKeyAndCert

func NewConfigWithKeyAndCert(certFile, keyFile string, passphrase []byte,
	options ...Option) (*tls.Config, error)

NewConfigWithKeyAndCert returns a TLS configuration suitable for an endpoint with its private key stored in keyFile and corresponding certificate stored in certFile. If the private key is passphrase-protected, the credential cred is used to unlock the the key, otherwise cred is expected to be nil. rootCAs defines a list of root CA filenames. Note: It appears as if ICAs have to be loaded via a chained server certificate file as the RootCAs pool in tls.Config appears to be referred to for RCAs only.

func NewConfigWithP12

func NewConfigWithP12(p12File string, passphrase []byte, options ...Option) (*tls.Config, error)

NewConfigWithP12 ...

func TLSCertificateFromP12

func TLSCertificateFromP12(p12File string, passphrase []byte) (tls.Certificate, error)

TLSCertificateFromP12 decrypts a PKCS#12 encoded key-bundle and returns the corresponding tls.Certificate representation. NOTE to support "modern" PBE-encryption schemes, the "frozen" Go stdlib PKCS#12 package golang.org/x/crypto is insufficient. Unfortunately, software.sslmate.com/src/go-pkcs12 has quite some dependencies. See the commented code below, to restrict support to legacy algorithms only.

Types

type Option

type Option func(*tls.Config) error

Option configures a *tls.Config.

func CipherSuitesOption

func CipherSuitesOption(cipherSuites ...uint16) Option

CipherSuitesOption is a list of enabled TLS 1.0–1.2 cipher suites. The order of the list is ignored. Note that TLS 1.3 ciphersuites are not configurable. If CipherSuites is nil, a safe default list is used. The default cipher suites might change over time.

func ClientAuthTypeOption

func ClientAuthTypeOption(clientAuth tls.ClientAuthType) Option

ClientAuthTypeOption determines the server's policy for TLS Client Authentication. The default is NoClientCert.

func ClientCAsOption

func ClientCAsOption(clientCAs ...string) Option

ClientCAsOption defines the set of root certificate authorities that servers use if required to verify a client certificate by the policy in ClientAuth.

func CurvePreferencesOption

func CurvePreferencesOption(curvePreferences ...tls.CurveID) Option

CurvePreferencesOption contains the elliptic curves that will be used in an ECDHE handshake, in preference order. If empty, the default will be used. The client will use the first preference as the type for its key share in TLS 1.3. This may change in the future.

func DynamicRecordSizingDisabledOption

func DynamicRecordSizingDisabledOption(dynamicRecordSizingDisabled bool) Option

DynamicRecordSizingDisabledOption disables adaptive sizing of TLS records. When true, the largest possible TLS record size is always used. When false, the size of TLS records may be adjusted in an attempt to improve latency.

func GetConfigForClientOption

func GetConfigForClientOption(
	getConfigForClientFunc func(*tls.ClientHelloInfo) (*tls.Config, error)) Option

GetConfigForClientOption if not nil, is called after a ClientHello is received from a client. It may return a non-nil Config in order to change the Config that will be used to handle this connection. If the returned Config is nil, the original Config will be used. The Config returned by this callback may not be subsequently modified.

If GetConfigForClient is nil, the Config passed to Server() will be used for all connections.

If SessionTicketKey was explicitly set on the returned Config, or if SetSessionTicketKeys was called on the returned Config, those keys will be used. Otherwise, the original Config keys will be used (and possibly rotated if they are automatically managed).

func InsecureSkipVerifyOption

func InsecureSkipVerifyOption(insecureSkipVerify bool) Option

InsecureSkipVerifyOption controls whether a client verifies the server's certificate chain and host name. If InsecureSkipVerify is true, crypto/tls accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. This should be used only for testing or in combination with VerifyConnection or VerifyPeerCertificate.

func KeyLogWriterOption

func KeyLogWriterOption(keyLogWriter io.Writer) Option

KeyLogWriterOption optionally specifies a destination for TLS master secrets in NSS key log format that can be used to allow external programs such as Wireshark to decrypt TLS connections. See https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Key_Log_Format. Use of KeyLogWriter compromises security and should only be used for debugging.

func MaxVersionOption

func MaxVersionOption(maxVersion uint16) Option

MaxVersionOption contains the maximum TLS version that is acceptable. If zero, the maximum version supported by this package is used, which is currently TLS 1.3.

func MinVersionOption

func MinVersionOption(minVersion uint16) Option

MinVersionOption contains the minimum TLS version that is acceptable. If zero, TLS 1.0 is currently taken as the minimum.

func RenegotiationOption

func RenegotiationOption(renegotiation tls.RenegotiationSupport) Option

RenegotiationOption controls what types of renegotiation are supported. The default, none, is correct for the vast majority of applications.

func RootCAsOption

func RootCAsOption(rootCAs ...string) Option

RootCAsOption defines the set of root certificate authorities that clients use when verifying server certificates. If RootCAs is nil, TLS uses the host's root CA set.

func ServerNameOption

func ServerNameOption(serverName string) Option

ServerNameOption ServerName is used to verify the hostname on the returned certificates unless InsecureSkipVerify is given. It is also included in the client's handshake to support virtual hosting unless it is an IP address.

func SessionTicketsDisabledOption

func SessionTicketsDisabledOption(sessionTicketsDisabled bool) Option

SessionTicketsDisabledOption may be set to true to disable session ticket and PSK (resumption) support. Note that on clients, session ticket support is also disabled if ClientSessionCache is nil.

func VerifyConnectionOption

func VerifyConnectionOption(
	verifyConnectionFunc func(tls.ConnectionState) error) Option

VerifyConnectionOption if not nil, is called after normal certificate verification and after VerifyPeerCertificate by either a TLS client or server. If it returns a non-nil error, the handshake is aborted and that error results.

If normal verification fails then the handshake will abort before considering this callback. This callback will run for all connections regardless of InsecureSkipVerify or ClientAuth settings.

func VerifyPeerCertificateOption

func VerifyPeerCertificateOption(
	verifyPeerCertificateFunc func(rawCerts [][]byte,
		verifiedChains [][]*x509.Certificate) error) Option

VerifyPeerCertificateOption if not nil, is called after normal certificate verification by either a TLS client or server. It receives the raw ASN.1 certificates provided by the peer and also any verified chains that normal processing found. If it returns a non-nil error, the handshake is aborted and that error results.

If normal verification fails then the handshake will abort before considering this callback. If normal verification is disabled by setting InsecureSkipVerify, or (for a server) when ClientAuth is RequestClientCert or RequireAnyClientCert, then this callback will be considered but the verifiedChains argument will always be nil.