s = CS.Hash.createHash(path := ... ‖ text := ... ‖ bytes := ...ʃ, bytesFormat := ...ʅ
ʃ, type := ...ʅ
ʃ, length := ...ʅ
ʃ, iterations := ...ʅ
ʃ, salt := ...ʅʃ, saltFormat := ...ʅ) | Argument | Description | Types / Required |
|---|
| path | The path of a file to hash. | string
not required |
| text | A text string to hash. | string
not required |
| bytes | Bytes to hash. | string
not required |
| bytesFormat | The format of bytes.
The default value is "autodetect". | string
not required |
| type | The hash algorithm.
The default value is "PBKDF2_SHA256". | string
not required |
| length | The length of the hash value in bytes.
The default value is 32. | number
not required |
| iterations | The number of times the value is hashed.
The default value is 1024. | number
not required |
| salt | A salt to add to the hash. | string
not required |
| saltFormat | The format of salt.
The default value is "autodetect". | string
not required |
The
Hash.createHash action creates a hash value based on the contents of a file, text, or bytes. One, and only one, of the arguments
path,
text, or
bytes must be provided. If specifying
text, the
UTF-8 representation of the text is hashed. If specifying
bytes, the optional
bytesFormat argument dictates how
binary data is converted from string format.
Three hash types are supported, specified using the type argument:
- "PBKDF2_SHA256": Calculates a hash using a SHA-256 key derivation algorithm.
- "MD5": Creates a MD5 hash. (The action Hash.createMd5 also creates MD5 hashes.)
- "EncryptedCSProDB": Calculates a hash using the algorithm used to turn a text password into an encryption key used to open Encrypted CSPro DB data sources.
The default type,
"PBKDF2_SHA256", returns hash values identical to the
hash logic function.
The optional number
length specifies the desired length of the hash value in bytes. The string returned will always be twice the value of
length. The maximum value for
length is 500. The optional number
iterations specifies the number of times the input is hashed. You can also specify a
salt (and its
format,
saltFormat), which is an additional input in generating the hash value. You must store this salt value somewhere to be able to use this hash function to perform any checks. The
length,
iterations, and
salt arguments are ignored when creating MD5 hashes, and hashes for Encrypted CSPro DB data sources, as those values are predefined for those hash types.
More information on hash values, key derivation algorithms, and salt values is readily available online.
The action returns the hash value represented as a hexadecimal string. The hexadecimal characters are returned in lowercase.
The action throws an exception if any of its arguments are not specified in a valid form, if the file does not exist, or if the bytes or salt values cannot be successfully converted from their binary formats.
// check the password against the hash value stored in the data file of staff members,
// created using the random salt stored in USER_PASSWORD_SALT
string userPassword = prompt("Enter your password", password);
string hashedPassword = CS.Hash.createHash(text := userPassword,
salt := strip(USER_PASSWORD_SALT), saltFormat := "text");
if hashedPassword <> strip(USER_PASSWORD_HASH) then
errmsg("Invalid password. You cannot access this system.");
stop(1);
endif;