(Engine-Level Function)
| Description: | The SetKeyParam function customizes various aspects of a session key's operations. The values set by this function are not persisted to memory and can only be used with in a single session. It is the VTScada analog of the CryptoAPI SetKeyParam call. |
| Returns: | Numeric, where 0 indicates success and a non-zero value indicates a system error code. |
Usage:  |
Script Only. |
| Function Groups: | Cryptography |
| Related to: | DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetCryptoProvider | GetKeyParam | ImportKey | TextEncode |
| Format: |
SetKeyParam(Key, Param [, Value, Flags, Error]) |
| Parameters: |
| Key | ||||||||
| Required. The handle to the key for which values are to be set. | ||||||||
| Param | ||||||||
|
Required text or numeric. A parameter specifying the value to be set. CAPI (Cryptography API) providers are specified using numeric identifiers. Values are defined in WinCrypt.h CNG (Cryptography New Generation) algorithm providers are specified using text identifiers. |
||||||||
| Value | ||||||||
|
An optional parameter containing the value to which the keys parameter is to be set. If omitted or invalid then the value 0 is used. Warning: Accidentally passing a value that is meant to be a number but is actually stored as text, "42", will cause an error. |
||||||||
| Flags | ||||||||
| An optional parameter specifying the flags to be passed to CryptSetKeyParam. If omitted or invalid then the value 0 is used. | ||||||||
| Error | ||||||||
Required. An optional variable in which the error code for the function is returned. It has the following meaning:
|
| Comments: |
The allowable values for Param vary with the key type. Certain modes of SetKeyParam take either a binary string of bytes or a text string. It is up to script code to convert the parameter to the appropriate representation depending on the mode used. As an example, when setting the IV, a binary string of bytes is expected, which is the same representation as a string in script code and this can be passed in directly. When setting ChainingMode, a text string with the desired mode is expected, for example “ChainingModeECB”. The underlying API expects this input as utf-16le characters, so script code must first convert this to null terminated utf-16le. This can be achieved using TextEncode: SetKeyParam(Key,
"ChainingMode",
TextEncode(Concat("ChainingModeECB", MakeBuff(1, 0)),
Invalid,
"utf-8",
"utf-16le"),
0,
ErrOut)
|
Example:
[
Constant KP_G = 12 { DSS/Diffie-Hellman G value };
]
Init [
If 1 Main;
[
{ Set the key parameter }
SetKeyParam(Key2, KP_G, KeyG);
]
]
