logo: Troi Encryptor Plug-in for FileMaker

Troi Encryptor Plug-in 4.0
for FileMaker Pro 16
USER GUIDE

February 2019







logo: Troi Plug-ins for FileMaker

Troi
Boliviastraat 11
2408 MX Alphen aan den Rijn
The Netherlands

You can visit the Troi web site at: www.troi.com

Troi Encryptor Plug-in is copyright 1998-2019 of Troi Automatisering. All rights reserved.








Table of Contents


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 Mac OS!


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 MD5 or SHA1 Message Digests
  • 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

System requirements for Mac OS

Mac OS X 10.7 (Lion), OS X 10.8 (Mountain Lion), OS X 10.9 (Mavericks), OS X 10.10 (Yosemite), OS X 10.11 (El Capitan), macOS Sierra (OS X 10.12).

NOTE Troi Encryptor Plug-in 4 will probably run on Mac OS X 10.6.8 (Snow Leopard), but we have not tested this and no longer provide support for this.

System requirements for Windows

Windows 7 on Intel-compatible computer 1 GHz or faster
Windows 8, Windows 8.1
Windows 10

FileMaker Pro requirements

FileMaker Pro 12 or FileMaker Pro Advanced 12 or higher.
FileMaker Pro 13 or FileMaker Pro Advanced 13 or higher.
FileMaker Pro 14 or FileMaker Pro Advanced 14 or higher.
FileMaker Pro 15 or FileMaker Pro Advanced 15 or higher.
FileMaker Pro 16 or FileMaker Pro Advanced 16 or higher.

FileMaker Server requirements

FileMaker Server 12 or FileMaker Server Advanced 12.
FileMaker Server 13 or FileMaker Server Advanced 13.
FileMaker Server 14 or FileMaker Server Advanced 14
FileMaker Server 15 or FileMaker Server Advanced 15.
FileMaker Server 16 or FileMaker Server Advanced 16.

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:

External functions in 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.

Script steps in the script steps in Script Workspace 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_EncryptRijndaelAES) 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_EncryptRijndaelAES ( "-Unused" ; "secret" ; myText ) ]

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_EncryptRijndaelAES, 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 12 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_EncryptRijndaelAES ( "-Unused" ; "secret" ; myText ) ]

With variables you can alternatively use:

  Set Variable [ $EncryptedText ; Encr_EncryptRijndaelAES ( "-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.


Rijndael 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:

            http://www.nist.gov/
            http://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 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!

How is AES implemented in Troi Encryptor?

Troi Encryptor Plug-in implements AES in two ways: the Encr_EncryptRijndaelAES 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_EncryptRijndaelAES 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_EncryptRijndaelAES ( "-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.

Message digests

SHA-1 and MD5 algorithms

SHA-1 is the Secure Hash Algorithm (SHA) 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 byte) message digest. Although slower than MD5, this larger digest size makes it 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 MD5 is no longer considered collision-free/unique. You can find more info on this here:
             http://www.mscs.dal.ca/~selinger/md5collision/

So it is better to use SHA-1 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 and SHA-1 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 issue like data integrity and comparison checking.

For instance when you download or receive a text, you can use SHA-1 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.