EncodeString: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (remove extra example that does the same thing (useless))
 
(22 intermediate revisions by 13 users not shown)
Line 4: Line 4:
This function encodes a [[string]] using the specified algorithm. The counterpart of this function is [[decodeString]].
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==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
string encodeString ( string algorithm, string input, table options [, function callback ] )   
string encodeString ( string algorithm, string input, [table options, function callback] )   
</syntaxhighlight>  
</syntaxhighlight>  


Line 13: Line 15:
*'''algorithm:''' The algorithm to use.
*'''algorithm:''' The algorithm to use.
*'''input:''' The input to encode.
*'''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===
===Options for each algorithm===
* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
* ''tea'' ([https://en.wikipedia.org/wiki/Tiny_Encryption_Algorithm Tiny Encryption Algorithm])
** ''key'': A key to 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}}
{{Added feature/item|1.6.0|1.6.1|23219|
* ''zlib'' ([https://en.wikipedia.org/wiki/Zlib Zlib Compression Algorithm])
** '''compression''': a number that defines compression level. (0-9) (9 - the best) (default: 9)
** '''format''': a string or number that defines compression format. (gzip, zlib, raw or [https://www.zlib.net/manual.html#Advanced window size number]) (default: gzip)
** '''strategy''': a string that defines compression strategy. (default, filtered, huffman, rle, fixed)
|23219}}


===Optional Arguments===
===Optional Arguments===
{{New feature/item|3.0160|1.5.7|20394|
*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
}}
===Returns===
Returns 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.


==Example==  
===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''' ([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.
 
* ''tea'', ''rsa'', ''base64'', ''base32'', ''zlib''
** '''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==
 
<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.
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>
</section>


<section name="Server" class="server" show="true">
<section name="Server" class="server" show="true">
This example shows you how to use the RSA encryption with a simple string message.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
addCommandHandler("encode",  
local private, public = generateKeyPair("rsa", { size = 2048 })
    function(player, _, algorithm, key, ...)
 
        if algorithm and key then
local input = "Hello, world!"
            local text = table.concat({...}, " ")
local encrypted = encodeString("rsa", input, { key = public })
            if type(text) == "string" and text ~= "" then
local decrypted = decodeString("rsa", encrypted, { key = private })
                local encoded = encodeString(algorithm, text, { key = key })
 
                if encoded then
outputDebugString("RSA test: ".. tostring(input == decrypted))
                    outputChatBox("The result of " .. algorithm .. " encoding is: " .. encoded, player)
                else
                    outputChatBox("Failed to encode. Make sure that all arguments are valid.", player, 255, 0, 0)
                end
            else
                outputChatBox("Please specify text in the command.", player, 255, 0, 0)
            end
        else
            outputChatBox("Invalid algorithm and/or key.", player, 255, 0, 0)
        end
    end
)
</syntaxhighlight>
</syntaxhighlight>
</section>
</section>

Latest revision as of 10:09, 19 May 2025

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

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)
BETA: NEW FEATURE (BUILD: 1.6.1 r22408)
BETA: NEW FEATURE (BUILD: 1.6.1 r23219)
  • zlib (Zlib Compression Algorithm)
    • compression: a number that defines compression level. (0-9) (9 - the best) (default: 9)
    • format: a string or number that defines compression format. (gzip, zlib, raw or window size number) (default: gzip)
    • strategy: a string that defines compression strategy. (default, filtered, huffman, rle, fixed)

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, zlib
    • 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)
Click to collapse [-]
Server

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 })

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

See Also


Retrieved from "https://wiki.multitheftauto.com/wiki/EncodeString?oldid=82005"