encrypt-data

Encrypt data.

encrypt-data <data> to [ define ] <result> password <password> \
    [ input-length <input length> ] \
    [ salt <salt> ] \
    [ output-length [ define ] <output length> ] \
    [ binary ] \

encrypt-data encrypts <data> using AES256 encryption and SHA256 hashing.

If "input-length" clause is missing, then <data> is considered to be a null-terminated string and its length is the number of bytes encrypted. If "input-length" clause is used, then <input length> bytes is encrypted, regardless of whether <data> is a null-terminated string or not.

String <password> (in "password" clause) is the password used to encrypt and it must be a null-terminated string. Optional <salt> (in "salt" clause) is the salt used (which is combined with password to protect against "rainbow table" attacks), and it must be a null terminated string. If <salt> is used, then it must be a string exactly 16 bytes long (you can use random-string to generate random strings of a given length). Note that if you use "salt" clause, then you must use the exact same <salt> value when data is decrypted with decrypt-data - typically salt values are stored in the database along with encrypted values.

The encrypted data is stored in <result> (used in "to" clause), which you can create with optional "define". The encrypted data can be a binary data (if "binary" clause is present, which is binary-mode encryption) or if not, it will be a null-terminated string (which is character-mode encryption), consisting of hexadecimal characters (i.e. ranging from "0" to "9" and "a" to "f"). Character mode of encryption is convenient if the result of encryption should be a human readable string, or for the purposes of non-binary storage in the database.

If "binary" clause is specified, then "output-length" must be present and the length of the binary encrypted data will be in <output length> , which can be created with optional "define". In any case, if used, <output length> has the length of the encrypted data, which is the exact byte count in binary mode, or the length of encrypted string in character mode (i.e. the number of character bytes excluding the terminating null byte).

In the following example, the data is encrypted, and then decrypted, producing the very same data:

// Original string to encrypt
char *orig_data="something to encrypt!";

// Encrypted data is in "res" variable
encrypt-data orig_data password "mypass" to define res

// Decrypt what was just encrypted, decrypted data is in "dec_data"
decrypt-data res password "mypass" to define dec_data

// Check that decrypted data matches the original 
if (!strcmp (orig_data, dec_data)) {
    @Success!
} else {
    @Failure!
}

A more involved example below encrypts specific number of bytes (6 in this case). random-string is used to produce salt. The length of data to encrypt is given with "input-length" clause. The encrypted data is specified to be "binary" (meaning not as a human-readable string), so the "output-length" of such binary output is specified. The decryption thus uses "input-length" clause to specify the length of data to decrypt, and also "output-length" to get the length of decrypted data. Finally, the original data is compared with the decrypted data, and the length of such data must be the same as the original (meaning 6):

// Original data (only the first 6 bytes are encrypted)
char *orig_data="something to encrypt!";

// Get 16 random bytes to be the salt
random-string to define newsalt length 16

// Encrypt data using salt and produce binary output (meaning it's not a null-terminated character string), with the
// length of such output in "encrypted_len" variable.
encrypt-data orig_data input-length 6 output-length define encrypted_len password "mypass" salt newsalt to define res binary

// Decrypt the data encrypted above. The length of encrypted data is passed in "encrypted_len" variable, and then length of decrypted data
// is obtained in "decrypted_len" variable.
decrypt-data res output-length define decrypted_len password "mypass" salt newsalt to define dec_data input-length encrypted_len binary

// Check if the 6 bytes of the original data matches decrypted data, and if exactly 6 bytes was decrypted
if (!strncmp(orig_data,dec_data, 6) && decrypted_len == 6) {
    @Success!
} else {
    @Failure!
}

Encryption ( decrypt-data   encrypt-data   hash-string   random-string  )  SEE ALL (documentation)