EncryptSymmetric()

Encrypts plain text data using the supplied algorithm and encryption values. You can supply either a value or a valid external key for the password, initialization vector (IV), and salt.

You can also use the external keys if you previously created keys in the Key Management section of the Marketing Cloud Engagement web interface. If you haven't created any keys, the function generates a password using the password parameter or stored value, the salt parameter or stored value, and the IV parameter or stored value. If you don't pass or reference an initialization vector, the function uses the password parameter or stored value as the initialization vector. This function treats Salt and IV values either directly provided or looked up by key as hex strings, with each pair of characters representing a single byte in the larger strings. Don't attempt to use these values as a cipher string, because you can’t successfully decrypt those strings using this function. You can wrap the EncryptSymmetric() and DecryptSymmetric() functions in Base64Encode() and Base64Decode() functions to view the final string in plain text.

You can only use the EncryptSymmetric() and DecryptSymmetric() AMPscript functions on data contained in Marketing Cloud Engagement. You can't use these functions with third-party encryption and decryption functionality.

The EncryptSymmetric() function has eight parameters:

  • data (string): Required. The plain text string to encrypt.
  • encryptionAlgoritm (string): Required. The algorithm to use to encrypt the data. See Encryption Algorithm Options.
  • passwordExternalKey (string): Required. The external key of a password that was created in Key Management.
  • passwordValue (string): Required. The password value.
  • saltExternalKey (string): Required. The external key of a salt in Key Management.
  • saltValue (string): Required. The salt value, represented as an 8-byte hexadecimal string.
  • ivExternalKey (string): Required. The external key of an initialization vector in Key Management.
  • ivValue (string): Required. The initialization vector, represented as a 16-byte hexadecimal string.

To use this function, specify an encryption algorithm. Three algorithms are available.

  • aes — AES (Advanced Encryption Standard)
  • des — DES (Data Encryption Standard)
  • tripledes — Triple DES (applies the DES cipher to each data block three times)

Of these options, AES is the most secure, followed by Triple DES, and then DES.

When you use the DES or Triple DES algorithms, you can optionally specify a mode of operation. To specify a mode of operation, add a semicolon after the algorithm type, followed by mode= and the name of the cipher mode. Five cipher modes are available.

  • cbc - Cipher Block Chaining (default)
  • cfb - Cipher Feedback
  • cts - Ciphertext Stealing
  • ecb - Electronic Codebook
  • ofb - Output Feedback

You can also include a padding method. To specify the padding method, add a semicolon after the mode of operation, followed by padding= and one of these options.

  • ansix923 - ANSI X9.23
  • iso10126 - ISO 10126
  • none - No padding
  • pkcs7 - PKCS#7/RFC 5652 (this is the default padding method)
  • zeros - All bytes padded with zeros

For example, to use Triple DES encryption with Cipher Feedback and ANSI X9.23 padding, specify tripledes;mode=cfb;padding=ansix923 as the value of the second parameter.

This example sets the @encData variable to the encrypted value of the plain text supplied in the function (in this case, the word Example). This example uses provided values for the password, salt, and IV, and it sets any external key values to the undeclared variable @null. The Salt and IV values provided in this example represent hex string values. The Salt value includes 8 bytes of information, and the IV value provides 16 bytes.

This example generates an encrypted string using Triple DES encryption with Cipher Feedback and ANSI X9.23 padding.

The function outputs the encrypted string.