Merge pull request #71995 from Faless/net/4.x_tls_verify

[NET] Refactor TLS configuration.

6 files changed, 76 insertions, 32 deletions

diff --git a/doc/classes/DTLSServer.xml b/doc/classes/DTLSServer.xml
index 457513b8aa..a3a0b0456c 100644
--- a/doc/classes/DTLSServer.xml
+++ b/doc/classes/DTLSServer.xml
@@ -148,11 +148,9 @@
 	<methods>
 		<method name="setup">
 			<return type="int" enum="Error" />
-			<param index="0" name="key" type="CryptoKey" />
-			<param index="1" name="certificate" type="X509Certificate" />
-			<param index="2" name="chain" type="X509Certificate" default="null" />
+			<param index="0" name="server_options" type="TLSOptions" />
 			<description>
-				Setup the DTLS server to use the given [param key] and provide the given [param certificate] to clients. You can pass the optional [param chain] parameter to provide additional CA chain information along with the certificate.
+				Setup the DTLS server to use the given [param server_options]. See [method TLSOptions.server].
 			</description>
 		</method>
 		<method name="take_connection">
diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml
index b3ed38d250..b7a5cff694 100644
--- a/doc/classes/HTTPClient.xml
+++ b/doc/classes/HTTPClient.xml
@@ -30,13 +30,10 @@
 			<return type="int" enum="Error" />
 			<param index="0" name="host" type="String" />
 			<param index="1" name="port" type="int" default="-1" />
-			<param index="2" name="use_tls" type="bool" default="false" />
-			<param index="3" name="verify_host" type="bool" default="true" />
+			<param index="2" name="tls_options" type="TLSOptions" default="null" />
 			<description>
 				Connects to a host. This needs to be done before any requests are sent.
-				The host should not have http:// prepended but will strip the protocol identifier if provided.
-				If no [param port] is specified (or [code]-1[/code] is used), it is automatically set to 80 for HTTP and 443 for HTTPS (if [param use_tls] is enabled).
-				[param verify_host] will check the TLS identity of the host if set to [code]true[/code].
+				If no [param port] is specified (or [code]-1[/code] is used), it is automatically set to 80 for HTTP and 443 for HTTPS. You can pass the optional [param tls_options] parameter to customize the trusted certification authorities, or the common name verification when using HTTPS. See [method TLSOptions.client] and [method TLSOptions.client_unsafe].
 			</description>
 		</method>
 		<method name="get_response_body_length" qualifiers="const">
diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml
index 3dbc024b14..d403acf90c 100644
--- a/doc/classes/HTTPRequest.xml
+++ b/doc/classes/HTTPRequest.xml
@@ -187,9 +187,8 @@
 			<return type="int" enum="Error" />
 			<param index="0" name="url" type="String" />
 			<param index="1" name="custom_headers" type="PackedStringArray" default="PackedStringArray()" />
-			<param index="2" name="tls_validate_domain" type="bool" default="true" />
-			<param index="3" name="method" type="int" enum="HTTPClient.Method" default="0" />
-			<param index="4" name="request_data" type="String" default="&quot;&quot;" />
+			<param index="2" name="method" type="int" enum="HTTPClient.Method" default="0" />
+			<param index="3" name="request_data" type="String" default="&quot;&quot;" />
 			<description>
 				Creates request on the underlying [HTTPClient]. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request].
 				Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host.
@@ -201,9 +200,8 @@
 			<return type="int" enum="Error" />
 			<param index="0" name="url" type="String" />
 			<param index="1" name="custom_headers" type="PackedStringArray" default="PackedStringArray()" />
-			<param index="2" name="tls_validate_domain" type="bool" default="true" />
-			<param index="3" name="method" type="int" enum="HTTPClient.Method" default="0" />
-			<param index="4" name="request_data_raw" type="PackedByteArray" default="PackedByteArray()" />
+			<param index="2" name="method" type="int" enum="HTTPClient.Method" default="0" />
+			<param index="3" name="request_data_raw" type="PackedByteArray" default="PackedByteArray()" />
 			<description>
 				Creates request on the underlying [HTTPClient] using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request].
 				Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host.
