# Troi Encryptor Plug-in 8.0 for FileMaker Pro 2023 and Claris Pro 40 USER GUIDE April 2023 You can visit the Troi web site at: www.troi.com Troi Encryptor Plug-in is copyright 1998-2023 of Troi Automatisering. All rights reserved. # Table of Contents Installing plug-ins If you have problems What can this plug-in do? Software requirements Getting started Using external functions Using script steps Simple example You can use globals or variables AES Encryption What is AES? What do I need to know about AES? How is AES implemented in Troi Encryptor? Getting extra information Container fields About OpenSSL compatibility Message digests SHA-1, SHA-256 and MD5 algorithms What is a hash algorithm? Function and script step reference ## Installing plug-ins Starting with FileMaker Pro 12 a plug-in can be installed directly from a container field. Installation is therefore very easy: just open the "All Encryptor Examples.fmp12" example file and the startup script will install the plug-in for you. See also the EasyInstallTroiPlugins.fmp12 example file which contains the actual plug-in and install script. TIP You can check which plug-ins you have loaded by going to the plug-in preferences: choose Preferences from the Edit menu, and then choose Plug-ins. You can now open the file "All Encryptor Examples.fmp12" to see how to use the plug-in's functions. There is also a function and script step reference available. ## If you have problems This user guide tries to give you all the information necessary to use this plug-in. So if you have a problem please read this user guide first. You can also visit our support web page: www.troi.com/support This page contains FAQ's (Frequently Asked Questions), help on registration and much more. If that doesn't help, you can get free support by email. Send your questions to support@troi.com with a full explanation of the problem. Also give as much relevant information (version of the plug-in, which platform, version of the operating system, version of FileMaker Pro) as possible. Note that due to spam we have to filter incoming email. It might happen that non-spam email is filtered out too. If you have sent an email and you don't get an answer, try to send another email, slightly differently formulated and include the word "FileMaker" in the body text. If you find any mistakes in this manual or have a suggestion, please let us know. We appreciate your feedback! TIP You can get more information on returned error codes from the OSErrrs database on our web site. This free FileMaker database lists all error codes for Windows and macOS! ## What can this plug-in do? Troi Encryptor Plug-in is a very powerful tool for dealing efficiently with encryption in your FileMaker Pro database. All from within FileMaker you can: Encrypt and decrypt text fields Encrypt and decrypt container fields, with for example JPEGs in them Create SHA-1 and SHA-256 Message Digests Generate secure passwords And more... The plug-in can use a standard industry strength, 256 bit AES Encryption scheme. And the plug-in is upward and downward compatible with data encrypted with Troi Encryptor Plug-in 2.5.x. It is also still upward compatible with data encrypted with Troi Coding 1.6 for FileMaker Pro 6! ## Software requirements NOTE The minimum supported FileMaker version is now FileMaker Pro 16. Also the minimum supported macOS version is now macOS 10.15 (Catalina). The minimum supported Windows version is now Windows 10. ### System requirements for macOS macOS 10.15 (Catalina) macOS 11.0 (Big Sur) macOS 12 (Monterey) macOS 13 (Ventura) ### System requirements for Windows Windows 10 including these updates: Creators Update Fall Creators Update April 2018 Update October 2018 Update May 2019 Update November 2019 Update May 2020 Update October 2020 Update May 2021 Update Windows 11 including this update: 22H2 (September 20, 2022 Update) ### FileMaker Pro requirements FileMaker Pro 16 or FileMaker Pro Advanced 16 FileMaker Pro Advanced 17 FileMaker Pro Advanced 18 FileMaker Pro 19 FileMaker Pro 2023 (FileMaker Pro 20.1) ### Claris Pro requirements Claris Pro 40.1 Claris Pro 40.2 ### FileMaker Server requirements FileMaker Server 16 FileMaker Server 17 FileMaker Server 18 FileMaker Server 19 You can use FileMaker Server to serve databases that use functions of Troi Encryptor Plug-in (client-side): you need to have the plug-in installed at the clients that use these functions. Troi Encryptor Plug-in can also be used by FileMaker Server as a server-side plug-in or as a plug-in used by the web publishing engine. To use Troi plug-ins as a server-side or web-side plug-in you need to purchase a special Server/Web license. More information can be found in the download or on our web site. ## Getting started ### Using external functions Troi Encryptor Plug-in adds new functions to the standard functions that are available in FileMaker Pro. The functions added by a plug-in are called external functions. You can see those extra functions for all plug-ins at the top right of the Specify Calculation box: You use special syntax with external functions: FunctionName ( parameter1 ; parameter 2 ) where FunctionName is the name of an external function. A function can have zero or more parameters. Each parameter is separated by a semi-colon. Plug-ins don't work directly after installation. To access a plug-in's function, you need to add the calls to the function in a calculation, for example in a text calculation in Define Fields or in a script in Script Workspace (formaly called ScriptMaker). ### Using script steps Starting with FileMaker 16 plug-ins can also add script steps. You can select these script steps in the script steps pane in Script Workspace, or you can begin typing the script step name, then choose the script step from the list that appears. The script steps expand the possible actions you can perform with FileMaker Pro. screenshot of Troi File Plug-in script step NOTE only steps that perform an action have been added as a script step. Functions that just manipulate data and have no side effects (like for example Encr_EncryptAES) are only available as an external function. ### Simple example This example shows how to begin using Troi Encryptor Plug-in. Say you have a database Secrets.fmp12, with a text field called myText, and a text field called EncryptedField. Now add the following script step to a script:
      Set Field [ EncryptedField ; Encr_EncryptAES ( "-Unused" ; "secret" ; myText ) ]
