Merge pull request #32285 from Faless/crypto/initial_docs

Add documentation for crypto-related classes.

5 files changed, 72 insertions, 1 deletions

diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml
index bb852f5fff..e81e17497c 100644
--- a/doc/classes/Crypto.xml
+++ b/doc/classes/Crypto.xml
@@ -1,8 +1,27 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="Crypto" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
+		Access to advanced cryptographic functionalities.
 	</brief_description>
 	<description>
+		The Crypto class allows you to access some more advanced cryptographic functionalities in Godot.
+		For now, this includes generating cryptographically secure random bytes, and RSA keys and self-signed X509 certificates generation. More functionalities are planned for future releases.
+		[codeblock]
+		extends Node
+
+		var crypto = Crypto.new()
+		var key = CryptoKey.new()
+		var cert = X509Certificate.new()
+
+		func _ready():
+		    # Generate new RSA key.
+		    key = crypto.generate_rsa(4096)
+		    # Generate new self-signed certificate with the given key.
+		    cert = crypto.generate_self_signed_certificate(key, "CN=mydomain.com,O=My Game Company,C=IT")
+		    # Save key and certificate in the user folder.
+		    key.save("user://generated.key")
+		    cert.save("user://generated.crt")
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,12 +32,14 @@
 			<argument index="0" name="size" type="int">
 			</argument>
 			<description>
+				Generates a [PoolByteArray] of cryptographically secure random bytes with given [code]size[/code].
 			</description>
 		</method>
 		<method name="generate_rsa">
 			<return type="CryptoKey">
 			</return>
 			<argument index="0" name="size" type="int">
+				Generates an RSA [CryptoKey] that can be used for creating self-signed certificates and passed to [method StreamPeerSSL.acccept_stream].
 			</argument>
 			<description>
 			</description>
@@ -35,6 +56,15 @@
 			<argument index="3" name="not_after" type="String" default="&quot;20340101000000&quot;">
 			</argument>
 			<description>
+				Generates a self-signed [X509Certificate] from the given [CryptoKey] and [code]issuer_name[/code]. The certificate validity will be defined by [code]not_before[/code] and [code]not_after[/code] (first valid date and last valid date). The [code]issuer_name[/code] must contain at least "CN=" (common name, i.e. the domain name), "O=" (organization, i.e. your company name), "C=" (country, i.e. 2 lettered ISO-3166 code of the country the organization is based in).
+				A small example to generate an RSA key and a X509 self-signed certificate.
+				[codeblock]
+				var crypto = Crypto.new()
+				# Generate 4096 bits RSA key.
+				var key = crypto.generate_rsa(4096)
+				# Generate self-signed certificate using the given key.
+				var cert = crypto.generate_self_signed_certificate(key, "CN=example.com,O=A Game Company,C=IT")
+				[/codeblock]
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/CryptoKey.xml b/doc/classes/CryptoKey.xml
index d3cd485a5f..6db6fea779 100644
--- a/doc/classes/CryptoKey.xml
+++ b/doc/classes/CryptoKey.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="CryptoKey" inherits="Resource" category="Core" version="3.2">
 	<brief_description>
+		A cryptographic key (RSA).
 	</brief_description>
 	<description>
+		The CryptoKey class represents a cryptographic key. Keys can be loaded and saved like any other [Resource].
+		They can be used to generate a self-signed [X509Certificate] via [method Crypto.generate_self_signed] and as private key in [method StreamPeerSSL.accept_stream] along with the appropriate certificate.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,6 +16,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Loads a key from [code]path[/code] ("*.key" file).
 			</description>
 		</method>
 		<method name="save">
@@ -21,6 +25,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Saves a key to the given [code]path[/code] (should be a "*.key" file).
 			</description>
 		</method>
 	</methods>
diff --git a/doc/classes/HashingContext.xml b/doc/classes/HashingContext.xml
index 552a74eba4..802b186ef3 100644
--- a/doc/classes/HashingContext.xml
+++ b/doc/classes/HashingContext.xml
@@ -1,8 +1,32 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="HashingContext" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
+		Context to compute cryptographic hashes over multiple iterations.
 	</brief_description>
 	<description>
