PasswordHash: Difference between revisions

Latest revision as of 20:31, 21 May 2022

[[{{{image}}}\|link=\|]]	Note: Using passwordHash is the recommended way of storing passwords.

This function creates a new password hash using a specified hashing algorithm.

[[\|link=\|]]	Warning: It is strongly recommended to use the async version of the function (i.e. provide a callback function). Otherwise, you will experience short freezes due to the slow nature of the bcrypt algorithm

Syntax

string passwordHash ( string password, string algorithm, table options [, function callback ] )

Required Arguments

password: The password to hash.
algorithm: The algorithm to use:
- bcrypt: use the bcrypt hashing algorithm. Hash length: 60 characters. Note that only the prefix $2y$ is supported (older prefixes can cause security issues).
options: table with options for the hashing algorithm, as detailed below.

Optional Arguments

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

Options for each hashing algorithm

bcrypt:
- cost (int), default: 10. Visit this link to determine the number of rounds appropriate for your server.
- salt (string), default: empty string
  - an empty string will automatically generate a salt with the cost provided
  - deprecated: if a string is provided, it will be used as a salt (do not do this!)
  - the provided string should be longer than or equal to 22 characters

Returns

Returns the hash as a string if hashing was successful, false otherwise. If a callback was provided, the aforementioned values are arguments to the callback, and this function will always return true.

Example

[[\|link=\|]]	Warning: If you will be using "Example 1" then you will have to save account data "hash_password" after server restart, otherwise this script will no longer work.

This example makes use of passwordHash and passwordVerify in account creation and account login to boost up security.

Click to collapse [-]

Example 1

Use /accountCreate [username] [password] to create an account.
Use /accountLogin [username] [password] to login in account.

-- lets add command handler that will handle the account creation
addCommandHandler("accountCreate",function(source,cmd,username,password)
	if (username and password) then
		local hashedPassword = passwordHash(password,"bcrypt",{}) -- create new hash for password
		if (hashedPassword) then -- check if hash has been generated
			local account = addAccount(username,hashedPassword) -- now lets add account with new hash what we got when we made it for password.
			if (account) then
				setAccountData(account,"hash_password",hashedPassword) -- store accounts password hash in order to verify it when it's needed.
				outputChatBox("Account successfuly created! Now please login. Syntax </accountLogin [username] [password]>",source,20,160,20)
			else
				outputChatBox("Account already exists! Please try again with different username.",source,20,160,20)
			end
		else
			outputChatBox("Securing your password failed! Please try again or contact an administrator.",source,160,20,20)
		end
	else
		outputChatBox("Wrong parameters! Correct Syntax </accountCreate [username] [password]>",source,160,20,20)
	end
end);

-- lets add command handler that will handle the account login
addCommandHandler("accountLogin",function(source,cmd,username,password)
	if (username and password) then
		local account = getAccount(username) -- get entered account
		if (account) then -- check if entered account exists
			local hashedPassword = getAccountData(account,"hash_password") -- lets get hashed password
			if (passwordVerify(password,hashedPassword)) then -- check if hash and entered password matches
				if logIn(source,account,hashedPassword) then -- now lets login player into account
					outputChatBox("Login successfull. Welcome, "..getAccountName(account).."!",source,20,160,20)
				end
			else
				outputChatBox("Password is incorrect!",source,160,20,20)
			end
		else
			outputChatBox("Account doesn't exist! Please try again with different account.",source,160,20,20)
		end
	else
		outputChatBox("Wrong parameters! Correct Syntax </accountLogin [username] [password]>",source,160,20,20)
	end
end);

@@ Line 1: / Line 1: @@
 __NOTOC__
 {{Shared function}}
-{{Note box|Using '''passwordHash''' is the recommended way of storing passwords.}}
+{{Note|Using '''passwordHash''' is the recommended way of storing passwords.}}
 {{New feature/item|3.0154|1.5.4|11277|
 This function creates a new password hash using a specified hashing algorithm.
 }}
+{{Warning|It is strongly recommended to use the async version of the function (i.e. provide a callback function). Otherwise, you will experience short freezes due to the slow nature of the bcrypt algorithm}}
 ==Syntax==
 <syntaxhighlight lang="lua">
-string passwordHash ( string password, string algorithm [, table options = {} ] )
+string passwordHash ( string password, string algorithm, table options [, function callback ] )
 </syntaxhighlight>