NOTE The Encr_EncryptAES function was called Encr_EncryptRijndaelAES in older versions of the plug-in. This will encrypt the text from the field myText into the EncryptedField, using the password "secret". This gives this result (or similar, as the encrypted text is different every time):
      <TROI_AES_STD_ENCR10>
      NVFJPSV9fX19fX19fX19fbpsts4SthcI/85T5dcjEv7IsuDGy72Z/t4bfFUyOY7A2ITa3jzEx
      wyy+kHnWsgo/IJ1d7BZeRW A6Wbtzn8/xyAgm47SuJ167SJMLb5k/Kl11dKFuaQ==
      </TROI_AES_STD_ENCR10>
Now the original text can be deleted, but be sure to remember your password, as otherwise you can not retrieve the original text. NOTE Function names, like Encr_EncryptAES, are not case sensitive. Please take a close look at the included example files, as they provide a great starting point. From there you can move on, using the functions of the plug-in as building blocks. Together they give you all the tools you need to perform powerful encryption and coding. ### You can use globals or variables With the release of FileMaker Pro 8 and later it is possible to use variables in calculations. Our example files in the download now both use global fields and variables to pass parameters and store the results of a plug-in function. As this release of Troi Encryptor is intended for FileMaker Pro 16 and higher, we continue to move the scripts to use variables wherever possible. Note that not all examples are using variables yet. All plug-in functions work with variables just fine. For example if you have this script step
      Set Field [ EncryptedField ; Encr_EncryptAES ( "-Unused" ; "secret" ; myText ) ]
With variables you can alternatively use:
      Set Variable [ $EncryptedText ; Encr_EncryptAES ( "-Unused" ; "secret" ; $myText ) ]