+		The HashingContext class provides an interface for computing cryptographic hashes over multiple iterations. This is useful for example when computing hashes of big files (so you don't have to load them all in memory), network streams, and data streams in general (so you don't have to hold buffers).
+		The [enum HashType] enum shows the supported hashing algorithms.
+		[codeblock]
+		const CHUNK_SIZE = 1024
+
+		func hash_file(path):
+		    var ctx = HashingContext.new()
+		    var file = File.new()
+		    # Start a SHA-256 context.
+		    ctx.start(HashingContext.HASH_SHA256)
+		    # Check that file exists.
+		    if not file.file_exists(path):
+		        return
+		    # Open the file to hash.
+		    file.open(path, File.READ)
+		    # Update the context after reading each chunk.
+		    while not file.eof_reached():
+		        ctx.update(file.get_buffer(CHUNK_SIZE))
+		    # Get the computed hash.
+		    var res = ctx.finish()
+		    # Print the result as hex string and array.
+		    printt(res.hex_encode(), Array(res))
+		[/codeblock]
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,6 +35,7 @@
 			<return type="PoolByteArray">
 			</return>
 			<description>
+				Closes the current context, and return the computed hash.
 			</description>
 		</method>
 		<method name="start">
@@ -19,6 +44,7 @@
 			<argument index="0" name="type" type="int" enum="HashingContext.HashType">
 			</argument>
 			<description>
+				Starts a new hash computation of the given [code]type[/code] (e.g. [constant HASH_SHA256] to start computation of a SHA-256).
 			</description>
 		</method>
 		<method name="update">
@@ -27,15 +53,19 @@
 			<argument index="0" name="chunk" type="PoolByteArray">
 			</argument>
 			<description>
+				Updates the computation with the given [code]chunk[/code] of data.
 			</description>
 		</method>
 	</methods>
 	<constants>
 		<constant name="HASH_MD5" value="0" enum="HashType">
+			Hashing algorithm: MD5.
 		</constant>
 		<constant name="HASH_SHA1" value="1" enum="HashType">
+			Hashing algorithm: SHA-1.
 		</constant>
 		<constant name="HASH_SHA256" value="2" enum="HashType">
+			Hashing algorithm: SHA-256.
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/StreamPeerSSL.xml b/doc/classes/StreamPeerSSL.xml
index c960a794e2..b34d8d1b25 100644
--- a/doc/classes/StreamPeerSSL.xml
+++ b/doc/classes/StreamPeerSSL.xml
@@ -4,7 +4,7 @@
 		SSL stream peer.
 	</brief_description>
 	<description>
-		SSL stream peer. This object can be used to connect to SSL servers.
+		SSL stream peer. This object can be used to connect to an SSL server or accept a single SSL client connection.
 	</description>
 	<tutorials>
 		<link>https://docs.godotengine.org/en/latest/tutorials/networking/ssl_certificates.html</link>
@@ -22,6 +22,7 @@
 			<argument index="3" name="chain" type="X509Certificate" default="null">
 			</argument>
 			<description>
+				Accepts a peer connection as a server using the given [code]private_key[/code] and providing the given [code]certificate[/code] to the client. You can pass the optional [code]chain[/code] parameter to provide additional CA chain information along with the certificate.
 			</description>
 		</method>
 		<method name="connect_to_stream">
diff --git a/doc/classes/X509Certificate.xml b/doc/classes/X509Certificate.xml
index 013f768843..8066f65391 100644
--- a/doc/classes/X509Certificate.xml
+++ b/doc/classes/X509Certificate.xml
@@ -1,8 +1,11 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="X509Certificate" inherits="Resource" category="Core" version="3.2">
 	<brief_description>
+		An X509 certificate (e.g. for SSL).
 	</brief_description>
 	<description>
+		The X509Certificate class represents an X509 certificate. Certificates can be loaded and saved like any other [Resource].
+		They can be used as the server certificate in [StreamPeerSSL.accept_stream] (along with the proper [CryptoKey]), and to specify the only certificate that should be accepted when connecting to an SSL server via [StreamPeerSSL.connect_to_stream].
 	</description>
 	<tutorials>
 	</tutorials>
@@ -13,6 +16,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Loads a certificate from [code]path[/code] ("*.crt" file).
 			</description>
 		</method>
 		<method name="save">
@@ -21,6 +25,7 @@
 			<argument index="0" name="path" type="String">
 			</argument>
 			<description>
+				Saves a certificate to the given [code]path[/code] (should be a "*.crt" file).
 			</description>
 		</method>
 	</methods>