Encrypt

(Engine-Level Function)

Description:	The Encrypt function encrypts data. The algorithm used to encrypt the data is designated by the Key parameter. It is the VTScada analog of the Windows CryptoAPI CryptEncrypt call. Encrypt fully supports asymmetric and symmetric keys via CNG (Cryptography New Generation).
Returns:	Text
Usage:	Script Only.
Function Groups:	Cryptography
Related to:	DeriveKey \| Decrypt \| Encrypt \| ExportKey \| GenerateKey \| GetCryptoProvider \| GetKeyParam \| ImportKey \| SetKeyParam
Format:	Encrypt(Key, PlainText, Final [, Reserved, Flags, Error])
Parameters:

Key

Required. The handle to the key to use to encrypt the data.

PlainText

Required. A text string that contains the plain text to be encrypted.

Final

Required. A parameter that specifies whether this is the last section in a series being encrypted.
Final is set TRUE for the last or only block and FALSE if there are more blocks to be encrypted

Reserved

An optional parameter that should be set to 0. If omitted or invalid, then the value 0 is used.

Flags

Optional. Specifies the flags to be passed to CryptEncrypt. If omitted or invalid then the value 0 is used. Refer to the Crypto API Encrypt function for the flag list if using CAPI.

If using a CNG key, the following may be used (separate tables provided for asymmetric and symmetric keys)

If the encryption key is an asymmetric key:

Value	Meaning
0	No padding is to added to the plaintext data before encryption.
1	Padding is added to the plaintext data before encryption in accordance with the RSAES-PKCS1-v1_5 scheme.
2	Padding is added to the plaintext data before encryption in accordance with the RSAES-OEAP scheme, using SHA1 for padding generation.
3	Padding is added to the plaintext data before encryption in accordance with the RSAES-OEAP scheme, using SHA256 for padding generation.

If the encryption key is a symmetric key:

Value	Meaning
0	No padding is to added to the plaintext data before encryption.
1	Padding is added to the plaintext data before encryption.

Error

Optional. A variable in which the error code for the function is returned. It has the following meaning: (no default)

Error	Meaning
0	Key successfully imported.
1	Key, PlainText or Final parameters invalid.
x	Any other value is an error from CryptEncrypt.

Comments:

The cipher text is returned as a text string. If an error occurs, the return value is invalid.

When using CNG keys, the data supplied to Encrypt must be an integer multiple of the symmetric key block size UNLESS Flags is set to one of the padding options, when the algorithm will automatically pad the plaintext as required.

Note that the size of a block can be obtained using the GetKeyParam function and specifying the "BlockLength" property.

Example:

[
  PlainText1 = "abcdefghijklmnopqrstuvwxyz0123456789"; 
  CipherText1; 
]
Init [
If 1 Main; 
  [ 
    CipherText1 = Encrypt(Key3, PlainText1, 1, 0, 0); 
  ] 
]