tls-api.diff

@@ -8,6 +8,7 @@
 CONSTANTS
 
 const (
+    // TLS 1.0 - 1.2 cipher suites.
     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
@@ -31,6 +32,11 @@
     TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305    uint16 = 0xcca8
     TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305  uint16 = 0xcca9
 
+    // TLS 1.3+ cipher suites.
+    TLS_AES_128_GCM_SHA256       uint16 = 0x1301
+    TLS_AES_256_GCM_SHA384       uint16 = 0x1302
+    TLS_CHACHA20_POLY1305_SHA256 uint16 = 0x1303
+
     // TLS_FALLBACK_SCSV isn't a standard cipher suite but an indicator
     // that the client is doing version fallback. See
     // https://tools.ietf.org/html/rfc7507.
@@ -43,10 +49,12 @@
     http://www.iana.org/assignments/tls-parameters/tls-parameters.xml
 
 const (
     VersionSSL30 = 0x0300
     VersionTLS10 = 0x0301
     VersionTLS11 = 0x0302
     VersionTLS12 = 0x0303
+    VersionTLS13 = 0x0304
 )
 
 FUNCTIONS
@@ -173,6 +181,18 @@ type ClientHelloInfo struct
     // from, or write to, this connection; that will cause the TLS
     // connection to fail.
     Conn net.Conn
+
+    // Offered0RTTData is true if the client announced that it will send
+    // 0-RTT data. If the server Config.Accept0RTTData is true, and the
+    // client offered a session ticket valid for that purpose, it will
+    // be notified that the 0-RTT data is accepted and it will be made
+    // immediately available for Read.
+    Offered0RTTData bool
+
+    // The Fingerprint is an sequence of bytes unique to this Client Hello.
+    // It can be used to prevent or mitigate 0-RTT data replays as it's
+    // guaranteed that a replayed connection will have the same Fingerprint.
+    Fingerprint []byte
 }
     ClientHelloInfo contains information from a ClientHello message in order
     to guide certificate selection in the GetCertificate callback.
@@ -314,10 +338,15 @@ type Config struct
     // 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.
+    // TLS 1.3 uses a default set of secure cipher suites.
     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
@@ -373,6 +402,31 @@ type Config struct
     // Use of KeyLogWriter compromises security and should only be
     // used for debugging.
     KeyLogWriter io.Writer
+
+    // If Max0RTTDataSize is not zero, the client will be allowed to use
+    // session tickets to send at most this number of bytes of 0-RTT data.
+    // 0-RTT data is subject to replay and has memory DoS implications.
+    // The server will later be able to refuse the 0-RTT data with
+    // Accept0RTTData, or wait for the client to prove that it's not
+    // replayed with Conn.ConfirmHandshake.
+    //
+    // It has no meaning on the client.
+    //
+    // See https://tools.ietf.org/html/draft-ietf-tls-tls13-18#section-2.3.
+    Max0RTTDataSize uint32
+
+    // Accept0RTTData makes the 0-RTT data received from the client
+    // immediately available to Read. 0-RTT data is subject to replay.
+    // Use Conn.ConfirmHandshake to wait until the data is known not
+    // to be replayed after reading it.
+    //
+    // It has no meaning on the client.
+    //
+    // See https://tools.ietf.org/html/draft-ietf-tls-tls13-18#section-2.3.
+    Accept0RTTData bool
     // contains filtered or unexported fields
 }
     A Config structure is used to configure a TLS client or server. After
@@ -434,6 +488,18 @@
     be called once the handshake has completed and does not call CloseWrite
     on the underlying connection. Most callers should just use Close.
 
+func (c *Conn) ConfirmHandshake() error
+    ConfirmHandshake waits for the handshake to reach a point at which the
+    connection is certainly not replayed. That is, after receiving the
+    Client Finished.
+
+    If ConfirmHandshake returns an error and until ConfirmHandshake returns,
+    the 0-RTT data should not be trusted not to be replayed.
+
+    This is only meaningful in TLS 1.3 when Accept0RTTData is true and the
+    client sent valid 0-RTT data. In any other case it's equivalent to
+    calling Hendshake.
+
 func (c *Conn) ConnectionState() ConnectionState
     ConnectionState returns basic TLS details about the connection.
 
@@ -442,6 +508,9 @@ func (*Conn).Handshake
     been run. Most uses of this package need not call Handshake explicitly:
     the first Read or Write will call it automatically.
 
+    In TLS 1.3 Handshake returns after the client and server first flights,
+    without waiting for the Client Finished.
+
 func (c *Conn) LocalAddr() net.Addr
     LocalAddr returns the local network address.
 
@@ -500,6 +570,17 @@ type ConnectionState struct
     // future versions of Go once the TLS master-secret fix has been
     // standardized and implemented.
     TLSUnique []byte
+
+    // HandshakeConfirmed is true once all data returned by Read
+    // (past and future) is guaranteed not to be replayed.
+    HandshakeConfirmed bool
+
+    // The Fingerprint is an sequence of bytes unique to this connection.
+    // It can be used to prevent or mitigate 0-RTT data replays as it's
+    // guaranteed that a replayed connection will have the same Fingerprint.
+    Fingerprint []byte
 }
     ConnectionState records basic TLS details about the connection.