DrtRegisterKey function (drt.h)

Article
10/13/2021

The DrtRegisterKey function registers a key in the DRT.

Syntax

HRESULT DrtRegisterKey(
  [in]           HDRT                      hDrt,
  [in]           DRT_REGISTRATION          *pRegistration,
  [in, optional] PVOID                     pvKeyContext,
  [out]          HDRT_REGISTRATION_CONTEXT *phKeyRegistration
);

Parameters

[in] hDrt

A pointer to a handle returned by the DrtOpen function.

[in] pRegistration

A pointer to a handle to the DRT_REGISTRATION structure.

[in, optional] pvKeyContext

Pointer to the context data associated with the key in the DRT. This data is passed to the key-specific functions of the security provider.

[out] phKeyRegistration

Pointer to a handle for a key that has been registered.

Return value

This function returns S_OK on success. Other possible values include:

Return code	Description
E_INVALIDARG	pRegistration is NULL The cb value of the appData member of the DRT_REGISTRATION structure is too large (ie. less than 1). The cb value of the appData member of the DRT_REGISTRATION structure is too large (ie. more than 5120). The pb value of the key member of the DRT_REGISTRATION structure is NULL. phKeyRegistration is NULL
E_HANDLE	hDrt is an invalid handle or phKeyRegistration is an invalid handle
DRT_E_INVALID_KEY_SIZE	The size of cb value of the key member of the DRT_REGISTRATION structure is not equal to 256 bits or the pb value of the key member of the DRT_REGISTRATION structure is NULL..
DRT_E_FAULTED	The DRT cloud is in the faulted state.
DRT_E_DUPLICATE_KEY	The key is already registered.
DRT_E_INVALID_CERT_CHAIN	The provided certification chain is invalid.
DRT_E_CAPABILITY_MISMATCH	Supplied certificate provider is not AES capable.
DRT_E_INVALID_KEY	Supplied key does not match generated key.
DRT_E_TRANSPORT_NO_DEST_ADDRESSES	Valid address not found.
DRT_E_TRANSPORT_SHUTTING_DOWN	Transport is shutting down.
DRT_E_INVALID_TRANSPORT_PROVIDER	Transport provider is NULL.
DRT_E_TRANSPORTPROVIDER_NOT_ATTACHED	Transport is not attached.
DRT_E_SECURITYPROVIDER_NOT_ATTACHED	Security provider is not attached.
DRT_E_TRANSPORT_NOT_BOUND	Transport is not currently bound.
E_OUTOFMEMORY	The system is out of memory.
E_UNEXPECTED	The GlobalControl.HandleTable is NULL. The cloud is shutting down. The DRT is shutting down.
E_FAIL	An unexpected fatal error has occurred.

Note DrtRegisterKey may also surface errors from underlying calls to CryptGetProvParam, CertGetCertificateChain, CertOpenStore, CertAddCertificateContextToStore, CryptContextAddRef, CryptAcquireCertificatePrivateKey, CertSaveStore, WSAIoctl, CryptImportPublicKeyInfoEx2, NCryptSignHash, CertEnumCertificatesInStore, BCryptGetProperty, BCryptGenRandom, BCryptGenerateSymmetricKey and BCryptEncrypt.

Remarks

A node can register keys while in the DRT_ACTIVE, DRT_ALONE, or DRT_NO_NETWORK state. However, keys registered in DRT_ALONE and DRT_NO_NETWORK states can only be recognized by other DRTs after the local node has transitioned to DRT_ACTIVE.

To update an existing key, an application must first deregister the key with DrtUnregisterKey before calling DrtRegisterKey to register the updated key.

Requirements

Requirement	Value
Minimum supported client	Windows 7 Professional [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	drt.h
Library	Drt.lib
DLL	Drt.dll