The main advantage of variables is that you don't need to define global fields that clutter your database definitions. The variables can stay local to the script. ## AES Encryption ### What is AES? The Advanced Encryption Standard (AES), also known as Rijndael, is a block cipher adopted as an encryption standard by the US government. It was adopted by National Institute of Standards and Technology (NIST) as US FIPS PUB 197 in November 2001. See also: https://www.nist.gov/ https://csrc.nist.gov/groups/ST/toolkit/ The cipher was developed by two Belgian cryptographers, Joan Daemen and Vincent Rijmen, and submitted to the AES selection process under the name "Rijndael". Rijndael can be pronounced "Rhine dahl", a long "i" and a silent "e". AES is considered to be very secure. AES has the potential to remain secure well beyond twenty years. The strength of AES make it very useful in complying with HIPAA guidelines. For compatibility with Troi Coding Plug-in, the Troi Encryptor Plug-in also still implements the newDES algorithm. Note that newDES is less secure than AES. TIP It is recommended that for new projects you use AES encryption. ### What do I need to know about AES? To be able to work with the plug-in you don't need to know all the technical details. But for those interested the details are in the next section below. Here are some things you do need to know: 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. Note that the plug-in can generate safe passwords, and check its strength. See the GeneratePassword.fmp12 example. 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! ### How is AES implemented in Troi Encryptor? Troi Encryptor Plug-in implements AES in two ways: the Encr_EncryptAES function provides an easy way to encrypt, where you provide a password to encrypt the data. You can also use a more advanced approach, with these 3 functions: Encr_AES_CreateKeyAndIV, Encr_AES_EncryptUsingKey and Encr_AES_DecryptUsingKey, where from a passphrase an encryption key and initialization vector is generated. With the key and initialization vector you can then encrypt and decrypt your data. This provides the standard AES-256 or AES-128 implementation. This makes it possible to exhange encrypted data with external systems, for example PHP-mcrypt. The Encr_EncryptAES function is implemented as follows: 1) Convert the input plaintext The source plaintext is encoded from the FileMaker native Unicode to UTF8. 2) The password is converted to UTF8 Passwords are UTF8 encoded before the key is derived. This means that all Unicode characters can be used for the password. For example:
"japan_ xx" | becomes "japan_0xE698BEE7A4BA" as password ( xx are japanese characters)
"españa" | becomes "espa0xC3B1a" as password
3) Generation of derived key, Initialization Vector and Salt. From the UTF8 password a 32 byte encryption key and a 16 byte Initialization Vector (IV) are derived. This is done via the PBKDF2 standard (RFC 2898 - PKCS #5: Password-Based Cryptography Specification Version 2.0). See: http://www.faqs.org/rfcs/rfc2898.html Also a 20 byte salt is generated, which will make the encryption result different each time, making it more secure. The IV is used in an initial step in the encryption of data and in the corresponding decryption of the data. The IV need not be secret; however, for the CBC modes, the IV for any particular execution of the encryption process must be unpredictable. This is the case with Troi Encryptor. 4) Encryption of the data Starting with v3.0 the data is encrypted using AES-256: this is a 256 bit encryption key, CBC with blocksize and IV of 16 byte and a 20 byte salt. Padding is done according to PKCS7. This results in the <Encrypted Data>. 5) Extra information Extra information is added at the beginning, like this:
<TROI internal use only> | 16 bytes
<Salt> | 20 bytes
<SHA-1 digest of the password> | 40 bytes (for a 20 byte hash, hex encoded, is also encrypted)
<Encrypted Data> | actual length
6) This result is Base64 encoded 7) The plug-in adds a two tags around the final result: <TROI_AES_STD_ENCR10> NVFJPSV9fX19fX19fX19fbpsts4SthcI/85T5dcjEv7IsuDGy72Z/t4bfFUyOY7A2ITa3jzEx wyy+kHnWsgo/IJ1d7BZeRW A6Wbtzn8/xyAgm47SuJ167SJMLb5k/Kl11dKFuaQ== </TROI_AES_STD_ENCR10> ### Getting extra information If you want to know the derived key, Initialization Vector or Salt you can add one or more of these switches to retrieve more 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 at the end of the result (always keep secret!)
For example:
      Set Field [ secretField ; Encr_EncryptAES ( "-AddSaltInfo" ; gEncryptionPassword ; textField ) ]
