 |
Encr_AES_CreateKeyAndIV |
Creates an encryption key and initialization vector, which can be used for AES encryption and decryption.
Syntax
Encr_AES_CreateKeyAndIV ( switches ; passphrase ; salt )
Parameters
| switches | modifies the behavior of the function |
| passphrase | the passphrase (password) to use |
| salt | a 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=128 | create 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:
| $$-4244 | kErrPwdEmpty | no passphrase was given |
| $$-50 | paramErr | Parameter error (incorrect key size given) |
Originated in
Troi Encryptor Plug-in 3.0
Compatibility
FileMaker Pro 16 to FileMaker Pro 2023
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.
Used in example files
EncryptAES.fmp12
OpenSSL.fmp12
Related functions
| Encr_AES_DecryptUsingKey |
| Encr_AES_EncryptUsingKey |
| Encr_Code |
| Encr_EncryptAES |
Related topics
Troi Encryptor Plug-in online help (overview)