Run Format

Package tls

import "crypto/tls"
Overview
Index

Overview ▾

Package tls partially implements TLS 1.2, as specified in RFC 5246.

Constants

const (
        TLS_RSA_WITH_RC4_128_SHA                uint16 = 0x0005
        TLS_RSA_WITH_3DES_EDE_CBC_SHA           uint16 = 0x000a
        TLS_RSA_WITH_AES_128_CBC_SHA            uint16 = 0x002f
        TLS_RSA_WITH_AES_256_CBC_SHA            uint16 = 0x0035
        TLS_ECDHE_ECDSA_WITH_RC4_128_SHA        uint16 = 0xc007
        TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA    uint16 = 0xc009
        TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA    uint16 = 0xc00a
        TLS_ECDHE_RSA_WITH_RC4_128_SHA          uint16 = 0xc011
        TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA     uint16 = 0xc012
        TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA      uint16 = 0xc013
        TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA      uint16 = 0xc014
        TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256   uint16 = 0xc02f
        TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 uint16 = 0xc02b
)

A list of the possible cipher suite ids. Taken from http://www.iana.org/assignments/tls-parameters/tls-parameters.xml

const (
        VersionSSL30 = 0x0300
        VersionTLS10 = 0x0301
        VersionTLS11 = 0x0302
        VersionTLS12 = 0x0303
)

func Listen

func Listen(network, laddr string, config *Config) (net.Listener, error)

Listen creates a TLS listener accepting connections on the given network address using net.Listen. The configuration config must be non-nil and must have at least one certificate.

func NewListener

func NewListener(inner net.Listener, config *Config) net.Listener

NewListener creates a Listener which accepts connections from an inner Listener and wraps each connection with Server. The configuration config must be non-nil and must have at least one certificate.

type Certificate

type Certificate struct {
        Certificate [][]byte
        PrivateKey  crypto.PrivateKey // supported types: *rsa.PrivateKey, *ecdsa.PrivateKey
        // OCSPStaple contains an optional OCSP response which will be served
        // to clients that request it.
        OCSPStaple []byte
        // Leaf is the parsed form of the leaf certificate, which may be
        // initialized using x509.ParseCertificate to reduce per-handshake
        // processing for TLS clients doing client authentication. If nil, the
        // leaf certificate will be parsed as needed.
        Leaf *x509.Certificate
}

A Certificate is a chain of one or more certificates, leaf first.

func LoadX509KeyPair

func LoadX509KeyPair(certFile, keyFile string) (cert Certificate, err error)

LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data.

func X509KeyPair

func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (cert Certificate, err error)

X509KeyPair parses a public/private key pair from a pair of PEM encoded data.

type ClientAuthType

type ClientAuthType int

ClientAuthType declares the policy the server will follow for TLS Client Authentication.

const (
        NoClientCert ClientAuthType = iota
        RequestClientCert
        RequireAnyClientCert
        VerifyClientCertIfGiven
        RequireAndVerifyClientCert
)

type Config

type Config struct {
        // Rand provides the source of entropy for nonces and RSA blinding.
        // If Rand is nil, TLS uses the cryptographic random reader in package
        // crypto/rand.
        Rand io.Reader

        // Time returns the current time as the number of seconds since the epoch.
        // If Time is nil, TLS uses time.Now.
        Time func() time.Time

        // Certificates contains one or more certificate chains
        // to present to the other side of the connection.
        // Server configurations must include at least one certificate.
        Certificates []Certificate

        // NameToCertificate maps from a certificate name to an element of
        // Certificates. Note that a certificate name can be of the form
        // '*.example.com' and so doesn't have to be a domain name as such.
        // See Config.BuildNameToCertificate
        // The nil value causes the first element of Certificates to be used
        // for all connections.
        NameToCertificate map[string]*Certificate

        // RootCAs 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.
        RootCAs *x509.CertPool

        // NextProtos is a list of supported, application level protocols.
        NextProtos []string

        // ServerName is included in the client's handshake to support virtual
        // hosting.
        ServerName string

        // ClientAuth determines the server's policy for
        // TLS Client Authentication. The default is NoClientCert.
        ClientAuth ClientAuthType

        // ClientCAs defines the set of root certificate authorities
        // that servers use if required to verify a client certificate
        // by the policy in ClientAuth.
        ClientCAs *x509.CertPool

        // InsecureSkipVerify controls whether a client verifies the
        // server's certificate chain and host name.
        // If InsecureSkipVerify is true, TLS accepts any certificate
        // presented by the server and any host name in that certificate.
        // In this mode, TLS is susceptible to man-in-the-middle attacks.
        // This should be used only for testing.
        InsecureSkipVerify bool

        // CipherSuites is a list of supported cipher suites. If CipherSuites
        // is nil, TLS uses a list of suites supported by the implementation.
        CipherSuites []uint16

        // PreferServerCipherSuites controls whether the server selects the
        // client's most preferred ciphersuite, or the server's most preferred
        // ciphersuite. If true then the server's preference, as expressed in
        // the order of elements in CipherSuites, is used.
        PreferServerCipherSuites bool

        // SessionTicketsDisabled may be set to true to disable session ticket
        // (resumption) support.
        SessionTicketsDisabled bool

        // SessionTicketKey is used by TLS servers to provide session
        // resumption. See RFC 5077. If zero, it will be filled with
        // random data before the first server handshake.
        //
        // If multiple servers are terminating connections for the same host
        // they should all have the same SessionTicketKey. If the
        // SessionTicketKey leaks, previously recorded and future TLS
        // connections using that key are compromised.
        SessionTicketKey [32]byte

        // MinVersion contains the minimum SSL/TLS version that is acceptable.
        // If zero, then SSLv3 is taken as the minimum.
        MinVersion uint16

        // MaxVersion contains the maximum SSL/TLS version that is acceptable.
        // If zero, then the maximum version supported by this package is used,
        // which is currently TLS 1.2.
        MaxVersion uint16
        // contains filtered or unexported fields
}

