EncodeString: Difference between revisions

Latest revision as of 20:13, 15 March 2024

This function encodes a string using the specified algorithm. The counterpart of this function is decodeString.

[[{{{image}}}\|link=\|]]	Tip: If it doesn't matter which algorithm you use for the encoding, keep in mind that aes128 uses hardware acceleration so it may outperform the tea algorithm on most processors.

Syntax

string encodeString ( string algorithm, string input, [table options, function callback] )

Required Arguments

algorithm: The algorithm to use.
input: The input to encode.
options: A table with options and other necessary data for the algorithm, as detailed below.

Options for each algorithm

tea (Tiny Encryption Algorithm)
- key: a key to encode the input with.

aes128 (Advanced Encryption Standard in CTR mode)
- key: a key to encode the input with (must be 16 characters long).

rsa (Rivest-Shamir-Adleman in OAEP with SHA-1 mode)
- key: a public key to encode the input. (use generateKeyPair to create a new private and public key)

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)

base64 (Base64 Encoding Algorithm)
- variant: a string that defines the encoding variant. (Currently only "URL" is available)

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)

base32 (Base32 Encoding Algorithm)
- variant: a string that defines the encoding variant. (Currently only "Hex" is available)

Optional Arguments

callback: providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.

Returns for each algorithm

aes128
- encodedString: the encoded string if successful, false otherwise. If a callback was provided, true is returned immediately, and the encoded string is passed as an argument to the callback.
- iv (Initialization vector): this is a string generated by the encryption algorithm that is needed to decrypt the message by decodeString. If a callback was provided, true is returned immediately, and the iv is passed as an argument to the callback.

tea
rsa
base64
base32
- encodedString: the encoded string if successful, false otherwise. If a callback was provided, true is returned immediately, and the encoded string is passed as an argument to the callback.

Examples

Click to collapse [-]

Server

Adds an /encode command in which you can provide an algorithm, key and data to encode. Below is the example provided as both server-side and client-side variations.

addCommandHandler("encode", function(player, _, algorithm, key, ...)
    if not algorithm or not key then
        outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
        return
    end
    local text = table.concat({...}, " ")
    if type(text) ~= "string" or text == "" then
        outputChatBox("Please specify text in the command.", player, 255, 0, 0)
        return
    end
    local encoded = encodeString(algorithm, text, { key = key })
    if not encoded then
        outputChatBox("Failed to encode. Make sure that all arguments are valid.", player, 255, 0, 0)
        return
    end

    outputChatBox("The result of " .. algorithm .. " encoding is: " .. encoded, player)
end)

This example shows you how to use the RSA encryption with a simple string message.

local private, public = generateKeyPair("rsa", { size = 2048 })

local input = "Hello, world!"
local encrypted = encodeString("rsa", input, { key = public })
local decrypted = decodeString("rsa", encrypted, { key = private })

outputServerLog("RSA test: ".. tostring(input == decrypted))

@@ Line 1: / Line 1: @@
 __NOTOC__
 {{Shared function}}
-{{New feature/item|3.0160|1.6|11849|
+{{New feature/item|3.0156|1.5.5|11849|
-This function encodes a string using a specified algorithm.
+This function encodes a [[string]] using the specified algorithm. The counterpart of this function is [[decodeString]].
 }}
+{{Tip|If it doesn't matter which algorithm you use for the encoding, keep in mind that ''aes128'' uses hardware acceleration so it may outperform the ''tea'' algorithm on most processors.}}
 ==Syntax==
 <syntaxhighlight lang="lua">
-string|false encodeString ( string algorithm, string input, table options )
+string encodeString ( string algorithm, string input, [table options, function callback] )
 </syntaxhighlight>
@@ Line 13: / Line 15: @@
 *'''algorithm:''' The algorithm to use.
 *'''input:''' The input to encode.
-*'''options :''' A table with options and other neccessary data for the algorithm, as detailed below
+*'''options:''' A [[table]] with options and other necessary data for the algorithm, as detailed below.
 ===Options for each algorithm===
-* ''tea'':
+* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
-** ''key'' (string) A key to tea-encode the input with
+** '''key''': a key to encode the input with.
+{{Added feature/item|1.5.9|1.5.8|20898|
+* ''aes128'' ([https://en.wikipedia.org/wiki/Advanced_Encryption_Standard Advanced Encryption Standard] in CTR mode)
+** '''key''': a key to encode the input with (must be 16 characters long).
+|20898}}
+{{Added feature/item|1.5.9|1.5.8|21055|
+* ''rsa'' ([https://en.wikipedia.org/wiki/RSA_(cryptosystem) Rivest-Shamir-Adleman] in OAEP with SHA-1 mode)
+** '''key''': a public key to encode the input. (use [[generateKeyPair]] to create a new private and public key)
+|21055}}
+{{Added feature/item|1.6.0|1.6.1|22408|
+* ''base64'' ([https://en.wikipedia.org/wiki/Base64 Base64 Encoding Algorithm])
+** '''variant''': a string that defines the encoding variant. (Currently only "URL" is available)
+|22408}}
+{{Added feature/item|1.6.0|1.6.1|22408|
+* ''base32'' ([https://en.wikipedia.org/wiki/Base32 Base32 Encoding Algorithm])
+** '''variant''': a string that defines the encoding variant. (Currently only "Hex" is available)
+|22408}}
+===Optional Arguments===
+*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
+===Returns for each algorithm===
+{{New items|3.0159|1.5.8|
+* ''aes128''
+** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
+** '''iv''' ([https://en.wikipedia.org/wiki/Initialization_vector Initialization vector]): this is a string generated by the encryption algorithm that is needed to decrypt the message by [[decodeString]]. If a callback was provided, ''true'' is returned immediately, and the ''iv'' is passed as an argument to the callback.
+|20898}}
+{{New items|3.0159|1.6.1|
+* ''tea''
+* ''rsa''
+* ''base64''
+* ''base32''
+** '''encodedString''': the encoded string if successful, ''false'' otherwise. If a callback was provided, ''true'' is returned immediately, and the encoded string is passed as an argument to the callback.
+|22408}}
+==Examples==
+<section name="Server" class="server" show="true">
+Adds an ''/encode'' command in which you can provide an algorithm, key and data to encode. Below is the example provided as both server-side and client-side variations.
+<syntaxhighlight lang="lua">
+addCommandHandler("encode", function(player, _, algorithm, key, ...)
+    if not algorithm or not key then
+        outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
+        return
+    end
+    local text = table.concat({...}, " ")
+    if type(text) ~= "string" or text == "" then
+        outputChatBox("Please specify text in the command.", player, 255, 0, 0)
+        return
+    end
+    local encoded = encodeString(algorithm, text, { key = key })
+    if not encoded then
+        outputChatBox("Failed to encode. Make sure that all arguments are valid.", player, 255, 0, 0)
+        return
+    end
+    outputChatBox("The result of " .. algorithm .. " encoding is: " .. encoded, player)
+end)
+</syntaxhighlight>
+This example shows you how to use the RSA encryption with a simple string message.
+<syntaxhighlight lang="lua">
+local private, public = generateKeyPair("rsa", { size = 2048 })
-===Returns===
+local input = "Hello, world!"
-Returns the encoded string if successful, ''false'' otherwise.
+local encrypted = encodeString("rsa", input, { key = public })
+local decrypted = decodeString("rsa", encrypted, { key = private })
-==Example==
+outputServerLog("RSA test: ".. tostring(input == decrypted))
-{{Needs Example}}
+</syntaxhighlight>
+</section>
 ==See Also==
 {{Utility functions}}