From f055b86e65b9290301d6a7d43b5ca328d77d799b Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Thu, 18 Jun 2020 12:39:56 +0200 Subject: Document AES and new Crypto/CryptoKey functions. --- doc/classes/AESContext.xml | 99 ++++++++++++++++++++++++++++++++++++++++++++++ doc/classes/Crypto.xml | 66 ++++++++++++++++++++++++++++++- doc/classes/CryptoKey.xml | 37 ++++++++++++++++- 3 files changed, 199 insertions(+), 3 deletions(-) create mode 100644 doc/classes/AESContext.xml (limited to 'doc/classes') diff --git a/doc/classes/AESContext.xml b/doc/classes/AESContext.xml new file mode 100644 index 0000000000..ab4d0e0bc3 --- /dev/null +++ b/doc/classes/AESContext.xml @@ -0,0 +1,99 @@ + + + + Interface to low level AES encryption features. + + + This class provides access to AES encryption/decryption of raw data. Both AES-ECB and AES-CBC mode are supported. + [codeblock] + extends Node + + var aes = AESContext.new() + + func _ready(): + var key = "My secret key!!!" # Key must be either 16 or 32 bytes. + var data = "My secret text!!" # Data size must be multiple of 16 bytes, apply padding if needed. + # Encrypt ECB + aes.start(AESContext.MODE_ECB_ENCRYPT, key.to_utf8()) + var encrypted = aes.update(data.to_utf8()) + aes.finish() + # Decrypt ECB + aes.start(AESContext.MODE_ECB_DECRYPT, key.to_utf8()) + var decrypted = aes.update(encrypted) + aes.finish() + # Check ECB + assert(decrypted == data.to_utf8()) + + var iv = "My secret iv!!!!" # IV must be of exactly 16 bytes. + # Encrypt CBC + aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8(), iv.to_utf8()) + encrypted = aes.update(data.to_utf8()) + aes.finish() + # Decrypt CBC + aes.start(AESContext.MODE_CBC_DECRYPT, key.to_utf8(), iv.to_utf8()) + decrypted = aes.update(encrypted) + aes.finish() + # Check CBC + assert(decrypted == data.to_utf8()) + [/codeblock] + + + + + + + + + Close this AES context so it can be started again. See [method start]. + + + + + + + Get the current IV state for this context (IV gets updated when calling [method update]). You normally don't need this funciton. + Note: This function only makes sense when the context is started with [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT]. + + + + + + + + + + + + + Start the AES context in the given [code]mode[/code]. A [code]key[/code] of either 16 or 32 bytes must always be provided, while an [code]iv[/code] (initialization vector) of exactly 16 bytes, is only needed when [code]mode[/code] is either [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT]. + + + + + + + + + Run the desired operation for this AES context. Will return a [PackedByteArray] containing the result of encrypting (or decrypting) the given [code]src[/code]. See [method start] for mode of operation. + Note: The size of [code]src[/code] must be a multiple of 16. Apply some padding if needed. + + + + + + AES electronic codebook encryption mode. + + + AES electronic codebook decryption mode. + + + AES cipher blocker chaining encryption mode. + + + AES cipher blocker chaining decryption mode. + + + Maximum value for the mode enum. + + + diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml index 10f1f18f0d..4edb3eda0a 100644 --- a/doc/classes/Crypto.xml +++ b/doc/classes/Crypto.xml @@ -5,7 +5,7 @@ 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. + For now, this includes generating cryptographically secure random bytes, RSA keys and self-signed X509 certificates generation, asymmetric key encryption/decryption, and signing/verification. [codeblock] extends Node @@ -21,12 +21,48 @@ # Save key and certificate in the user folder. key.save("user://generated.key") cert.save("user://generated.crt") + # Encryption + var data = "Some data" + var encrypted = crypto.encrypt(key, data.to_utf8()) + # Decryption + var decrypted = crypto.decrypt(key, encrypted) + # Signing + var signature = crypto.sign(HashingContext.HASH_SHA256, data.sha256_buffer(), key) + # Verifying + var verified = crypto.verify(HashingContext.HASH_SHA256, data.sha256_buffer(), signature, key) + # Checks + assert(verified) + assert(data.to_utf8() == decrypted) [/codeblock] [b]Note:[/b] Not available in HTML5 exports. + + + + + + + + + Decrypt the given [code]ciphertext[/code] with the provided private [code]key[/code]. + [b]Note[/b]: The maximum size of accepted ciphertext is limited by the key size. + + + + + + + + + + + Encrypt the given [code]plaintext[/code] with the provided public [code]key[/code]. + [b]Note[/b]: The maximum size of accepted plaintext is limited by the key size. + + @@ -68,6 +104,34 @@ [/codeblock] + + + + + + + + + + + Sign a given [code]hash[/code] of type [code]hash_type[/code] with the provided private [code]key[/code]. + + + + + + + + + + + + + + + Verify that a given [code]signature[/code] for [code]hash[/code] of type [code]hash_type[/code] against the provided public [code]key[/code]. + + diff --git a/doc/classes/CryptoKey.xml b/doc/classes/CryptoKey.xml index fe7f4b63f0..410c2262f9 100644 --- a/doc/classes/CryptoKey.xml +++ b/doc/classes/CryptoKey.xml @@ -11,13 +11,34 @@ + + + + + Return [code]true[/code] if this CryptoKey only has the public part, and not the private one. + + + + + + Loads a key from [code]path[/code]. If [code]public_only[/code] is [code]true[/code], only the public key will be loaded. + [b]Note[/b]: [code]path[/code] should should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. + + + + + + + + + - Loads a key from [code]path[/code] ("*.key" file). + Loads a key from the given [code]string[/code]. If [code]public_only[/code] is [code]true[/code], only the public key will be loaded. @@ -25,8 +46,20 @@ + + + + Saves a key to the given [code]path[/code]. If [code]public_only[/code] is [code]true[/code], only the public key will be saved. + [b]Note[/b]: [code]path[/code] should should be a "*.pub" file if [code]public_only[/code] is [code]true[/code], a "*.key" file otherwise. + + + + + + + - Saves a key to the given [code]path[/code] (should be a "*.key" file). + Returns a string containing the key in PEM format. If [code]public_only[/code] is [code]true[/code], only the public key will be included. -- cgit v1.2.3