@@ Line 13: / Line 15: @@
 *'''password:''' The password to hash.
 *'''algorithm:''' The algorithm to use:
-** ''bcrypt'': use the bcrypt hashing algorithm
+** ''bcrypt'': use the bcrypt hashing algorithm. Hash length: 60 characters. <span style="color:red">Note that only the prefix ''$2y$'' is supported (older prefixes can cause security issues).</span>
+*'''options:''' table with options for the hashing algorithm, as detailed below.
 ===Optional Arguments===
-*'''options:''' table with options for the hashing algorithm, as detailed below
+{{New feature/item|3.0154|1.5.4|11281|
+*'''callback:''' providing a callback will run this function asynchronously, the arguments to the callback are the same as the returned values below.
+}}
 ===Options for each hashing algorithm===
 * ''bcrypt'':
-** ''cost'' (int), default: 10
+** ''cost'' (int), default: 10.  Visit [http://security.stackexchange.com/questions/17207/recommended-of-rounds-for-bcrypt this link] to determine the number of rounds appropriate for your server.
-** ''salt'' (string), default: automatically generate salt
+** ''salt'' (string), default: empty string
 *** an empty string will automatically generate a salt with the ''cost'' provided
-*** if a string is provided, the given salt is used (do not do this!)
+*** '''deprecated''': if a string is provided, it will be used as a salt ('''do not do this!''')
+*** the provided string should be longer than or equal to 22 characters
 ===Returns===
-Returns the hash as a string if hashing was successful, ''false'' otherwise.
+Returns the hash as a string if hashing was successful, ''false'' otherwise. If a callback was provided, the aforementioned values are arguments to the callback, and this function will always return ''true''.
+==Example==
+{{Warning|If you will be using "Example 1" then you will have to save account data "hash_password" after server restart, otherwise this script will no longer work.}}
+This example makes use of [https://wiki.multitheftauto.com/wiki/PasswordHash passwordHash] and [https://wiki.multitheftauto.com/wiki/PasswordVerify passwordVerify] in account creation and account login to boost up security.
+<section name="Example 1" class="server" show="true">
+* Use '''/accountCreate [username] [password]''' to create an account.
+* Use '''/accountLogin [username] [password]''' to login in account.
+<syntaxhighlight lang="lua">
+-- lets add command handler that will handle the account creation
+addCommandHandler("accountCreate",function(source,cmd,username,password)
+	if (username and password) then
+		local hashedPassword = passwordHash(password,"bcrypt",{}) -- create new hash for password
+		if (hashedPassword) then -- check if hash has been generated
+			local account = addAccount(username,hashedPassword) -- now lets add account with new hash what we got when we made it for password.
+			if (account) then
+				setAccountData(account,"hash_password",hashedPassword) -- store accounts password hash in order to verify it when it's needed.
+				outputChatBox("Account successfuly created! Now please login. Syntax </accountLogin [username] [password]>",source,20,160,20)
+			else
+				outputChatBox("Account already exists! Please try again with different username.",source,20,160,20)
+			end
+		else
+			outputChatBox("Securing your password failed! Please try again or contact an administrator.",source,160,20,20)
+		end
+	else
+		outputChatBox("Wrong parameters! Correct Syntax </accountCreate [username] [password]>",source,160,20,20)
+	end
+end);
-==Example==
+-- lets add command handler that will handle the account login
-{{Example}}
+addCommandHandler("accountLogin",function(source,cmd,username,password)
+	if (username and password) then
+		local account = getAccount(username) -- get entered account
+		if (account) then -- check if entered account exists
+			local hashedPassword = getAccountData(account,"hash_password") -- lets get hashed password
+			if (passwordVerify(password,hashedPassword)) then -- check if hash and entered password matches
+				if logIn(source,account,hashedPassword) then -- now lets login player into account
+					outputChatBox("Login successfull. Welcome, "..getAccountName(account).."!",source,20,160,20)
+				end
+			else
+				outputChatBox("Password is incorrect!",source,160,20,20)
+			end
+		else
+			outputChatBox("Account doesn't exist! Please try again with different account.",source,160,20,20)
+		end
+	else
+		outputChatBox("Wrong parameters! Correct Syntax </accountLogin [username] [password]>",source,160,20,20)
+	end
+end);
+</syntaxhighlight>
+</section>
 ==See Also==
+{{Utility functions}}
+[[pt-br:passwordHash]]