Add private min and max version API (#823)

Author: theodorsm

config.go

@@ -15,6 +15,7 @@ import (
 	"time"
 
 	"github.com/pion/dtls/v3/pkg/crypto/elliptic"
+	"github.com/pion/dtls/v3/pkg/protocol"
 	"github.com/pion/dtls/v3/pkg/protocol/handshake"
 	"github.com/pion/logging"
 )
@@ -236,6 +237,10 @@ type Config struct { //nolint:dupl
 
 	// ListenConfig used to create the underlying listener socket.
 	listenConfig net.ListenConfig
+
+	minVersion protocol.Version
+
+	maxVersion protocol.Version
 }
 
 func (c *Config) includeCertificateSuites() bool {

conn.go

@@ -191,6 +191,16 @@ func createConn(
 		curves = filtered
 	}
 
+	minVersion := config.minVersion
+	if !minVersion.Equal(protocol.Version1_2) || !minVersion.Equal(protocol.Version1_3) {
+		minVersion = protocol.Version1_2
+	}
+
+	maxVersion := config.minVersion
+	if !maxVersion.Equal(protocol.Version1_2) || !maxVersion.Equal(protocol.Version1_3) {
+		maxVersion = protocol.Version1_2
+	}
+
 	handshakeConfig := &handshakeConfig{
 		localPSKCallback:              config.PSK,
 		localPSKIdentityHint:          config.PSKIdentityHint,
@@ -226,6 +236,8 @@ func createConn(
 		serverHelloMessageHook:        config.ServerHelloMessageHook,
 		certificateRequestMessageHook: config.CertificateRequestMessageHook,
 		resumeState:                   resumeState,
+		minVersion:                    minVersion,
+		maxVersion:                    maxVersion,
 	}
 
 	conn := &Conn{

handshaker.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/pion/dtls/v3/pkg/crypto/elliptic"
 	"github.com/pion/dtls/v3/pkg/crypto/signaturehash"
+	"github.com/pion/dtls/v3/pkg/protocol"
 	"github.com/pion/dtls/v3/pkg/protocol/alert"
 	"github.com/pion/dtls/v3/pkg/protocol/handshake"
 	"github.com/pion/logging"
@@ -136,6 +137,9 @@ type handshakeConfig struct {
 	certificateRequestMessageHook func(handshake.MessageCertificateRequest) handshake.Message
 
 	resumeState *State
+
+	minVersion protocol.Version
+	maxVersion protocol.Version
 }
 
 type flightConn interface {

options.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/pion/dtls/v3/pkg/crypto/elliptic"
+	"github.com/pion/dtls/v3/pkg/protocol"
 	"github.com/pion/dtls/v3/pkg/protocol/handshake"
 	"github.com/pion/logging"
 )
@@ -80,6 +81,8 @@ type dtlsConfig struct { //nolint:dupl
 	certificateRequestMessageHook func(handshake.MessageCertificateRequest) handshake.Message
 	onConnectionAttempt           func(net.Addr) error
 	listenConfig                  net.ListenConfig
+	minVersion                    protocol.Version
+	maxVersion                    protocol.Version
 }
 
 // applyDefaults applies default values to the config.
@@ -124,6 +127,8 @@ func (c *dtlsConfig) toConfig() *Config {
 		CertificateRequestMessageHook: c.certificateRequestMessageHook,
 		OnConnectionAttempt:           c.onConnectionAttempt,
 		listenConfig:                  c.listenConfig,
+		minVersion:                    c.minVersion,
+		maxVersion:                    c.maxVersion,
 	}
 
 	if len(c.certificates) > 0 {
@@ -561,6 +566,34 @@ func WithClientHelloMessageHook(fn func(handshake.MessageClientHello) handshake.
 	})
 }
 
+// MinVersion sets the minimum TLS version that is acceptable.
+// By default, DTLS 1.2 is currently used as the minimum as it's the only supported version.
+func withMinVersion(version protocol.Version) Option { // nolint:unused
+	return sharedOption(func(c *dtlsConfig) error {
+		if protocol.IsSupportedVersion(version) {
+			c.minVersion = version
+
+			return nil
+		}
+
+		return errUnsupportedProtocolVersion
+	})
+}
+
+// MaxVersion sets the maxiumum TLS version that is acceptable.
+// By default, DTLS 1.2 is currently used as the minimum as it's the only supported version.
+func withMaxVersion(version protocol.Version) Option { // nolint:unused
+	return sharedOption(func(c *dtlsConfig) error {
+		if protocol.IsSupportedVersion(version) {
+			c.maxVersion = version
+
+			return nil
+		}
+
+		return errUnsupportedProtocolVersion
+	})
+}
+
 // serverOnlyOption wraps an apply function for server-only options.
 type serverOnlyOption func(*dtlsConfig) error
 

options_test.go

@@ -13,6 +13,7 @@ import (
 	"github.com/pion/dtls/v3/pkg/crypto/elliptic"
 	"github.com/pion/dtls/v3/pkg/crypto/selfsign"
 	dtlsnet "github.com/pion/dtls/v3/pkg/net"
+	"github.com/pion/dtls/v3/pkg/protocol"
 	"github.com/pion/transport/v4/dpipe"
 	"github.com/stretchr/testify/require"
 )
@@ -268,6 +269,14 @@ func TestInvalidNumericOptionsReturnError(t *testing.T) {
 		_, err = buildServerConfig(WithExtendedMasterSecret(ExtendedMasterSecretType(100)))
 		require.ErrorIs(t, err, errInvalidExtendedMasterSecretType)
 	})
+
+	t.Run("InvalidVersions", func(t *testing.T) {
+		_, err := buildClientConfig(withMinVersion(protocol.Version{}))
+		require.ErrorIs(t, err, errUnsupportedProtocolVersion)
+
+		_, err = buildClientConfig(withMaxVersion(protocol.Version{}))
+		require.ErrorIs(t, err, errUnsupportedProtocolVersion)
+	})
 }
 
 // TestDefaultsAreApplied verifies that defaults are applied before options.

pkg/protocol/version.go

@@ -27,17 +27,17 @@ func (v Version) Equal(x Version) bool {
 // IsSupportedBytes returns true if it's supported by Pion. Only DTLS 1.2 is currently supported.
 // DTLS 1.3 is a work in progress and is currently being implemented.
 func IsSupportedBytes(major uint8, minor uint8) bool {
-	return major == 0xfe && (minor == 0xfd || minor == 0xfc)
+	return major == Version1_2.Major && minor == Version1_2.Minor
 }
 
 // IsSupportedVersion returns true if it's supported by Pion. Only DTLS 1.2 is currently supported.
 // DTLS 1.3 is a work in progress and is currently being implemented.
 func IsSupportedVersion(v Version) bool {
-	return v.Equal(Version1_2) || v.Equal(Version1_3)
+	return v.Equal(Version1_2)
 }
 
 // IsValidBytes returns true if the bytes represent a valid DTLS version as defined in RFC9147 below.
-// Note that this is not the same as whether it's  *supported* by Pion. Please see IsSupportedBytes() for more info.
+// Note that this is not the same as whether it's *supported* by Pion. Please see IsSupportedBytes() for more info.
 //
 // https://tools.ietf.org/html/rfc9147#section-5.3 (see legacy_version)
 func IsValidBytes(major uint8, minor uint8) bool {

pkg/protocol/version_test.go

@@ -38,7 +38,7 @@ func TestIsSupportedBytes(t *testing.T) {
 		want     bool
 	}{
 		{0xfe, 0xfd, true},  // DTLS 1.2
-		{0xfe, 0xfc, true},  // DTLS 1.3 (work in progress)
+		{0xfe, 0xfc, false}, // DTLS 1.3 (WIP)
 		{0xfe, 0xff, false}, // DTLS 1.0 not supported
 		{0x03, 0x03, false}, // TLS 1.2, not DTLS
 		{0x00, 0x00, false},
@@ -56,7 +56,7 @@ func TestIsSupportedVersion(t *testing.T) {
 		want bool
 	}{
 		{Version1_2, true},
-		{Version1_3, true},                         // WIP, supported
+		{Version1_3, false},                        // WIP
 		{Version1_0, false},                        // not supported
 		{Version{Major: 0x03, Minor: 0x03}, false}, // TLS 1.2, not DTLS
 	}