IX509CertificateRequestPkcs10::get_CspStatuses method (certenroll.h)

Article
04/02/2021

The CspStatuses property retrieves a collection of ICspStatus objects that matches the intended use of the private key associated with the certificate request.

This property is read-only.

Syntax

HRESULT get_CspStatuses(
  ICspStatuses **ppValue
);

Parameters

ppValue

Return value

None

Remarks

This property retrieves a collection of ICspStatus objects. Each object represents a single provider/algorithm pair. The CspStatuses property differs from the GetCspStatuses method. The method enables you to set a KeySpec parameter, but CspStatuses uses the KeySpec property set on the private key associated with the IX509CertificateRequestPkcs10 object. This can be one of the following values.

Value	Description
XCN_AT_NONE	Only Cryptography API: Next Generation (CNG) providers are selected.
XCN_AT_KEYEXCHANGE	Only CryptoAPI cryptographic service providers (CSPs) with encryption algorithms (including key exchange) are selected.
XCN_AT_SIGNATURE	Only CryptoAPI cryptographic service providers (CSPs) with signature algorithms are selected.

If you specify a template when initializing the request object, template attributes such as the pKIDefaultCSPs and pKIDefaultKeySpec affect which provider/algorithm pairs are initially enabled in the collection. You can call the following properties on each ICspStatus object to retrieve information about a pair:

The CspInformation property retrieves provider information.
The CspAlgorithm property retrieves algorithm information.
The EnrollmentStatus property retrieves an IX509EnrollmentStatus object. Call the Selected property on the status object to determine whether the provider/algorithm pair is enabled for this request.
The Ordinal property retrieves the position in the collection of the provider/algorithm pair.

The collection retrieved by this method is saved internally on the request object. The collection exists as long as the PKCS #10 object continues to exist.

Assume, for example, that the KeySpec property on the private key associated with the request object is set to XCN_AT_SIGNATURE and that a template is used to initialize the request. The following statements will be true:

A collection of ICspStatus objects is created and saved on the IX509CertificateRequestPkcs10 object. The collection contains all valid provider/algorithm pairs installed on the computer.
Because the KeySpec property is not set to XCN_AT_NONE, the Selected property is set to SelectedNo for each Cryptography API: Next Generation (CNG) provider/algorithm pair in the collection.
Because the KeySpec property is not set to XCN_AT_KEYEXCHANGE, the Selected property is set to SelectedNo for each CryptoAPI CSP/algorithm pair in the collection where the algorithm can be used only to encrypt data or archive a key.
For each provider referenced by the template or private key but not supported on the computer, a placeholder ICspStatus object is created and added to the collection and the Selected property is set to SelectedNo.
The Selected property is set to SelectedYes for each CryptoAPI CSP/algorithm pair where the algorithm can be used only to sign data.
The Ordinal property is set to reflect the CSP order, if any, identified by the pKIDefaultCSPs template attribute. The CSPs listed first by the attribute are ordered first in the collection. This property is used during enrollment if a private key must be created. The first selected CSP/algorithm pair is used to create the key, but if the operation fails, the next selected pair is tried.

You must initialize the IX509CertificateRequestPkcs10 object before calling this method. For more information, see any of the following methods:

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	certenroll.h
DLL	CertEnroll.dll