From a20cbf2cca4e471ebcee86aab52336721cef57bd Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Mon, 23 Sep 2019 18:16:41 +0200 Subject: [PATCH] Add documentation for crypto-related classes. Add documentation for Crypto, CryptoKey, HashingContext, and X509Certificate. Add documentation for `StreamPeerSSL.accept_peer`. Ref #29871. --- doc/classes/Crypto.xml | 30 ++++++++++++++++++++++++++++++ doc/classes/CryptoKey.xml | 5 +++++ doc/classes/HashingContext.xml | 30 ++++++++++++++++++++++++++++++ doc/classes/StreamPeerSSL.xml | 3 ++- doc/classes/X509Certificate.xml | 5 +++++ 5 files changed, 72 insertions(+), 1 deletion(-) diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml index bb852f5fff4..e81e17497c2 100644 --- a/doc/classes/Crypto.xml +++ b/doc/classes/Crypto.xml @@ -1,8 +1,27 @@ + Access to advanced cryptographic functionalities. + 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] @@ -13,12 +32,14 @@ + Generates a [PoolByteArray] of cryptographically secure random bytes with given [code]size[/code]. + Generates an RSA [CryptoKey] that can be used for creating self-signed certificates and passed to [method StreamPeerSSL.acccept_stream]. @@ -35,6 +56,15 @@ + 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] diff --git a/doc/classes/CryptoKey.xml b/doc/classes/CryptoKey.xml index d3cd485a5f3..6db6fea779c 100644 --- a/doc/classes/CryptoKey.xml +++ b/doc/classes/CryptoKey.xml @@ -1,8 +1,11 @@ + A cryptographic key (RSA). + 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. @@ -13,6 +16,7 @@ + Loads a key from [code]path[/code] ("*.key" file). @@ -21,6 +25,7 @@ + Saves a key to the given [code]path[/code] (should be a "*.key" file). diff --git a/doc/classes/HashingContext.xml b/doc/classes/HashingContext.xml index 552a74eba42..802b186ef38 100644 --- a/doc/classes/HashingContext.xml +++ b/doc/classes/HashingContext.xml @@ -1,8 +1,32 @@ + Context to compute cryptographic hashes over multiple iterations. + 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] @@ -11,6 +35,7 @@ + Closes the current context, and return the computed hash. @@ -19,6 +44,7 @@ + Starts a new hash computation of the given [code]type[/code] (e.g. [constant HASH_SHA256] to start computation of a SHA-256). @@ -27,15 +53,19 @@ + Updates the computation with the given [code]chunk[/code] of data. + Hashing algorithm: MD5. + Hashing algorithm: SHA-1. + Hashing algorithm: SHA-256. diff --git a/doc/classes/StreamPeerSSL.xml b/doc/classes/StreamPeerSSL.xml index c960a794e2f..b34d8d1b254 100644 --- a/doc/classes/StreamPeerSSL.xml +++ b/doc/classes/StreamPeerSSL.xml @@ -4,7 +4,7 @@ SSL stream peer. - 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. https://docs.godotengine.org/en/latest/tutorials/networking/ssl_certificates.html @@ -22,6 +22,7 @@ + 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. diff --git a/doc/classes/X509Certificate.xml b/doc/classes/X509Certificate.xml index 013f768843a..8066f653910 100644 --- a/doc/classes/X509Certificate.xml +++ b/doc/classes/X509Certificate.xml @@ -1,8 +1,11 @@ + An X509 certificate (e.g. for SSL). + 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]. @@ -13,6 +16,7 @@ + Loads a certificate from [code]path[/code] ("*.crt" file). @@ -21,6 +25,7 @@ + Saves a certificate to the given [code]path[/code] (should be a "*.crt" file).