// Copyright 2012 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. package tls import ( "crypto/aes" "crypto/cipher" "crypto/hmac" "crypto/sha256" "crypto/subtle" "crypto/x509" "errors" "io" "golang.org/x/crypto/cryptobyte" ) // A SessionState is a resumable session. type SessionState struct { // Encoded as a SessionState (in the language of RFC 8446, Section 3). // // enum { server(1), client(2) } SessionStateType; // // opaque Certificate<1..2^24-1>; // // Certificate CertificateChain<0..2^24-1>; // // opaque Extra<0..2^24-1>; // // struct { // uint16 version; // SessionStateType type; // uint16 cipher_suite; // uint64 created_at; // opaque secret<1..2^8-1>; // Extra extra<0..2^24-1>; // uint8 ext_master_secret = { 0, 1 }; // uint8 early_data = { 0, 1 }; // CertificateEntry certificate_list<0..2^24-1>; // CertificateChain verified_chains<0..2^24-1>; /* excluding leaf */ // select (SessionState.early_data) { // case 0: Empty; // case 1: opaque alpn<1..2^8-1>; // }; // select (SessionState.type) { // case server: Empty; // case client: struct { // select (SessionState.version) { // case VersionTLS10..VersionTLS12: Empty; // case VersionTLS13: struct { // uint64 use_by; // uint32 age_add; // }; // }; // }; // }; // } SessionState; // // Extra is ignored by crypto/tls, but is encoded by [SessionState.Bytes] // and parsed by [ParseSessionState]. // // This allows [Config.UnwrapSession]/[Config.WrapSession] and // [ClientSessionCache] implementations to store and retrieve additional // data alongside this session. // // To allow different layers in a protocol stack to share this field, // applications must only append to it, not replace it, and must use entries // that can be recognized even if out of order (for example, by starting // with an id and version prefix). Extra [][]byte // EarlyData indicates whether the ticket can be used for 0-RTT in a QUIC // connection. The application may set this to false if it is true to // decline to offer 0-RTT even if supported. EarlyData bool version uint16 isClient bool cipherSuite uint16 // createdAt is the generation time of the secret on the sever (which for // TLS 1.0–1.2 might be earlier than the current session) and the time at // which the ticket was received on the client. createdAt uint64 // seconds since UNIX epoch secret []byte // master secret for TLS 1.2, or the PSK for TLS 1.3 extMasterSecret bool peerCertificates []*x509.Certificate activeCertHandles []*activeCert ocspResponse []byte scts [][]byte verifiedChains [][]*x509.Certificate alpnProtocol string // only set if EarlyData is true // Client-side TLS 1.3-only fields. useBy uint64 // seconds since UNIX epoch ageAdd uint32 } // Bytes encodes the session, including any private fields, so that it can be // parsed by [ParseSessionState]. The encoding contains secret values critical // to the security of future and possibly past sessions. // // The specific encoding should be considered opaque and may change incompatibly // between Go versions. func (s *SessionState) Bytes() ([]byte, error) { var b cryptobyte.Builder b.AddUint16(s.version) if s.isClient { b.AddUint8(2) // client } else { b.AddUint8(1) // server } b.AddUint16(s.cipherSuite) addUint64(&b, s.createdAt) b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { b.AddBytes(s.secret) }) b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) { for _, extra := range s.Extra { b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) { b.AddBytes(extra) }) } }) if s.extMasterSecret { b.AddUint8(1) } else { b.AddUint8(0) } if s.EarlyData { b.AddUint8(1) } else { b.AddUint8(0) } marshalCertificate(&b, Certificate{ Certificate: certificatesToBytesSlice(s.peerCertificates), OCSPStaple: s.ocspResponse, SignedCertificateTimestamps: s.scts, }) b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) { for _, chain := range s.verifiedChains { b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) { // We elide the first certificate because it's always the leaf. if len(chain) == 0 { b.SetError(errors.New("tls: internal error: empty verified chain")) return } for _, cert := range chain[1:] { b.AddUint24LengthPrefixed(func(b *cryptobyte.Builder) { b.AddBytes(cert.Raw) }) } }) } }) if s.EarlyData { b.AddUint8LengthPrefixed(func(b *cryptobyte.Builder) { b.AddBytes([]byte(s.alpnProtocol)) }) } if s.isClient { if s.version >= VersionTLS13 { addUint64(&b, s.useBy) b.AddUint32(s.ageAdd) } } return b.Bytes() } func certificatesToBytesSlice(certs []*x509.Certificate) [][]byte { s := make([][]byte, 0, len(certs)) for _, c := range certs { s = append(s, c.Raw) } return s } // ParseSessionState parses a [SessionState] encoded by [SessionState.Bytes]. func ParseSessionState(data []byte) (*SessionState, error) { ss := &SessionState{} s := cryptobyte.String(data) var typ, extMasterSecret, earlyData uint8 var cert Certificate var extra cryptobyte.String if !s.ReadUint16(&ss.version) || !s.ReadUint8(&typ) || (typ != 1 && typ != 2) || !s.ReadUint16(&ss.cipherSuite) || !readUint64(&s, &ss.createdAt) || !readUint8LengthPrefixed(&s, &ss.secret) || !s.ReadUint24LengthPrefixed(&extra) || !s.ReadUint8(&extMasterSecret) || !s.ReadUint8(&earlyData) || len(ss.secret) == 0 || !unmarshalCertificate(&s, &cert) { return nil, errors.New("tls: invalid session encoding") } for !extra.Empty() { var e []byte if !readUint24LengthPrefixed(&extra, &e) { return nil, errors.New("tls: invalid session encoding") } ss.Extra = append(ss.Extra, e) } switch extMasterSecret { case 0: ss.extMasterSecret = false case 1: ss.extMasterSecret = true default: return nil, errors.New("tls: invalid session encoding") } switch earlyData { case 0: ss.EarlyData = false case 1: ss.EarlyData = true default: return nil, errors.New("tls: invalid session encoding") } for _, cert := range cert.Certificate { c, err := globalCertCache.newCert(cert) if err != nil { return nil, err } ss.activeCertHandles = append(ss.activeCertHandles, c) ss.peerCertificates = append(ss.peerCertificates, c.cert) } ss.ocspResponse = cert.OCSPStaple ss.scts = cert.SignedCertificateTimestamps var chainList cryptobyte.String if !s.ReadUint24LengthPrefixed(&chainList) { return nil, errors.New("tls: invalid session encoding") } for !chainList.Empty() { var certList cryptobyte.String if !chainList.ReadUint24LengthPrefixed(&certList) { return nil, errors.New("tls: invalid session encoding") } var chain []*x509.Certificate if len(ss.peerCertificates) == 0 { return nil, errors.New("tls: invalid session encoding") } chain = append(chain, ss.peerCertificates[0]) for !certList.Empty() { var cert []byte if !readUint24LengthPrefixed(&certList, &cert) { return nil, errors.New("tls: invalid session encoding") } c, err := globalCertCache.newCert(cert) if err != nil { return nil, err } ss.activeCertHandles = append(ss.activeCertHandles, c) chain = append(chain, c.cert) } ss.verifiedChains = append(ss.verifiedChains, chain) } if ss.EarlyData { var alpn []byte if !readUint8LengthPrefixed(&s, &alpn) { return nil, errors.New("tls: invalid session encoding") } ss.alpnProtocol = string(alpn) } if isClient := typ == 2; !isClient { if !s.Empty() { return nil, errors.New("tls: invalid session encoding") } return ss, nil } ss.isClient = true if len(ss.peerCertificates) == 0 { return nil, errors.New("tls: no server certificates in client session") } if ss.version < VersionTLS13 { if !s.Empty() { return nil, errors.New("tls: invalid session encoding") } return ss, nil } if !s.ReadUint64(&ss.useBy) || !s.ReadUint32(&ss.ageAdd) || !s.Empty() { return nil, errors.New("tls: invalid session encoding") } return ss, nil } // sessionState returns a partially filled-out [SessionState] with information // from the current connection. func (c *Conn) sessionState() (*SessionState, error) { return &SessionState{ version: c.vers, cipherSuite: c.cipherSuite, createdAt: uint64(c.config.time().Unix()), alpnProtocol: c.clientProtocol, peerCertificates: c.peerCertificates, activeCertHandles: c.activeCertHandles, ocspResponse: c.ocspResponse, scts: c.scts, isClient: c.isClient, extMasterSecret: c.extMasterSecret, verifiedChains: c.verifiedChains, }, nil } // EncryptTicket encrypts a ticket with the [Config]'s configured (or default) // session ticket keys. It can be used as a [Config.WrapSession] implementation. func (c *Config) EncryptTicket(cs ConnectionState, ss *SessionState) ([]byte, error) { ticketKeys := c.ticketKeys(nil) stateBytes, err := ss.Bytes() if err != nil { return nil, err } return c.encryptTicket(stateBytes, ticketKeys) } func (c *Config) encryptTicket(state []byte, ticketKeys []ticketKey) ([]byte, error) { if len(ticketKeys) == 0 { return nil, errors.New("tls: internal error: session ticket keys unavailable") } encrypted := make([]byte, aes.BlockSize+len(state)+sha256.Size) iv := encrypted[:aes.BlockSize] ciphertext := encrypted[aes.BlockSize : len(encrypted)-sha256.Size] authenticated := encrypted[:len(encrypted)-sha256.Size] macBytes := encrypted[len(encrypted)-sha256.Size:] if _, err := io.ReadFull(c.rand(), iv); err != nil { return nil, err } key := ticketKeys[0] block, err := aes.NewCipher(key.aesKey[:]) if err != nil { return nil, errors.New("tls: failed to create cipher while encrypting ticket: " + err.Error()) } cipher.NewCTR(block, iv).XORKeyStream(ciphertext, state) mac := hmac.New(sha256.New, key.hmacKey[:]) mac.Write(authenticated) mac.Sum(macBytes[:0]) return encrypted, nil } // DecryptTicket decrypts a ticket encrypted by [Config.EncryptTicket]. It can // be used as a [Config.UnwrapSession] implementation. // // If the ticket can't be decrypted or parsed, DecryptTicket returns (nil, nil). func (c *Config) DecryptTicket(identity []byte, cs ConnectionState) (*SessionState, error) { ticketKeys := c.ticketKeys(nil) stateBytes := c.decryptTicket(identity, ticketKeys) if stateBytes == nil { return nil, nil } s, err := ParseSessionState(stateBytes) if err != nil { return nil, nil // drop unparsable tickets on the floor } return s, nil } func (c *Config) decryptTicket(encrypted []byte, ticketKeys []ticketKey) []byte { if len(encrypted) < aes.BlockSize+sha256.Size { return nil } iv := encrypted[:aes.BlockSize] ciphertext := encrypted[aes.BlockSize : len(encrypted)-sha256.Size] authenticated := encrypted[:len(encrypted)-sha256.Size] macBytes := encrypted[len(encrypted)-sha256.Size:] for _, key := range ticketKeys { mac := hmac.New(sha256.New, key.hmacKey[:]) mac.Write(authenticated) expected := mac.Sum(nil) if subtle.ConstantTimeCompare(macBytes, expected) != 1 { continue } block, err := aes.NewCipher(key.aesKey[:]) if err != nil { return nil } plaintext := make([]byte, len(ciphertext)) cipher.NewCTR(block, iv).XORKeyStream(plaintext, ciphertext) return plaintext } return nil } // ClientSessionState contains the state needed by a client to // resume a previous TLS session. type ClientSessionState struct { ticket []byte session *SessionState } // ResumptionState returns the session ticket sent by the server (also known as // the session's identity) and the state necessary to resume this session. // // It can be called by [ClientSessionCache.Put] to serialize (with // [SessionState.Bytes]) and store the session. func (cs *ClientSessionState) ResumptionState() (ticket []byte, state *SessionState, err error) { return cs.ticket, cs.session, nil } // NewResumptionState returns a state value that can be returned by // [ClientSessionCache.Get] to resume a previous session. // // state needs to be returned by [ParseSessionState], and the ticket and session // state must have been returned by [ClientSessionState.ResumptionState]. func NewResumptionState(ticket []byte, state *SessionState) (*ClientSessionState, error) { return &ClientSessionState{ ticket: ticket, session: state, }, nil }