 |
Encr_EncryptAES |
Encrypts text using the AES algorithm and the password.
Syntax
Encr_EncryptAES ( switches ; password ; dataToEncrypt )
Parameters
| switches | modifies the behavior of the function |
| password | the password to use |
| dataToEncrypt | the text (or container data) to encrypt |
Switches
Switches can be one of:
| -KeySize=256 | (default) create a key for AES-256 encryption |
| -KeySize=128 | create a key for AES-128 encryption |
You can add one or more of these switches to retrieve extra information:
| -AddIntializationVectorInfo | add the used Initialization Vector at the end of the result (need not be kept secret) |
| -AddSaltInfo | add the used Salt at the end of the result (need not be kept secret) |
| -AddKeyInfo | add the derived Key (derived from the password) at the end of the result (keep secret!) |
| -OpenSSLCompatible | format as OpenSSL compatible result |
| -HashIterationCount=n | specify 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:
| $$-4244 | no password was given |
Originated in
Troi Encryptor Plug-in 1.2
Compatibility
FileMaker Pro 16 to FileMaker Pro 2023
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 10 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=n 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.
Used in example file
EncryptAES.fmp12
Related functions
| Encr_Code |
| Encr_DecryptAES |
| Encr_EncryptNewDES |
| Encr_GeneratePassword |
Related topics
Troi Encryptor Plug-in online help (overview)