@@ -227,6 +225,13 @@
 				The proxy server is unset if [param host] is empty or [param port] is -1.
 			</description>
 		</method>
+		<method name="set_tls_options">
+			<return type="void" />
+			<param index="0" name="client_options" type="TLSOptions" />
+			<description>
+				Sets the [TLSOptions] to be used when connecting to an HTTPS server. See [method TLSOptions.client].
+			</description>
+		</method>
 	</methods>
 	<members>
 		<member name="accept_gzip" type="bool" setter="set_accept_gzip" getter="is_accepting_gzip" default="true">
diff --git a/doc/classes/PacketPeerDTLS.xml b/doc/classes/PacketPeerDTLS.xml
index db8403a56b..19c5d0e287 100644
--- a/doc/classes/PacketPeerDTLS.xml
+++ b/doc/classes/PacketPeerDTLS.xml
@@ -14,11 +14,10 @@
 		<method name="connect_to_peer">
 			<return type="int" enum="Error" />
 			<param index="0" name="packet_peer" type="PacketPeerUDP" />
-			<param index="1" name="validate_certs" type="bool" default="true" />
-			<param index="2" name="for_hostname" type="String" default="&quot;&quot;" />
-			<param index="3" name="valid_certificate" type="X509Certificate" default="null" />
+			<param index="1" name="hostname" type="String" />
+			<param index="2" name="client_options" type="TLSOptions" default="null" />
 			<description>
-				Connects a [param packet_peer] beginning the DTLS handshake using the underlying [PacketPeerUDP] which must be connected (see [method PacketPeerUDP.connect_to_host]). If [param validate_certs] is [code]true[/code], [PacketPeerDTLS] will validate that the certificate presented by the remote peer and match it with the [param for_hostname] argument. You can specify a custom [X509Certificate] to use for validation via the [param valid_certificate] argument.
+				Connects a [param packet_peer] beginning the DTLS handshake using the underlying [PacketPeerUDP] which must be connected (see [method PacketPeerUDP.connect_to_host]). You can optionally specify the [param client_options] to be used while verifying the TLS connections. See [method TLSOptions.client] and [method TLSOptions.client_unsafe].
 			</description>
 		</method>
 		<method name="disconnect_from_peer">
diff --git a/doc/classes/StreamPeerTLS.xml b/doc/classes/StreamPeerTLS.xml
index d1ddb3d441..a5d882a713 100644
--- a/doc/classes/StreamPeerTLS.xml
+++ b/doc/classes/StreamPeerTLS.xml
@@ -14,22 +14,18 @@
 		<method name="accept_stream">
 			<return type="int" enum="Error" />
 			<param index="0" name="stream" type="StreamPeer" />
-			<param index="1" name="private_key" type="CryptoKey" />
-			<param index="2" name="certificate" type="X509Certificate" />
-			<param index="3" name="chain" type="X509Certificate" default="null" />
+			<param index="1" name="server_options" type="TLSOptions" />
 			<description>
-				Accepts a peer connection as a server using the given [param private_key] and providing the given [param certificate] to the client. You can pass the optional [param chain] parameter to provide additional CA chain information along with the certificate.
+				Accepts a peer connection as a server using the given [param server_options]. See [method TLSOptions.server].
 			</description>
 		</method>
 		<method name="connect_to_stream">
 			<return type="int" enum="Error" />
 			<param index="0" name="stream" type="StreamPeer" />
-			<param index="1" name="validate_certs" type="bool" default="false" />
-			<param index="2" name="for_hostname" type="String" default="&quot;&quot;" />
-			<param index="3" name="valid_certificate" type="X509Certificate" default="null" />
+			<param index="1" name="common_name" type="String" />
+			<param index="2" name="client_options" type="TLSOptions" default="null" />
 			<description>
