diff --git a/tutorials/networking/img/add_crt.png b/tutorials/networking/img/add_crt.png deleted file mode 100644 index 309a359dd67..00000000000 Binary files a/tutorials/networking/img/add_crt.png and /dev/null differ diff --git a/tutorials/networking/img/ssl_certs.png b/tutorials/networking/img/ssl_certs.png deleted file mode 100644 index 77ea9305f7d..00000000000 Binary files a/tutorials/networking/img/ssl_certs.png and /dev/null differ diff --git a/tutorials/networking/img/tls_certificates_export_filter.webp b/tutorials/networking/img/tls_certificates_export_filter.webp new file mode 100644 index 00000000000..ee83fa50436 Binary files /dev/null and b/tutorials/networking/img/tls_certificates_export_filter.webp differ diff --git a/tutorials/networking/img/tls_certificates_project_setting.webp b/tutorials/networking/img/tls_certificates_project_setting.webp new file mode 100644 index 00000000000..026511aa5e4 Binary files /dev/null and b/tutorials/networking/img/tls_certificates_project_setting.webp differ diff --git a/tutorials/networking/ssl_certificates.rst b/tutorials/networking/ssl_certificates.rst index 09da65d085d..bfa62d3471c 100644 --- a/tutorials/networking/ssl_certificates.rst +++ b/tutorials/networking/ssl_certificates.rst @@ -1,74 +1,79 @@ -:article_outdated: True - .. _doc_ssl_certificates: -SSL certificates -================ +SSL/TLS certificates +==================== Introduction ------------ -It is often desired to use SSL connections for communications to avoid -"man in the middle" attacks. Godot has a connection wrapper, -:ref:`StreamPeerTLS `, -which can take a regular connection and add security around it. The -:ref:`HTTPClient ` -class also supports HTTPS by using this same wrapper. - -Godot includes SSL certificates from Mozilla, but you can provide your own -with a .crt file in the project settings: +It is often desired to use :abbr:`SSL (Secure Sockets Layer)` connections (also +known as :abbr:`TLS (Transport Layer Security)` connections) for communications +to avoid "man in the middle" attacks. Godot has a connection wrapper, +:ref:`StreamPeerTLS `, which can take a regular connection +and add security around it. The :ref:`HTTPClient ` and +:ref:`HTTPRequest ` classes also support HTTPS using +this same wrapper. -.. image:: img/ssl_certs.png +Godot includes the +`SSL certificate bundle from Mozilla `__, +but you can provide your own with a CRT file in the Project Settings: -This file should contain any number of public certificates in -`PEM format `__. +.. figure:: img/tls_certificates_project_setting.webp + :align: center + :alt: Setting the TLS certificate bundle override project setting -Of course, remember to add .crt as filter so the exporter recognizes -this when exporting your project. + Setting the TLS certificate bundle override project setting -.. image:: img/add_crt.png +When set, this file *overrides* the Mozilla certificate bundle Godot uses +by default. This file should contain any number of public certificates in +`PEM format `__. -There are two ways to obtain certificates: +Remember to add ``*.crt`` as the non-resource export filter to your export +preset, so that the exporter recognizes this when exporting your project: -Approach 1: self signed cert ----------------------------- +.. figure:: img/tls_certificates_export_filter.webp + :align: center + :alt: Adding ``*.crt`` to non-resource export filter in the export preset -The first approach is the simplest: generate a private and public -key pair and add the public key (in PEM format) to the .crt file. -The private key should go to your server. + Adding ``*.crt`` to non-resource export filter in the export preset -OpenSSL has `some -documentation `__ about -this. This approach also **does not require domain validation** nor -requires you to spend a considerable amount of money in purchasing -certificates from a CA. +There are two ways to obtain certificates: -Approach 2: CA cert -------------------- +Acquire a certificate from a certificate authority +-------------------------------------------------- -The second approach consists of using a certificate authority (CA) -such as Verisign, Geotrust, etc. This is a more cumbersome process, -but it's more "official" and ensures your identity is clearly -represented. +The main approach to getting a certificate is to use a certificate authority +(CA) such as `Let's Encrypt `__. This is a more +cumbersome process than a self-signed certificate, but it's more "official" and +ensures your identity is clearly represented. The resulting certificate is also +trusted by applications such as web browsers, unlike a self-signed certificate +which requires additional configuration on the client side before it's +considered trusted. -Unless you are working with large companies or corporations, or need -to connect to someone else's servers (i.e., connecting to Google or some -other REST API provider via HTTPS), this method is not as useful. +These certificates do not require any configuration on the client to work, since +Godot already bundles the Mozilla certificate bundle in the editor and exported +projects. -Also, when using a CA issued cert, **you must enable domain -validation**, to ensure the domain you are connecting to is the one -intended, otherwise any website can issue any certificate in the same CA -and it will work. +Generate a self-signed certificate +---------------------------------- -If you are using Linux, you can use the supplied certs file, generally -located in: +For most use cases, it's recommended to go through certificate authority as the +process is free with certificate authorities such as Let's Encrypt. However, if +using a certificate authority is not an option, then you can generate a +self-signed certificate and tell the client to consider your self-signed +certificate as trusted. -.. code-block:: none +To create a self-signed certificate, generate a private and public key pair and +add the public key (in PEM format) to the CRT file specified in the Project +Settings. - /etc/ssl/certs/ca-certificates.crt +.. warning:: -This file allows HTTPS connections to virtually any website (i.e., -Google, Microsoft, etc.). + The private key should **only** go to your server. The client must not have + access to it: otherwise, the security of the certificate will be + compromised. -Or pick any of the more specific certificates there if you are -connecting to a specific one. +OpenSSL has `some documentation +`__ +about this. For local development purposes **only**, `mkcert +`__ can be used as an alternative.