Encrypt
Encrypts a string. This is useful for interacting with third‑party systems or for hiding URL parameters.
Syntax
Encrypt(<value>, <key> [, <algorithm> [, <randomize> [, <authentication_tag>]]]) As String
Parameters
<values>
Type: String
The text that needs to be encrypted.
An empty string encrypts to a non-empty value which decrypts back to an empty string.
<key>
Type: String
The encryption key used to encrypt the value. The key must be a string of bytes that has been Base64 encoded. The required length of that byte string depends on the encryption algorithm used. For example:
Dim EncryptionKey
EncryptionKey = Base64Encode("e12zXyp04@jIcdMc")
<algorithm>
Type: String
(Optional.) The encryption algorithm to use; you can choose one of the Advanced Encryption Standard algorithms: AES-128 or AES-256.
For AES-128, the key must be 16 bytes long before Base64 encoding.
For AES-256, the key must be 32 bytes long before Base64 encoding.
The default value is AES-128.
<randomize>
Type: Boolean
(Optional.) True generates a different encrypted value every time you process a string, even if it is the same string. The encrypted value is longer, because it includes information about the randomization used, so that it can be decrypted.
False generates the same encrypted value when you encrypt the same string.
The default value is False.
<authentication_tag>
Type: Boolean
True includes extra information in the encrypted value which enables the Decrypt function to detect if the value has been changed. This makes the encrypted value longer.
The default value is False.
(return)
Type: String
Returns the encrypted version of the string that is specified by the <value> parameter.
Example
Dim EncryptionKey, EncryptedResult
EncryptionKey = Base64Encode("e12zXyp04@jIcdMc")
EncryptedResult = Encrypt("ID976543", EncryptionKey)
Encryption details
The encryption is performed in such a way that it should be possible for external systems to generate encrypted values that can be decrypted by the Decrypt function, and to decrypt values that have been encrypted by the Encrypt function.
The format of the encrypted value is:
Base64Encode(HeaderByte + [AuthenticationTag] + [IV] + CipherText)
+ means concatenation of bytes.
[ ] means optional.
HeaderByte
The HeaderByte is defined as:
▪Bits 0 – 5: Algorithm identifier. 1 = AES-128. (All other values are currently undefined and reserved for future use.)
▪Bit 6: 1 = IV is included; 0 = IV is absent.
▪Bit 7: 1 = Authentication tag is included; 0 = Authentication tag is absent.
The AuthenticationTag and IV values are optional; they are controlled by the Randomize and AuthenticationTag parameters of the Encrypt function.
Authentication tag
The authentication tag is calculated as a SHA-256 HMAC:
▪If the IV value is included, the HMAC is calculated over a sequence of bytes consisting of the HeaderByte, IV, and CipherText.
▪If the IV value is not included, the HMAC is calculated over a sequence of bytes consisting of only the HeaderByte and the CipherText.
The length of the AuthenticationTag value is always 256-bits.
IV value
If Randomize is requested, a random initialization vector (IV) is generated and included in the output value. The IV value used is stored in the output value so that it can be used when the value is decrypted. If Randomization is not required, a fixed IV value is used. The Base64 encoded representation of that fixed value is ¡°06AiKJFH4s5jqQUfKRIvOQ==¡±.
The length of the IV value depends on the encryption algorithm used (currently, it is always 128-bits).
CipherText value
The CipherText value is the UTF-8 encoded input value after encryption by the specified encryption algorithm. The only supported value is AES-128, which is 128‑bit AES using the CBC block mode and PKCS7 padding. The IV value used as input to the encryption is either a fixed value or a randomly generated value.
Output
The output of the Encrypt function is generated by concatenating the HeaderByte, AuthenticationTag (if required), IV (if required), and CipherText; and then Base64‑encoding that byte sequence. This results in a simple string that can be, for example, stored in a database or passed as a URL parameter.
Decryption
During decryption, the input value is Base64‑decoded back into a byte sequence.
The HeaderByte indicates if the AuthenticationTag and IV values are present, and therefore how to break the byte sequence into individual values.
If the AuthenticationTag is present, the original SHA-256 HMAC calculation is repeated, and then the result is compared against the AuthenticationTag value that was originally calculated and included in the encrypted value.
If the calculated AuthenticationTag is different, this means that the encrypted value has been changed since it was encrypted.
The HeaderByte specifies the decryption algorithm to use (currently, this is always AES-128.) The CipherText can then be decrypted by using either the supplied or fixed IV value with the known or supplied key.
The result is a UTF-8 encoded representation of the input string.
See also