this will result in: <TROI_AES_STD_ENCR10> NVFJPSV9fX19fX19fX19fbkO656mTvKWiWbKQqul7R5tZd7+aQ3h0QaLQOO6EUtFjxDLRxNQp rwFN1JhuE5SNPaSBWbCrteX7uPmqKpdyFrmcGwqX7CjZ5cE/ISIwD6L Wh3hguv1JObZqj7+n fWhvu4AflFM765T8hlg6BbeHjI2oUwGz </TROI_AES_STD_ENCR10> <TROI_SALT>43bae7a993bca5a259b290aae97b479b5977bf9a</TROI_SALT> ### Container fields 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 Troi Encryptor Plug-in formats the container data like this: <TROI_BINARY_CONTAINER10><number of streams> <- -> <length stream1><stream1 data> <- -> <length stream2><stream2 data> <- -> <length stream3><stream3 data> ... </TROI_BINARY_CONTAINER10> The resulting text is then encrypted the same way as a text field would be. ## About OpenSSL compatibility Extensive OpenSSL compatibility was introduced with Troi Encryptor 5.0. You can now AES-256 encrypt text with the plug-in and and decrypt it with the OpenSSL functions of PHP 7. You can also decrypt text with the plug-in which was encrypted with the OpenSSL functions of PHP 7. When you use the Encr_EncryptAES function with 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 hash iteration count for -OpenSSLCompatible is 1. The reverse is also possible: you can encrypt your data for example with the OpenSSL functions of PHP 7 and use the Encr_DecryptAES function with the -OpenSSLCompatible switch to decrypt it with the Encryptor Plug-in. 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. Decryption is also possible. See also the OpenSSL.fmp12 example and the php example scripts in the download for more detailed information. ## Message digests ### SHA-1, SHA-256 and MD5 algorithms SHA-1 is the Secure Hash Algorithm (SHA), which was developed by NIST and is specified in the Secure Hash Standard (SHS, FIPS 180). SHA-1 is a revision to this version and was published in 1994. It is also described in the ANSI X9.30 (part 2) standard. SHA-1 produces a 160-bit (20 bytes) message digest. SHA-256 was developed by the NSA and produces a 256-bit (32 bytes) message digest. This larger digest size makes SHA-256 stronger against brute force attacks. MD5: MD5 was developed by Professor Ronald L. Rivest in 1994. Its 128 bit (16 byte) message digest makes it a faster implementation than SHA-1. NOTE both MD5 and SHA-1 are no longer considered collision-free/unique. You can find more info on this here: https://www.mscs.dal.ca/~selinger/md5collision/ https://en.wikipedia.org/wiki/SHA-1 So it is better to use SHA-256 when more security is needed. In this case, the fingerprint (message digest) is non-reversible: your data can not be retrieved from the message digest, yet the digest uniquely identifies the data. ### What is a hash algorithm? MD5, SHA-1 and SHA-256 are hash algorithms for computing a 'condensed representation' of a message or a data file. The 'condensed representation' is of fixed length and is known as a 'message digest' or 'fingerprint'. What makes this useful, is that it is computationally infeasible to produce two messages having the same message digest. This uniqueness enables the message digest to act as a 'fingerprint' of the message. This opens up the possibility of using this technology for issues like data integrity and comparison checking. For instance when you download or receive a text, you can use SHA-256 to guarantee that you have the correct, unaltered text by comparing its hash with the original. You are essentially verifying the text's integrity. ## Function and script step reference For a description of all External Functions and External Script Steps added by Troi Encryptor Plug-in please see the separate Reference.fmp12 file. For each function and script step you will find: the correct syntax the parameters/options to be used the returned result special considerations an example usage The same information is also available as online help on Troi's web site. You can easily consult the online help directly from FileMaker, by clicking the Help button (the small question mark button) next to the function description in the functions pane or the script step description in the script steps pane.