Private and Public Key Functions

  • Article

CertEnroll.dll implements the IX509PrivateKey and IX509PublicKey interfaces. You can, for example, use the IX509PrivateKey interface to perform the following actions on a private key:

  • Create, open, close, import, export, and delete the key.
  • Specify or retrieve the public key algorithm.
  • Specify or retrieve information about the available cryptographic service provider (CSP) that support the public key algorithm.
  • Specify or retrieve the certificate associated with the private key.
  • Specify or retrieve the name of the key container.
  • Specify or retrieve a description of and a display name for the key.
  • Specify or retrieve the export constraints places on a private key.
  • Specify or retrieve a Boolean value that indicates whether the key exists.
  • Specify or retrieve a value that indicates how the key is protected before use.
  • Specify or retrieve a value that indicates whether the key can be used for signing, encryption, or both.
  • Specify or retrieve a value that identifies the specific purpose for which the key can be used.
  • Specify or retrieve the length of the key.
  • Specify or retrieve a value that indicates whether the key is used or saved in the context of a computer or user.
  • Retrieve a Boolean value that specifies whether the key has been opened.
  • Specify a personal identification number to access a private key on a smart card.
  • Specify or retrieve the name of the CSP associated with the key.
  • Specify or retrieve the security descriptor for the key.

Each of the following sections identifies a function exported by Xenroll.dll that can be used to manage a cryptographic key. Each topic also discusses how to use CertEnroll.dll to replace the function or indicates that no mapping between the two libraries exists:

ContainerNameWStr

The ContainerNameWStr function in Xenroll.dll specifies or retrieves the name of the key container.

When using CertEnroll.dll, you can perform the following actions to retrieve the name of a key container:

  1. Call the Request property on an existing IX509Enrollment object.
  2. Call the GetInnerRequest method on the request returned from step 1 to retrieve the innermost request.
  3. Call QueryInterface on the IX509CertificateRequest object returned from step 2 to cast to an IX509CertificateRequestPkcs10 object.
  4. Call the PrivateKey property on the PKCS #10 request.
  5. Call the ContainerName property on the IX509PrivateKey object retrieved from step 4.

GenKeyFlags

The GenKeyFlags function defined in Xenroll.dll specifies or retrieves flags used to generate a private key or public/private key pair.

When using CertEnroll.dll, you can specify a number of different properties that will determine how a private key is created. For more information, see Create.

GetKeyLen

The GetKeyLen function defined in Xenroll.dll retrieves the maximum or minimum key size of an encryption key.

When using CertEnroll.dll, you can call the Length property on an IX509PrivateKey or IX509PublicKey object to retrieve the key size, in bits.

GetKeyLenEx

The GetKeyLenEx function defined in Xenroll.dll retrieves the maximum or minimum key size or the increment length of an encryption key.

When using CertEnroll.dll, you can call the Length property on an IX509PrivateKey or IX509PublicKey object to retrieve the key size, in bits. If an algorithm supports incremental key lengths, you can call the IncrementLength property on the ICspAlgorithm object to retrieve the increment value. You can also call the MinLength and MaxLength properties to retrieve the minimum and maximum key sizes.

GetSupportedKeySpec

The GetSupportedKeySpec function defined in Xenroll.dll retrieves a value that indicates whether a CSP supports exchange keys, signing keys, or both.

When using CertEnroll.dll, you can call the KeySpec property on the IX509PrivateKey or ICspInformation objects to retrieve the operations supported by the key.

KeySpec

The KeySpec function defined in Xenroll.dll specifies or retrieves the key type.

When using CertEnroll.dll, you can call the KeySpec property on an IX509PrivateKey object to retrieve the operations supported by the key.

LimitExchangeKeyToEncipherment

The LimitExchangeKeyToEncipherment function defined in Xenroll.dll specifies or retrieves a Boolean value that indicates whether an encryption key can be used only for data or key encipherment.

CertEnroll.dll does not contain a direct equivalent for this function. You can, however, achieve a nearly equivalent result by specifying an IX509ExtensionKeyUsage object and adding it to the certificate request.

PVKFileNameWStr

The PVKFileNameWStr function defined in Xenroll.dll specifies or retrieves the name of a file that contains exported keys.

When using CertEnroll.dll, you can call the Export method on an IX509PrivateKey object to export a key to a BSTR. You can call the ExportPublicKey method to export the public key portion of an asymmetric key pair.

ReuseHardwareKeyIfUnableToGenNew

The ReuseHardwareKeyIfUnableToGenNew function defined in Xenroll.dll specifies or retrieves a Boolean value that indicates whether an existing key is reused when an error is encountered when generating a new key.

When using CertEnroll.dll, you can call the InitializeFromCertificate method on an IX509CertificateRequestPkcs10 object and specify a value of the X509RequestInheritOptions enumeration type to reuse an existing private key.

UseExistingKeySet

The UseExistingKeySet function defined in Xenroll.dll specifies or retrieves a Boolean value that indicates whether to use existing keys.

When using CertEnroll.dll, you can call the InitializeFromCertificate method on an IX509CertificateRequestPkcs10 object and specify a value of the X509RequestInheritOptions enumeration type to reuse existing private and public keys.

Mapping Xenroll.dll to CertEnroll.dll