Fonction CertAddCertificateContextToStore (wincrypt.h)

Article
03/03/2024

La fonction CertAddCertificateContextToStore ajoute un contexte de certificat au magasin de certificats.

Syntaxe

BOOL CertAddCertificateContextToStore(
  [in]            HCERTSTORE     hCertStore,
  [in]            PCCERT_CONTEXT pCertContext,
  [in]            DWORD          dwAddDisposition,
  [out, optional] PCCERT_CONTEXT *ppStoreContext
);

Paramètres

[in] hCertStore

Handle d’un magasin de certificats.

[in] pCertContext

Pointeur vers la structure CERT_CONTEXT à ajouter au magasin.

[in] dwAddDisposition

Spécifie l’action à entreprendre si un certificat correspondant ou un lien vers un certificat correspondant existe déjà dans le magasin. Les valeurs de disposition actuellement définies et leurs utilisations sont les suivantes.

Valeur	Signification
CERT_STORE_ADD_ALWAYS	La fonction n’effectue aucune case activée pour un certificat de correspondance existant ou un lien vers un certificat correspondant. Un nouveau certificat est toujours ajouté au magasin. Cela peut entraîner des doublons dans un magasin.
CERT_STORE_ADD_NEW	S’il existe un certificat correspondant ou un lien vers un certificat correspondant, l’opération échoue. GetLastError retourne le code CRYPT_E_EXISTS.
CERT_STORE_ADD_NEWER	Si un certificat correspondant ou un lien vers un certificat correspondant existe et que l’heure NotBefore du contexte existant est égale ou supérieure à l’heure NotBefore du nouveau contexte ajouté, l’opération échoue et GetLastError retourne le code CRYPT_E_EXISTS. Si l’heure NotBefore du contexte existant est inférieure à l’heure NotBefore du nouveau contexte ajouté, le certificat ou le lien existant est supprimé et un nouveau certificat est créé et ajouté au magasin. Si un certificat correspondant ou un lien vers un certificat correspondant n’existe pas, un nouveau lien est ajouté. Si des listes de révocation de certificats (CRL) ou des listes d’approbation de certificats (CTL) sont comparées, l’heure ThisUpdate est utilisée.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES	Si un certificat correspondant ou un lien vers un certificat correspondant existe et que l’heure NotBefore du contexte existant est égale ou supérieure à l’heure NotBefore du nouveau contexte ajouté, l’opération échoue et GetLastError retourne le code CRYPT_E_EXISTS. Si l’heure NotBefore du contexte existant est inférieure à l’heure NotBefore du nouveau contexte ajouté, le contexte existant est supprimé avant de créer et d’ajouter le nouveau contexte. Le nouveau contexte ajouté hérite des propriétés du certificat existant. Si des listes de contrôle d’accès (CRL) ou des CTL sont comparées, l’heure ThisUpdate est utilisée.
CERT_STORE_ADD_REPLACE_EXISTING	S’il existe un lien vers un certificat correspondant, ce certificat ou lien existant est supprimé et un nouveau certificat est créé et ajouté au magasin. Si un certificat correspondant ou un lien vers un certificat correspondant n’existe pas, un nouveau lien est ajouté.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES	Si un certificat correspondant existe dans le magasin, le contexte existant n’est pas remplacé. Le contexte existant hérite des propriétés du nouveau certificat.
CERT_STORE_ADD_USE_EXISTING	S’il existe un certificat correspondant ou un lien vers un certificat correspondant, ce certificat ou lien existant est utilisé et les propriétés du nouveau certificat sont ajoutées. La fonction n’échoue pas, mais elle n’ajoute pas de nouveau contexte. Si pCertContext n’a pas la valeur NULL, le contexte existant est dupliqué. Si un certificat correspondant ou un lien vers un certificat correspondant n’existe pas, un nouveau certificat est ajouté.

[out, optional] ppStoreContext

Pointeur vers un pointeur vers la copie à effectuer du certificat ajouté au magasin.

Le paramètre ppStoreContext peut être NULL, ce qui indique que l’application appelante ne nécessite pas de copie du certificat ajouté. Si une copie est effectuée, elle doit être libérée à l’aide de CertFreeCertificateContext.

Valeur retournée

Si la fonction réussit, la valeur de retour est TRUE.

Si la fonction échoue, la valeur de retour est FALSE. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Certains codes d’erreur possibles suivent.

Code de retour	Description
CRYPT_E_EXISTS	Cette valeur est retournée si CERT_STORE_ADD_NEW est défini et que le certificat existe déjà dans le magasin, ou si CERT_STORE_ADD_NEWER est défini et qu’un certificat existe dans le magasin avec une date NotBefore supérieure ou égale à la date NotBefore sur le certificat à ajouter.
E_INVALIDARG	Une valeur de disposition non valide a été spécifiée dans le paramètre dwAddDisposition .

Les erreurs des fonctions appelées, CertAddEncodedCertificateToStore et CertSetCertificateContextProperty, peuvent être propagées à cette fonction.

Remarques

Le contexte de certificat n’est pas dupliqué à l’aide de CertDuplicateCertificateContext. Au lieu de cela, la fonction crée une nouvelle copie du contexte et l’ajoute au magasin.

En plus du certificat encodé, CertDuplicateCertificateContext copie également les propriétés du contexte, à l’exception des propriétés CERT_KEY_PROV_HANDLE_PROP_ID et CERT_KEY_CONTEXT_PROP_ID.

Pour supprimer le contexte de certificat du magasin de certificats, utilisez la fonction CertDeleteCertificateFromStore .

Note L’ordre du contexte de certificat peut ne pas être conservé dans le magasin. Pour accéder à un certificat spécifique, vous devez itérer entre les certificats du magasin.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Crypt32.lib
DLL	Crypt32.dll

Voir aussi

CertAddEncodedCertificateToStore

CertSetCertificateContextProperty

Fonctions de certificat

Partager via