Encr_AES_CreateKeyAndIV (function reference)

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

Encr_AES_CreateKeyAndIV

Creates an encryption key and initialization vector, which can be used for AES encryption and decryption.

SyntaxFunction badge

Encr_AES_CreateKeyAndIV ( switches ; passphrase ; salt )

Parameters

switchesmodifies the behavior of the function
passphrasethe passphrase (password) to use
salta random text to make encryption more secure, make this 8 to about 20 characters long

Switches

Switches must be one of:

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

Other switches are not (yet) possible.

Returned Result

Data type returned

Text

Result

the created key and the IV each on a separate line. The function can also return an error code. Returned error codes can be:

$$-4244kErrPwdEmptyno passphrase was given
$$-50paramErrParameter error (incorrect key size given)

Originated in

Troi Encryptor Plug-in 3.0

Compatibility

FileMaker Pro 14 to 17

Considerations

This is an advanced function, for exchanging data with other systems. You might want to use the more simple Encr_EncryptAES function.
You use this in conjunction with the Encr_AES_EncryptUsingKey and Encr_AES_DecryptUsingKey functions.

Make the random salt 8 to about 20 characters long (1000 chars is the maximum).

The key is derived from a SHA1 hash of the salt and the passphrase.
You can use AES-128 or AES-256.

Technical details:
AES-128: 128 bit, CBC with a 16 byte key. Blocksize is 16 byte so the IV generated is 16 byte.
AES-256: 256 bit, CBC with a 32 byte key. Blocksize is also 16 byte so the IV generated is 16 byte.

Example

Set Variable [ $KeyAndIV ; Encr_AES_CreateKeyAndIV ( "-KeySize=256" ; "mySecretKey" ; 
                               "bZz%gABQ6lBpfNwgeD?v" ) ]

This will return the encryption key and the initialization vector each on a separate line, the result will be similar to:

ZTBkMDczYzdkN2NhZDNiMjFmMDM1MTdiOWMwM2Q3ZDg=
QXoxqKimWqRGyrpKesrKYQ==

The 2 lines are encoded as base64.
For AES-128 the key and initialization vector are 16 bytes.
For AES-256 the key is 32 bytes and initialization vector is 16 bytes long.

Example 2

With the passphrase and the random salt you can generate the key and the initialization vector suitable for AES-256 encryption. You can use these script steps:

Set Variable [ $Passphrase ; YourPassphraseField // get the passphrase from a field. ]

# set the salt; this should be a random string. 
Set Variable [ $UseFixedTestSalt ; Value:0 ] 

# Generate a 20 character random salt
  Loop 
    Set Variable [ $RandomChar ; Let ( allowedChars = 
        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890!@#$%&*+?" ; 
        Middle ( allowedChars ; Int ( Random * Length ( allowedChars ) ) + 1 ; 1 ) ) ] 
    Set Variable [ $Salt ; $Salt & $RandomChar ] 
    Exit Loop If [ Length ( $Salt ) >= 20 ]
  End Loop 
End If
# Set the wanted keysize: The sizes are given in bits...
# ... This is a key of 32 byte and IV of 16 byte.
Set Variable [ $Switches ; "-KeySize=256" ]

# Generate the key now:
Set Variable [ $KeyAndIV ; Value : Encr_AES_CreateKeyAndIV ( $Switches ; $Passphrase ; $Salt ) ]

If [ Left ( $KeyAndIV ; 2 ) = "$$" ] 
    Set Field [ this::gErrorCode ; $KeyAndIV ] 
    Perform Script [ “ Handle Errors” ]
Else
  Set Field [ this::gErrorCode ; 0 ] 

# NOTE the result is on two lines: first the key and the IV on the next line.
# The key and IV are Base64 encoded. 

Set Variable [ $Key ; Value : Left ( $KeyAndIV ; Position ( $KeyAndIV ; "¶" ; 1 ; 1 ) - 1 ) ] 
Set Variable [ $IV ; Value : Middle ( $KeyAndIV ; Position ( $KeyAndIV ; "¶" ; 1 ; 1) + 1 ; 
				Length ( $KeyAndIV ) ) ] 

Now the key + IV are generated, you can encrypt data with the Encr_AES_EncryptUsingKey function.

Related functionsFunction badge

Encr_AES_DecryptUsingKey
Encr_AES_EncryptUsingKey
Encr_Code
Encr_EncryptAES

Related topics

Troi Encryptor Plug-in online help (overview)


Online Help Page for Troi Encryptor Plug-in for 14 to 17 –> Encr_AES_CreateKeyAndIV (encrp4322) 2019-0212 18:00:37