A Config structure is used to configure a TLS client or server. After one has been passed to a TLS function it must not be modified.

func (*Config) BuildNameToCertificate

func (c *Config) BuildNameToCertificate()

BuildNameToCertificate parses c.Certificates and builds c.NameToCertificate from the CommonName and SubjectAlternateName fields of each of the leaf certificates.

type Conn

type Conn struct {
        // contains filtered or unexported fields
}

A Conn represents a secured connection. It implements the net.Conn interface.

func Client

func Client(conn net.Conn, config *Config) *Conn

Client returns a new TLS client side connection using conn as the underlying transport. Client interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults.

func Dial

func Dial(network, addr string, config *Config) (*Conn, error)

Dial connects to the given network address using net.Dial and then initiates a TLS handshake, returning the resulting TLS connection. Dial interprets a nil configuration as equivalent to the zero configuration; see the documentation of Config for the defaults.

func Server

func Server(conn net.Conn, config *Config) *Conn

Server returns a new TLS server side connection using conn as the underlying transport. The configuration config must be non-nil and must have at least one certificate.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection.

func (*Conn) ConnectionState

func (c *Conn) ConnectionState() ConnectionState

ConnectionState returns basic TLS details about the connection.

func (*Conn) Handshake

func (c *Conn) Handshake() error

Handshake runs the client or server handshake protocol if it has not yet been run. Most uses of this package need not call Handshake explicitly: the first Read or Write will call it automatically.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*Conn) OCSPResponse

func (c *Conn) OCSPResponse() []byte

OCSPResponse returns the stapled OCSP response from the TLS server, if any. (Only valid for client connections.)

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

Read can be made to time out and return a net.Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. A zero value for t means Read and Write will not time out. After a Write has timed out, the TLS state is corrupt and all future writes will return the same error.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline on the underlying connection. A zero value for t means Read will not time out.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline on the underlying conneciton. A zero value for t means Write will not time out. After a Write has timed out, the TLS state is corrupt and all future writes will return the same error.

func (*Conn) VerifyHostname

func (c *Conn) VerifyHostname(host string) error

VerifyHostname checks that the peer certificate chain is valid for connecting to host. If so, it returns nil; if not, it returns an error describing the problem.

func (*Conn) Write

func (c *Conn) Write(b []byte) (int, error)

Write writes data to the connection.

type ConnectionState

type ConnectionState struct {
        HandshakeComplete          bool                  // TLS handshake is complete
        DidResume                  bool                  // connection resumes a previous TLS connection
        CipherSuite                uint16                // cipher suite in use (TLS_RSA_WITH_RC4_128_SHA, ...)
        NegotiatedProtocol         string                // negotiated next protocol (from Config.NextProtos)
        NegotiatedProtocolIsMutual bool                  // negotiated protocol was advertised by server
        ServerName                 string                // server name requested by client, if any (server side only)
        PeerCertificates           []*x509.Certificate   // certificate chain presented by remote peer
        VerifiedChains             [][]*x509.Certificate // verified chains built from PeerCertificates
}

ConnectionState records basic TLS details about the connection.