IX509CertificateRequestPkcs10 ::GetCspStatuses, méthode (certenroll.h)

Article
02/23/2024

La méthode GetCspStatuses récupère une collection ICspStatuses qui contient toutes les paires fournisseur/algorithme cohérentes avec l’utilisation prévue de la clé privée, comme spécifié par l’appelant.

Syntaxe

HRESULT GetCspStatuses(
  [in]  X509KeySpec  KeySpec,
  [out] ICspStatuses **ppCspStatuses
);

Paramètres

[in] KeySpec

Valeur d’énumération X509KeySpec qui spécifie l’utilisation prévue de la clé. Il peut s’agir de l’une des valeurs suivantes.

Valeur	Signification
XCN_AT_NONE	Api de chiffrement uniquement : les fournisseurs CNG (Next Generation) sont sélectionnés.
XCN_AT_KEYEXCHANGE	Seuls les fournisseurs de services de chiffrement CryptoAPI avec des algorithmes de chiffrement (y compris l’échange de clés) sont sélectionnés.
XCN_AT_SIGNATURE	Seuls les fournisseurs de solutions cloud CryptoAPI avec des algorithmes de signature sont sélectionnés.

[out] ppCspStatuses

Adresse d’une variable qui reçoit un pointeur vers une interface ICspStatuses qui représente la collection.

Valeur retournée

Si la fonction réussit, la fonction retourne S_OK.

Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles sont notamment celles figurant dans le tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Code de retour	Description
CERTSRV_E_PROPERTY_EMPTY	La clé privée est introuvable.
OLE_E_BLANK	L’objet n’est pas initialisé.

Remarques

Cette méthode récupère une collection d’objets ICspStatus . Chaque objet représente une seule paire fournisseur/algorithme. Si vous spécifiez un modèle lors de l’initialisation de l’objet de requête IX509CertificateRequestPkcs10 , les attributs de modèle tels que pKIDefaultCSPs et pKIDefaultKeySpec affectent les paires initialement activées. Vous pouvez appeler les propriétés suivantes sur chaque objet ICspStatus pour récupérer des informations sur une paire :

La propriété CspInformation récupère les informations du fournisseur.
La propriété CspAlgorithm récupère les informations de l’algorithme.
La propriété EnrollmentStatus récupère un objet IX509EnrollmentStatus . Appelez la propriété Selected sur l’objet status pour déterminer si la paire fournisseur/algorithme est activée pour cette requête.
La propriété Ordinal récupère la position dans la collection de paires fournisseur/algorithme.

La collection récupérée par cette méthode est enregistrée en interne sur l’objet de demande. Jusqu’à trois collections, une pour chaque valeur KeySpec , peuvent être créées et enregistrées. Cela permet de conserver l’état de sélection des paires fournisseur/algorithme afin que les pages de propriétés pertinentes puissent être affichées avec précision et rapidement plusieurs fois et que la méthode Encode puisse identifier quels fournisseurs et algorithmes sont sélectionnés si une clé privée doit être créée. Si l’état de sélection d’une paire fournisseur/algorithme est modifié, les modifications sont enregistrées dans la collection appropriée. Les modifications apportées aux membres d’une collection n’affectent pas les membres d’une autre collection. Les collections existent tant que l’objet PKCS #10 continue d’exister.

Supposons, par exemple, que cette méthode soit appelée avec le paramètre KeySpec défini sur XCN_AT_SIGNATURE et qu’un modèle soit utilisé pour initialiser la demande. Les instructions suivantes ont la valeur true :

Une collection d’objets ICspStatus est créée et enregistrée sur l’objet IX509CertificateRequestPkcs10 . La collection contient toutes les paires fournisseur/algorithme valides installées sur l’ordinateur.
Étant donné que le paramètre KeySpec n’est pas défini sur XCN_AT_NONE, la propriété Selected est définie sur SelectedNo pour chaque paire fournisseur/algorithme CNG (CNG) dans la collection.
Étant donné que le paramètre KeySpec n’est pas défini sur XCN_AT_KEYEXCHANGE, la propriété Selected est définie sur SelectedNo pour chaque paire CSP/algorithme CryptoAPI dans la collection où l’algorithme peut être utilisé pour chiffrer des données ou archiver une clé.
Pour chaque fournisseur référencé par le modèle ou la clé privée mais non pris en charge sur l’ordinateur, un objet ICspStatus d’espace réservé est créé et ajouté à la collection et la propriété Selected est définie sur SelectedNo.
La propriété Selected est définie sur SelectedYes pour chaque paire CSP/algorithme CryptoAPI où l’algorithme ne peut être utilisé que pour signer des données.
La propriété Ordinal est définie pour refléter l’ordre CSP, le cas échéant, identifié par l’attribut de modèle pKIDefaultCSPs . Les fournisseurs de services partagés répertoriés en premier par l’attribut sont classés en premier dans la collection. Cette propriété est utilisée lors de l’inscription si une clé privée doit être créée. La première paire CSP/algorithme sélectionnée est utilisée pour créer la clé, mais si l’opération échoue, la paire sélectionnée suivante est essayée.
L’appel de cette méthode avec le même paramètre KeySpec récupère un pointeur vers la collection existante créée précédemment pour cette valeur de paramètre.
L’appel de cette méthode à nouveau avec un paramètre KeySpec différent n’affecte pas la collection créée pour la valeur KeySpec XCN_AT_SIGNATURE. En outre, la modification de la propriété Selected sur un membre de la nouvelle collection n’affecte aucun membre de la collection précédente.

La méthode GetCspStatuses diffère de la propriété CspStatuses en utilisant le paramètre KeySpec . La méthode permet aux utilisateurs de spécifier cette valeur, mais la propriété utilise la valeur définie sur la clé privée associée à l’objet de requête.

Vous devez initialiser l’objet IX509CertificateRequestPkcs10 avant d’appeler cette méthode. Pour plus d’informations, consultez l’une des méthodes suivantes :

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	certenroll.h
DLL	CertEnroll.dll

Voir aussi

IX509CertificateRequestPkcs10

Partager via