maxmustermann/godot
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #32285 from Faless/crypto/initial_docs

Browse source 
Add documentation for crypto-related classes.
This commit is contained in:
Rémi Verschelde 2019-09-24 15:55:00 +02:00 committed by GitHub
parent e95e847c01 a20cbf2cca
commit 08f557c0c4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 72 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
doc/classes/Crypto.xml
View file

@ -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>

5
doc/classes/CryptoKey.xml
View file

@ -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>

30
doc/classes/HashingContext.xml
View file

@ -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>

3
doc/classes/StreamPeerSSL.xml
View file

@ -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">

5
doc/classes/X509Certificate.xml
View file

@ -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>