EncodeString: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
m (corrected typo)
m (Improved formatting)
 
(20 intermediate revisions by 14 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
{{Shared function}}
{{Shared function}}
{{New feature/item|3.0160|1.5.5|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==  
==Syntax==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
string|false encodeString ( string algorithm, string input, table options )   
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'':
* ''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==
==See Also==
{{Utility functions}}
{{Utility functions}}

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

BETA: NEW FEATURE (BUILD: 1.6.1 r22408)
BETA: NEW FEATURE (BUILD: 1.6.1 r22408)

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

See Also