rename the STK to Cookie

Changelog.md

@@ -10,6 +10,7 @@
 - Add a `quic.Config` option to configure the handshake timeout
 - Add a `quic.Config` option to configure the idle timeout
 - Add a `quic.Config` option to configure keep-alive
+- Rename the STK to Cookie
 - Implement `net.Conn`-style deadlines for streams
 - Remove the `tls.Config` from the `quic.Config`. The `tls.Config` must now be passed to the `Dial` and `Listen` functions as a separate parameter. See the [Godoc](https://godoc.org/github.com/lucas-clemente/quic-go) for details.
 - Changed the log level environment variable to only accept strings ("DEBUG", "INFO", "ERROR"), see [the wiki](https://github.com/lucas-clemente/quic-go/wiki/Logging) for more details.

integrationtests/self/handshake_rtt_test.go

@@ -119,8 +119,8 @@ var _ = Describe("Handshake RTT tests", func() {
 		expectDurationInRTTs(2)
 	})
 
-	It("is forward-secure after 2 RTTs when the server doesn't require an STK", func() {
-		serverConfig.AcceptSTK = func(_ net.Addr, _ *quic.STK) bool {
+	It("is forward-secure after 2 RTTs when the server doesn't require a Cookie", func() {
+		serverConfig.AcceptCookie = func(_ net.Addr, _ *quic.Cookie) bool {
 			return true
 		}
 		runServerAndProxy()
@@ -129,8 +129,8 @@ var _ = Describe("Handshake RTT tests", func() {
 		expectDurationInRTTs(2)
 	})
 
-	It("doesn't complete the handshake when the server never accepts the STK", func() {
-		serverConfig.AcceptSTK = func(_ net.Addr, _ *quic.STK) bool {
+	It("doesn't complete the handshake when the server never accepts the Cookie", func() {
+		serverConfig.AcceptCookie = func(_ net.Addr, _ *quic.Cookie) bool {
 			return false
 		}
 		runServerAndProxy()

interface.go

@@ -16,8 +16,8 @@ type StreamID = protocol.StreamID
 // A VersionNumber is a QUIC version number.
 type VersionNumber = protocol.VersionNumber
 
-// An STK can be used to verify the ownership of the client address.
-type STK = handshake.Cookie
+// A Cookie can be used to verify the ownership of the client address.
+type Cookie = handshake.Cookie
 
 // Stream is the interface implemented by QUIC streams
 type Stream interface {
@@ -102,11 +102,11 @@ type Config struct {
 	// If the timeout is exceeded, the connection is closed.
 	// If this value is zero, the timeout is set to 30 seconds.
 	IdleTimeout time.Duration
-	// AcceptSTK determines if an STK is accepted.
-	// It is called with stk = nil if the client didn't send an STK.
-	// If not set, it verifies that the address matches, and that the STK was issued within the last 24 hours.
+	// AcceptCookie determines if a Cookie is accepted.
+	// It is called with cookie = nil if the client didn't send an Cookie.
+	// If not set, it verifies that the address matches, and that the Cookie was issued within the last 24 hours.
 	// This option is only valid for the server.
-	AcceptSTK func(clientAddr net.Addr, stk *STK) bool
+	AcceptCookie func(clientAddr net.Addr, cookie *Cookie) bool
 	// MaxReceiveStreamFlowControlWindow is the maximum stream-level flow control window for receiving data.
 	// If this value is zero, it will default to 1 MB for the server and 6 MB for the client.
 	MaxReceiveStreamFlowControlWindow uint64

internal/protocol/server_parameters.go

@@ -81,8 +81,8 @@ const SkipPacketAveragePeriodLength PacketNumber = 500
 // MaxTrackedSkippedPackets is the maximum number of skipped packet numbers the SentPacketHandler keep track of for Optimistic ACK attack mitigation
 const MaxTrackedSkippedPackets = 10
 
-// STKExpiryTime is the valid time of a source address token
-const STKExpiryTime = 24 * time.Hour
+// CookieExpiryTime is the valid time of a cookie
+const CookieExpiryTime = 24 * time.Hour
 
 // MaxTrackedSentPackets is maximum number of sent packets saved for either later retransmission or entropy calculation
 const MaxTrackedSentPackets = 2 * DefaultMaxCongestionWindow

server.go

@@ -94,11 +94,11 @@ func Listen(conn net.PacketConn, tlsConf *tls.Config, config *Config) (Listener,
 	return s, nil
 }
 
-var defaultAcceptSTK = func(clientAddr net.Addr, stk *STK) bool {
-	if stk == nil {
+var defaultAcceptCookie = func(clientAddr net.Addr, cookie *Cookie) bool {
+	if cookie == nil {
 		return false
 	}
-	if time.Now().After(stk.SentTime.Add(protocol.STKExpiryTime)) {
+	if time.Now().After(cookie.SentTime.Add(protocol.CookieExpiryTime)) {
 		return false
 	}
 	var sourceAddr string
@@ -107,7 +107,7 @@ var defaultAcceptSTK = func(clientAddr net.Addr, stk *STK) bool {
 	} else {
 		sourceAddr = clientAddr.String()
 	}
-	return sourceAddr == stk.RemoteAddr
+	return sourceAddr == cookie.RemoteAddr
 }
 
 // populateServerConfig populates fields in the quic.Config with their default values, if none are set
@@ -121,9 +121,9 @@ func populateServerConfig(config *Config) *Config {
 		versions = protocol.SupportedVersions
 	}
 
-	vsa := defaultAcceptSTK
-	if config.AcceptSTK != nil {
-		vsa = config.AcceptSTK
+	vsa := defaultAcceptCookie
+	if config.AcceptCookie != nil {
+		vsa = config.AcceptCookie
 	}
 
 	handshakeTimeout := protocol.DefaultHandshakeTimeout
@@ -148,7 +148,7 @@ func populateServerConfig(config *Config) *Config {
 		Versions:                              versions,
 		HandshakeTimeout:                      handshakeTimeout,
 		IdleTimeout:                           idleTimeout,
-		AcceptSTK:                             vsa,
+		AcceptCookie:                          vsa,
 		MaxReceiveStreamFlowControlWindow:     maxReceiveStreamFlowControlWindow,
 		MaxReceiveConnectionFlowControlWindow: maxReceiveConnectionFlowControlWindow,
 	}

server_test.go

@@ -343,10 +343,10 @@ var _ = Describe("Server", func() {
 
 	It("setups with the right values", func() {
 		supportedVersions := []protocol.VersionNumber{1, 3, 5}
-		acceptSTK := func(_ net.Addr, _ *STK) bool { return true }
+		acceptCookie := func(_ net.Addr, _ *Cookie) bool { return true }
 		config := Config{
 			Versions:         supportedVersions,
-			AcceptSTK:        acceptSTK,
+			AcceptCookie:     acceptCookie,
 			HandshakeTimeout: 1337 * time.Hour,
 			IdleTimeout:      42 * time.Minute,
 		}
@@ -359,7 +359,7 @@ var _ = Describe("Server", func() {
 		Expect(server.config.Versions).To(Equal(supportedVersions))
 		Expect(server.config.HandshakeTimeout).To(Equal(1337 * time.Hour))
 		Expect(server.config.IdleTimeout).To(Equal(42 * time.Minute))
-		Expect(reflect.ValueOf(server.config.AcceptSTK)).To(Equal(reflect.ValueOf(acceptSTK)))
+		Expect(reflect.ValueOf(server.config.AcceptCookie)).To(Equal(reflect.ValueOf(acceptCookie)))
 	})
 
 	It("fills in default values if options are not set in the Config", func() {
@@ -369,7 +369,7 @@ var _ = Describe("Server", func() {
 		Expect(server.config.Versions).To(Equal(protocol.SupportedVersions))
 		Expect(server.config.HandshakeTimeout).To(Equal(protocol.DefaultHandshakeTimeout))
 		Expect(server.config.IdleTimeout).To(Equal(protocol.DefaultIdleTimeout))
-		Expect(reflect.ValueOf(server.config.AcceptSTK)).To(Equal(reflect.ValueOf(defaultAcceptSTK)))
+		Expect(reflect.ValueOf(server.config.AcceptCookie)).To(Equal(reflect.ValueOf(defaultAcceptCookie)))
 	})
 
 	It("listens on a given address", func() {
@@ -447,51 +447,51 @@ var _ = Describe("Server", func() {
 var _ = Describe("default source address verification", func() {
 	It("accepts a token", func() {
 		remoteAddr := &net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)}
-		stk := &STK{
+		cookie := &Cookie{
 			RemoteAddr: "192.168.0.1",
-			SentTime:   time.Now().Add(-protocol.STKExpiryTime).Add(time.Second), // will expire in 1 second
+			SentTime:   time.Now().Add(-protocol.CookieExpiryTime).Add(time.Second), // will expire in 1 second
 		}
-		Expect(defaultAcceptSTK(remoteAddr, stk)).To(BeTrue())
+		Expect(defaultAcceptCookie(remoteAddr, cookie)).To(BeTrue())
 	})
 
 	It("requests verification if no token is provided", func() {
 		remoteAddr := &net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)}
-		Expect(defaultAcceptSTK(remoteAddr, nil)).To(BeFalse())
+		Expect(defaultAcceptCookie(remoteAddr, nil)).To(BeFalse())
 	})
 
 	It("rejects a token if the address doesn't match", func() {
 		remoteAddr := &net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)}
-		stk := &STK{
+		cookie := &Cookie{
 			RemoteAddr: "127.0.0.1",
 			SentTime:   time.Now(),
 		}
-		Expect(defaultAcceptSTK(remoteAddr, stk)).To(BeFalse())
+		Expect(defaultAcceptCookie(remoteAddr, cookie)).To(BeFalse())
 	})
 
 	It("accepts a token for a remote address is not a UDP address", func() {
 		remoteAddr := &net.TCPAddr{IP: net.IPv4(192, 168, 0, 1), Port: 1337}
-		stk := &STK{
+		cookie := &Cookie{
 			RemoteAddr: "192.168.0.1:1337",
 			SentTime:   time.Now(),
 		}
-		Expect(defaultAcceptSTK(remoteAddr, stk)).To(BeTrue())
+		Expect(defaultAcceptCookie(remoteAddr, cookie)).To(BeTrue())
 	})
 
 	It("rejects an invalid token for a remote address is not a UDP address", func() {
 		remoteAddr := &net.TCPAddr{IP: net.IPv4(192, 168, 0, 1), Port: 1337}
-		stk := &STK{
+		cookie := &Cookie{
 			RemoteAddr: "192.168.0.1:7331", // mismatching port
 			SentTime:   time.Now(),
 		}
-		Expect(defaultAcceptSTK(remoteAddr, stk)).To(BeFalse())
+		Expect(defaultAcceptCookie(remoteAddr, cookie)).To(BeFalse())
 	})
 
 	It("rejects an expired token", func() {
 		remoteAddr := &net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)}
-		stk := &STK{
+		cookie := &Cookie{
 			RemoteAddr: "192.168.0.1",
-			SentTime:   time.Now().Add(-protocol.STKExpiryTime).Add(-time.Second), // expired 1 second ago
+			SentTime:   time.Now().Add(-protocol.CookieExpiryTime).Add(-time.Second), // expired 1 second ago
 		}
-		Expect(defaultAcceptSTK(remoteAddr, stk)).To(BeFalse())
+		Expect(defaultAcceptCookie(remoteAddr, cookie)).To(BeFalse())
 	})
 })

session.go

@@ -197,8 +197,8 @@ func (s *session) setup(
 	if s.perspective == protocol.PerspectiveServer {
 		cryptoStream, _ := s.GetOrOpenStream(1)
 		_, _ = s.AcceptStream() // don't expose the crypto stream
-		verifySourceAddr := func(clientAddr net.Addr, stk *STK) bool {
-			return s.config.AcceptSTK(clientAddr, stk)
+		verifySourceAddr := func(clientAddr net.Addr, cookie *Cookie) bool {
+			return s.config.AcceptCookie(clientAddr, cookie)
 		}
 		if s.version == protocol.VersionTLS {
 			s.cryptoSetup, err = handshake.NewCryptoSetupTLS(

session_test.go

@@ -166,7 +166,7 @@ var _ = Describe("Session", func() {
 			_ io.ReadWriter,
 			_ handshake.ConnectionParametersManager,
 			_ []protocol.VersionNumber,
-			_ func(net.Addr, *STK) bool,
+			_ func(net.Addr, *Cookie) bool,
 			aeadChangedP chan<- protocol.EncryptionLevel,
 		) (handshake.CryptoSetup, error) {
 			aeadChanged = aeadChangedP
@@ -204,9 +204,9 @@ var _ = Describe("Session", func() {
 
 	Context("source address validation", func() {
 		var (
-			stkVerify       func(net.Addr, *STK) bool
+			cookieVerify    func(net.Addr, *Cookie) bool
 			paramClientAddr net.Addr
-			paramSTK        *STK
+			paramCookie     *Cookie
 		)
 		remoteAddr := &net.UDPAddr{IP: net.IPv4(192, 168, 13, 37), Port: 1000}
 
@@ -219,17 +219,17 @@ var _ = Describe("Session", func() {
 				_ io.ReadWriter,
 				_ handshake.ConnectionParametersManager,
 				_ []protocol.VersionNumber,
-				stkFunc func(net.Addr, *STK) bool,
+				cookieFunc func(net.Addr, *Cookie) bool,
 				_ chan<- protocol.EncryptionLevel,
 			) (handshake.CryptoSetup, error) {
-				stkVerify = stkFunc
+				cookieVerify = cookieFunc
 				return cryptoSetup, nil
 			}
 
 			conf := populateServerConfig(&Config{})
-			conf.AcceptSTK = func(clientAddr net.Addr, stk *STK) bool {
+			conf.AcceptCookie = func(clientAddr net.Addr, cookie *Cookie) bool {
 				paramClientAddr = clientAddr
-				paramSTK = stk
+				paramCookie = cookie
 				return false
 			}
 			pSess, _, err := newSession(
@@ -245,19 +245,19 @@ var _ = Describe("Session", func() {
 		})
 
 		It("calls the callback with the right parameters when the client didn't send an STK", func() {
-			stkVerify(remoteAddr, nil)
+			cookieVerify(remoteAddr, nil)
 			Expect(paramClientAddr).To(Equal(remoteAddr))
-			Expect(paramSTK).To(BeNil())
+			Expect(paramCookie).To(BeNil())
 		})
 
 		It("calls the callback with the STK when the client sent an STK", func() {
-			stkAddr := &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 1337}
+			cookieAddr := &net.UDPAddr{IP: net.IPv4(127, 0, 0, 1), Port: 1337}
 			sentTime := time.Now().Add(-time.Hour)
-			stkVerify(remoteAddr, &STK{SentTime: sentTime, RemoteAddr: stkAddr.String()})
+			cookieVerify(remoteAddr, &Cookie{SentTime: sentTime, RemoteAddr: cookieAddr.String()})
 			Expect(paramClientAddr).To(Equal(remoteAddr))
-			Expect(paramSTK).ToNot(BeNil())
-			Expect(paramSTK.RemoteAddr).To(Equal(stkAddr.String()))
-			Expect(paramSTK.SentTime).To(Equal(sentTime))
+			Expect(paramCookie).ToNot(BeNil())
+			Expect(paramCookie.RemoteAddr).To(Equal(cookieAddr.String()))
+			Expect(paramCookie.SentTime).To(Equal(sentTime))
 		})
 	})