CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code
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.
-
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 |
|