-				Connects to a peer using an underlying [StreamPeer] [param stream]. If [param validate_certs] is [code]true[/code], [StreamPeerTLS] will validate that the certificate presented by the peer matches the [param for_hostname].
-				[b]Note:[/b] Specifying a custom [param valid_certificate] is not supported in Web exports due to browsers restrictions.
+				Connects to a peer using an underlying [StreamPeer] [param stream] and verifying the remote certificate is correcly signed for the given [param common_name]. You can pass the optional [param client_options] parameter to customize the trusted certification authorities, or disable the common name verification. See [method TLSOptions.client] and [method TLSOptions.client_unsafe].
 			</description>
 		</method>
 		<method name="disconnect_from_stream">
@@ -57,10 +53,6 @@
 			</description>
 		</method>
 	</methods>
-	<members>
-		<member name="blocking_handshake" type="bool" setter="set_blocking_handshake_enabled" getter="is_blocking_handshake_enabled" default="true">
-		</member>
-	</members>
 	<constants>
 		<constant name="STATUS_DISCONNECTED" value="0" enum="Status">
 			A status representing a [StreamPeerTLS] that is disconnected.
diff --git a/doc/classes/TLSOptions.xml b/doc/classes/TLSOptions.xml
new file mode 100644
index 0000000000..0917bd9bce
--- /dev/null
+++ b/doc/classes/TLSOptions.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="TLSOptions" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		TLS configuration for clients and servers.
+	</brief_description>
+	<description>
+		TLSOptions abstracts the configuration options for the [StreamPeerTLS] and [PacketPeerDTLS] classes.
+		Objects of this class cannot be instantiated directly, and one of the static methods [method client], [method client_unsafe], or [method server] should be used instead.
+		[codeblocks]
+		[gdscript]
+		# Create a TLS client configuration which uses our custom trusted CA chain.
+		var client_trusted_cas = load("res://my_trusted_cas.crt")
+		var client_tls_options = TLSOptions.client(client_trusted_cas)
+
+		# Create a TLS server configuration.
+		var server_certs = load("res://my_server_cas.crt")
+		var server_key = load("res://my_server_key.key")
+		var server_tls_options = TLSOptions.server(server_certs, server_key)
+		[/gdscript]
+		[/codeblocks]
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="client" qualifiers="static">
+			<return type="TLSOptions" />
+			<param index="0" name="trusted_chain" type="X509Certificate" default="null" />
+			<param index="1" name="common_name_override" type="String" default="&quot;&quot;" />
+			<description>
+				Creates a TLS client configuration which validates certificates and their common names (fully qualified domain names).
+				You can specify a custom [param trusted_chain] of certification authorities (the default CA list will be used if [code]null[/code]), and optionally provide a [param common_name_override] if you expect the certificate to have a common name other then the server FQDN.
+				Note: On the Web plafrom, TLS verification is always enforced against the CA list of the web browser. This is considered a security feature.
+			</description>
+		</method>
+		<method name="client_unsafe" qualifiers="static">
+			<return type="TLSOptions" />
+			<param index="0" name="trusted_chain" type="X509Certificate" default="null" />
+			<description>
+				Creates an [b]unsafe[/b] TLS client configuration where certificate validation is optional. You can optionally provide a valid [param trusted_chain], but the common name of the certififcates will never be checked. Using this configuration for purposes other than testing [b]is not recommended[/b].
+				Note: On the Web plafrom, TLS verification is always enforced against the CA list of the web browser. This is considered a security feature.
+			</description>
+		</method>
+		<method name="server" qualifiers="static">
+			<return type="TLSOptions" />
+			<param index="0" name="key" type="CryptoKey" />
+			<param index="1" name="certificate" type="X509Certificate" />
+			<description>
+				Creates a TLS server configuration using the provided [param key] and [param certificate].
+				Note: The [param certificate] should include the full certificate chain up to the signing CA (certificates file can be concatenated using a general purpose text editor).
+			</description>
+		</method>
+	</methods>
+</class>