GetCryptoProvider

(Engine-Level Function)

Description:	The GetCryptoProvider function is used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned handle can then be used to make calls to the selected CSP. It is the VTScada analog of the CryptoAPI CryptAcquireContext call.
Returns:	Handle
Usage:	Script Only.
Function Groups:	Cryptography
Related to:	DeriveKey | Decrypt | Encrypt | ExportKey | GenerateKey | GetKeyParam | ImportKey | SetKeyParam
Format:	GetCryptoProvider(CSPType [, CSPName, ContainerName, Flags, Error])
Parameters:

CSPType

Required text or numeric. The type of CSP required. . 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.

CSPName

An optional parameter that holds the name of the required CSP. If omitted or invalid, then a handle to the default CSP of the specified type will be acquired.

ContainerName

An optional parameter that holds the name of the key container. If omitted or invalid, then the default key container for the CSP is used.

Flags

An optional parameter specifying the flags to be passed to CryptAcquireContext. If omitted or invalid then the value 0 is used.

Error

An optional variable in which the error code for the function is returned. It has the following meaning Error Meaning 0 CSP handle successfully returned. 1 CSPType parameter invalid. x Any other value is an error from CryptAcquireContext.

Comments:

The return value for this function is a handle to the CSP. If an error occurs, then the return value is invalid. A CSP handle has a value type of 36. If cast to text then the name of the CSP will be returned. If ContainerName is omitted or invalid then a default key container name is used. For example, the Microsoft Base Cryptographic Provider uses the account name of the user signed in as the key container name. Other CSPs can also have default key containers that can be acquired in this way.

Examples:

[
  CSP;
  Constant PROV_DSS_DH = 13;
]
Init [
  If 1 Main;
  [
    CSP = GetCryptoProvider(PROV_DSS_DH);
...

Would obtain a handle to a CAPI cryptographic provider.

    CSP = GetCryptoProvider("AES", …);

Would obtain a handle to a CNG algorithm provider. The algorithm provider is typically used as an input parameter to ImportKey. For example:

    ImportKey(GetCryptoProvider("AES"), Invalid, KeyMaterial);

 

[
  CSP;
  CSPFail;
  Container = "VTS";
  Constant PROV_DSS_DH = 13;
  Constant CRYPT_NEWKEYSET = 8;
  Constant NTE_BAD_KEYSET = 0x80090016;
]
Init [
  If 1 Main;
  [
    CSP = GetCryptoProvider(PROV_DSS_DH, Invalid,
                            Container, Invalid, CSPFail);
    IfThen(CSPFail == NTE_BAD_KEYSET,
       { Not used this container before, make a new one }
       CSP = GetCryptoProvider(PROV_DSS_DH, Invalid,
                            Container, CRYPT_NEWKEYSET, CSPFail);
    );
  ]
]