Encr_EncryptAES (function reference)

By February 1, 2019 February 12th, 2019 Online Help, Troi Encryptor Plug-in
Troi Encryptor Plug-in for FileMaker Pro

Encr_EncryptAES

Encrypts text using the AES algorithm and the password.

SyntaxFunction badge

Encr_EncryptAES ( switches ; password ; dataToEncrypt )

Parameters

switchesmodifies the behavior of the function
passwordthe password to use
dataToEncryptthe text (or container data) to encrypt

Switches

Switches can be one of:

-KeySize=256(default) create a key for AES-256 encryption
-KeySize=128create a key for AES-128 encryption

You can add one or more of these switches to retrieve extra information:

-AddIntializationVectorInfoadd the used Initialization Vector at the end of the result (need not be kept secret)
-AddSaltInfoadd the used Salt at the end of the result (need not be kept secret)
-AddKeyInfoadd the derived Key (derived from the password) at the end of the result (keep secret!)
-OpenSSLCompatibleformat as OpenSSL compatible result
-HashIterationCount=nspecify the hash iteration count used to generate the key and initialization vector (for OpenSSL)

Returned Result

Data type returned

Text

Result

the encrypted text or an error code.

Returned error codes can be:

$$-4244no password was given

Originated in

Troi Encryptor Plug-in 1.2

Compatibility

FileMaker Pro 14 to 17

Considerations

NOTE The Encr_EncryptAES function was called Encr_EncryptRijndaelAES in older versions of the plug-in.

– Be sure to remember the password (case sensitive!): without it you can not retrieve the original data.
– It’s good practice to use a password that is at least 8 characters long. You can use higher Unicode characters!
– Don’t store the password.
– Use a global for the password field.
– The encrypted text is different every time you encrypt the same text. This is not a bug, but a security feature!

Technical details:

By default (or if you use the switch -KeySize=256) the text is encrypted using AES-256 bit CBC with a 32 byte key and 16 byte IV (derived via PBKDF2) and 20 byte salt. Padding according to PKCS7. Result is Base64 encoded.

If you use the switch -KeySize=128 the text is encrypted using AES-128 bit CBC with a 16 byte key and IV (derived via PBKDF2) and 20 byte salt. Padding according to PKCS7. Result is Base64 encoded.

More technical details can be found at the beginning of the user guide.

About Unicode and Passwords:
Passwords are always UTF8 encoded before the key is derived. This means that all Unicode characters can be used for the password.
For example:
“japan_” becomes “japan_0xE698BEE7A4BA” as password
“españa” becomes “espa0xC3B1a” as password

Text is also UTF8 encoded before encryption.

Containers:
– You can also encrypt any type of container field, even containers that store a reference only. Note that for those containers only the reference is encrypted, not the original. This applies for all reference pictures and QuickTime movies.

Container data consists of several streams. Each stream is converted to base64 and this text is then encrypted. The text is formatted like this:

<TROI_BINARY_CONTAINER10><number of streams>
<- ->
<length stream1><stream1 data>
<- ->
<length stream2><stream2 data>
<- ->
<length stream3><stream3 data>

</TROI_BINARY_CONTAINER10>

About OpenSSL compatibility (introduced with Troi Encryptor 5.0):

When you use the -OpenSSLCompatible switch, the encrypted text is formatted as OpenSSL compatible (Base64) text.
This can be decrypted with the OpenSSL functions of PHP 7. You can specify the hash iteration count used to generate the key and initialization vector with the optional -HashIterationCount=n switch. Use for example -HashIterationCount=10000.
Note that the default for -OpenSSLCompatible is 1.
You can also encrypt for the openssl command in a command line interface (for example the macOS terminal). Use the switch -OpenSSLCompatible, but don’t use the -HashIterationCount=x switch as the openssl command expects the (default) iteration count of 1.

See the OpenSSL.fmp12 example in the download for more detailed information.

Example

Encr_EncryptAES ( "-Unused" ; "mypassword" ; "mySecretTexts" )

This will give this result (or similar, as the encrypted text is different every time):

<TROI_AES_STD_ENCR10>
NVFJPSV9fX19fX19fX19fbpsts4SthcI/85T5dcjEv7IsuDGy72Z/t4bfFUyOY7A2ITa3jzEx
wyy+kHnWsgo/IJ1d7BZeRWA6Wbtzn8/xyAgm47SuJ167SJMLb5k/Kl11dKFuaQ==
</TROI_AES_STD_ENCR10>

Example 2

In a database you have defined a text field named “patientData” which contains illness data. Then define a calculation field:

encryptedDataCalc    calculation   Unstored  = Encr_EncryptAES ( "-Unused" ; 
							gPasswordField ; patientData )

the calculation field will contain the encrypted text.

Example 3

Set Field [ secretField ;   
                 Encr_EncryptAES ( "-AddSaltInfo" ;  gEncryptionPassword ; textField ) ]

this will result in:

<TROI_AES_STD_ENCR10>
NVFJPSV9fX19fX19fX19fbkO656mTvKWiWbKQqul7R5tZd7+aQ3h0QaLQOO6EUtFjxDLRxNQp
rwFN1JhuE5SNPaSBWbCrteX7uPmqKpdyFrmcGwqX7CjZ5cE/ISIwD6LWh3hguv1JObZqj7+n
fWhvu4AflFM765T8hlg6BbeHjI2oUwGz
</TROI_AES_STD_ENCR10>

<TROI_SALT>43bae7a993bca5a259b290aae97b479b5977bf9a</TROI_SALT>

The last part contains the so called Salt, which was used to change the encryption result. NOTE: Normally it is not necessary to know about Salt, IV’s and derived Keys to use it. If you want to decrypt the data on a non-FileMaker system it might be useful.

Related functionsFunction badge

Encr_Code
Encr_DecryptAES
Encr_EncryptNewDES
Encr_GeneratePassword

Related topics

Troi Encryptor Plug-in online help (overview)


Online Help Page for Troi Encryptor Plug-in for 14 to 17 –> Encr_EncryptAES (encrp4275) 2019-0212 17:42:38