CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code

Article
05/31/2018

Adds a cryptographic key container to the list of keys that are replicated for a resource. Applications use this control code as a ClusterResourceControl parameter.

ClusterResourceControl( 
  hResource,                              // resource handle
  hHostNode,                              // optional host node
  CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT, // this control code
  lpInBuffer,                             // input buffer: string
  cbInBufferSize,                         // input buffer size (bytes)
  NULL,                                   // not used
  0,                                      // not used
  NULL );                                 // not used

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpInBuffer

Pointer to a null-terminated Unicode string that specifies the Cryptographic Service Provider (CSP) key container to be replicated. The CSP key container must first be created with the Cryptography API and the keys in the container must be exportable. The string must specify the CSP provider type, provider name, and key container name using the following syntax:

Type\Name\Key

Note that the values must be separated by a '\'. The provider type should specify the decimal value of the type, not the constant that represents the value. For example, instead of "PROV_RSA_FULL" use "1". The provider name is optional, if omitted, the default CSP provider name associated with the specified provider type will be used.

Return value

ClusterResourceControl returns one of the following values:

ERROR_SUCCESS: The operation was successful.
NTE_BAD_KEY: The keys in the specified container are not exportable. For more information, see CryptGenKey.
NTE_BAD_KEYSET: The specified key container does not exist. For more information, see CryptAcquireContext.
System error code: The operation failed.

Remarks

Only exportable, machine-level keysets can be used for cluster crypto checkpoints.

For more information on the following points, see the Cryptography_Reference.

A key container is given a name when it is created using CryptAcquireContext with dwFlags set to CRYPT_NEWKEYSET.
Once a key container has been created, the key pairs for that key container must be created using CryptGenKey with the dwFlags parameter set to CRYPT_EXPORTABLE. Note that some CSPs do not allow key exports from their key containers. If a key is not exportable then the ClusterResourceControl call will fail with an NTE_BAD_KEY error.
C programs that create key sets need to be compiled and linked by using WinCrypt.h and AdvApi32.lib.

For more information on cluster programming, refer to the following sections:

For information on working with control codes, see Using Control Codes.
For information on cluster registry checkpointing, see Cluster Database.
Cluster-aware applications need to be compiled and linked using ClusAPI.h, ClusAPI.lib, Resource.h, and ResUtils.lib. For an example of cluster-related compiler directives, see ClusDocEx.h.

ClusAPI.h defines the 32 bits of CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT as follows (for more information, see Control Code Architecture).

Component	Bit location	Value
Object code	24 31	CLUS_OBJECT_RESOURCE (0x1)
Global bit	23	CLUS_NOT_GLOBAL (0x0)
Modify bit	22	CLUS_MODIFY (0x1)
User bit	21	CLCTL_CLUSTER_BASE (0x0)
Type bit	20	External (0x0)
Operation code	0 23	CLCTL_ADD_CRYPTO_CHECKPOINT (0x4000ae)
Access code	0 1	CLUS_ACCESS_WRITE (0x2)

Resource DLL Support

The CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code is handled by the Cluster service and is not passed to resource DLLs.

Examples

//
// The following line creates a string used to checkpoint a
// key container with the following attributes:
//     provider type  = 1 (PROV_RSA_FULL)
//     provider name  = Microsoft Base Provider
//     container name = MyKey 
// Note the use of double backslashes "\\".
// 
WCHAR szCryptoCheckpoint[] = L"1\\Microsoft Base Cryptographic Provider v1.0\\MyKey";

//
// The following line creates a string used to checkpoint a
// key container with the following attributes:
//     provider type  = 1 (PROV_RSA_FULL)
//     provider name  = not specified; default will be used
//     container name = MyKey 
// Note the use of double backslashes "\\".
// 
WCHAR szCryptoCheckpoint[] = L"1\\\\MyKey";

DWORD dwResult = ClusterResourceControl(
                     hRes,
                     NULL,
                     CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT
                     (LPVOID) szCryptoCheckpoint
                     ( lstrlenW( szCryptoCheckpoint ) + 1 ) * sizeof( WCHAR ),
                     NULL,
                     0,
                     NULL );

if( dwResult != ERROR_SUCCESS )
{
    // Handle error.
}

Requirements


Minimum supported client	None supported
Minimum supported server	Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Header	ClusAPI.h