tls - The Go Programming Language

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_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
)

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

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
    // 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
}

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
    CipherSuite                uint16
    NegotiatedProtocol         string
    NegotiatedProtocolIsMutual bool

    // ServerName contains the server name indicated by the client, if any.
    // (Only valid for server connections.)
    ServerName string

    // the certificate chain that was presented by the other side
    PeerCertificates []*x509.Certificate
    // the verified certificate chains built from PeerCertificates.
    VerifiedChains [][]*x509.Certificate
}

ConnectionState records basic TLS details about the connection.

previous page start next page