generatePasswordHash
generatePasswordHash* ( password : string , options : object ) : string
| Parameter | Type | Description | |
|---|---|---|---|
| password | string | → | The user's password. Only the first 72 characters are used |
| options | object | → | An object containing options |
| Result | string | ← | Returns the hashed password |
Description
The generatePasswordHash function returns a secure password hash generated by a cryptographic hash algorithm.
Pass a string value in the password parameter. The generatePasswordHash returns a hashed string for the password. Multiple passes of the same password will result in different hashed strings.
In the options object, pass the properties to use when generating the password hash. The available values are listed in the table below:
| Property | Value Type | Description | Default Value |
|---|---|---|---|
| algorithm | string | algorithm to be used. Currently only "bcrypt" (case sensitive) is supported. | bcrypt |
| cost | number | speed to be used. The supported values for bcrypt are between 4 and 31. | 10 |
If either value in the options object is invalid, an error message and an empty string will be returned.
Error management
The following errors may be returned. You can review an error with the onErrCall command.
| Number | Message |
|---|---|
| 850 | Password-hash: Unsupported algorithm. |
| 852 | Password-hash: Unavailable bcrypt cost parameter, please provide a value between 4 and 31. |
About bcrypt
bcrypt is a password hashing function based on the Blowfish cipher. In addition to incorporating a salt to protect against rainbow table attacks, it's an adaptive function in which the iteration count can be increased to make it slower, so it remains resistant to brute-force attacks even with increasing computation power because it takes longer and becomes too time consuming and expensive.
Example
This example generates a password hash using bcrypt with a cost factor 4.
declare(password : string , userId : integer)
var hash : string
var options : object
var user : cs.UserEntity
options = newObject("algorithm","bcrypt","cost",4)
hash = generatePasswordHash(password,options)
user = ds.User.get(userId)
user.hash = hash
user.save()
Multiple passes of the same password will result in different hashed strings. This is a standard behavior for algorithms such as bcrypt, since the best practice is to create a new, random salt for every hash. Refer to the verifyPasswordHash description for an example of how to check the passwords