IX509CertificateRequestPkcs7 ::InitializeFromCertificate, méthode (certenroll.h)

La méthode InitializeFromCertificate initialise la demande de certificat à l’aide d’un certificat existant. Le certificat est contenu dans un tableau d’octets encodé à l’aide de Distinguished Encoding Rules (DER) tel que défini par la norme ASN.1 (Abstract Syntax Notation One). Le tableau d’octets encodé en DER est représenté par une chaîne qui est une séquence binaire pure ou est encodée Unicode.

Syntaxe

HRESULT InitializeFromCertificate(
  [in] X509CertificateEnrollmentContext Context,
  [in] VARIANT_BOOL                     RenewalRequest,
  [in] BSTR                             strCertificate,
  [in] EncodingType                     Encoding,
  [in] X509RequestInheritOptions        InheritOptions
);

Paramètres

[in] Context

Valeur d’énumération X509CertificateEnrollmentContext qui spécifie si le certificat demandé est destiné à un utilisateur final, un ordinateur ou un administrateur agissant pour le compte de l’ordinateur.

[in] RenewalRequest

Une VARIANT_BOOL qui indique si l’entité finale demande le renouvellement du certificat identifié par le paramètre strCertificate .

[in] strCertificate

Variable BSTR qui contient le certificat encodé en DER.

À compter de Windows 7 et Windows Server 2008 R2, vous pouvez spécifier un numéro d’impression de certificat ou un numéro de série plutôt qu’un certificat encodé. Cela entraîne la recherche du certificat correspondant dans les magasins locaux appropriés. Gardez à l’esprit les points suivants :

  • Le BSTR doit être un nombre pair de chiffres hexadécimaux.
  • Les espaces blancs entre les paires hexadécimales sont ignorés.
  • Le paramètre Encodage doit être défini sur XCN_CRYPT_STRING_HEXRAW.
  • Le paramètre Context détermine si les magasins locaux ou les magasins d’ordinateurs ou les deux sont recherchés.
  • Si une clé privée est nécessaire, seuls les magasins personnels et les magasins de requêtes sont recherchés.
  • Si une clé privée n’est pas nécessaire, les magasins d’autorité de certification racine et intermédiaire sont également recherchés.

[in] Encoding

Valeur d’énumération EncodingType qui spécifie le type d’encodage appliqué au certificat encodé en DER. La valeur par défaut est XCN_CRYPT_STRING_BASE64.

[in] InheritOptions

Valeur d’énumération X509RequestInheritOptions qui spécifie comment créer l’objet de demande de certificat à partir du certificat existant. Vous pouvez spécifier comment hériter d’une clé en choisissant l’une des valeurs suivantes. La valeur par défaut est InheritDefault.

Valeur Signification
InheritDefault
L’héritage du fournisseur et de la clé n’est pas spécifié.
InheritNewDefaultKey
Crée une clé, mais hérite du fournisseur de chiffrement par défaut.
HériterNewSimilarKey
Crée une clé, mais hérite du fournisseur de chiffrement utilisé pour créer le certificat existant.
InheritPrivateKey
Hérite des clés privées et publiques.
InheritPublicKey
Hérite uniquement de la clé publique.
 

Vous pouvez également utiliser une opération AND au niveau du bit pour combiner la valeur d’héritage de clé avec n’importe quelle combinaison des valeurs suivantes.

Valeur Signification
InheritRenewalCertificateFlag
Hérite du certificat de renouvellement. La spécification de cet indicateur définit une valeur ICertPropertyRenewal .
InheritTemplateFlag
Hérite du modèle de certificat.
InheritSubjectFlag
Hérite du nom unique du sujet.
InheritExtensionsFlag
Hérite des extensions appropriées du certificat.
InheritSubjectAltNameFlag
Hérite de l’extension SubjectAlternativeName .
InheritValidityPeriodFlag
Hérite de la période de validité.
 

Vous pouvez également spécifier InheritNone pour empêcher l’implémentation par défaut de l’un des indicateurs du tableau précédent (indicateurs non liés à l’héritage de clé). Si vous spécifiez InheritNone , mais que vous spécifiez également un indicateur non lié à l’héritage de clé, la méthode retourne E_INVALIDARG.

Si vous définissez le paramètre InheritOptions sur zéro (0) ou si vous spécifiez InheritDefault et que vous ne spécifiez pas de valeur d’héritage de clé, InheritNewSimilarKey est utilisé par défaut.

Si vous définissez le paramètre InheritOptions sur zéro (0) ou si vous spécifiez InheritDefault et que vous ne spécifiez aucune des valeurs non liées à l’héritage de clé, les indicateurs suivants sont définis par défaut :

  • InheritSubjectFlag
  • InheritExtensionsFlag
  • InheritValidityPeriodFlag
  • InheritTemplateFlag (si le certificat contient une extension de modèle)
  • InheritRenewalCertificateFlag (si le client renouvelle un certificat)

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
ERROR_ALREADY_INITIALIZED
L’objet de demande de certificat a déjà été initialisé.

Remarques

La méthode InitializeFromCertificate valide les options spécifiées dans le paramètre InheritOptions et initialise un nouvel objet de requête PKCS #7 en effectuant les actions suivantes :

  • Crée un objet de requête PKCS #10 à partir du certificat, du contexte d’inscription et d’hériter des options spécifiées sur l’entrée. L’objet PKCS #10 hérite :
    • Modèle s’il existe dans le certificat d’origine et que vous définissez la valeur InheritTemplateFlag .
    • Nom unique de l’objet si vous spécifiez InheritSubjectFlag.
    • Autre nom d’objet si vous spécifiez InheritSubjectAltNameFlag.
    • Extensions si vous spécifiez InheritExtensionsFlag.
  • Copie le certificat d’origine, s’il doit être renouvelé, dans la propriété RenewalCertificate de la nouvelle demande PKCS #10.
  • Crée un ISignerCertificate à partir du certificat d’origine, s’il doit être renouvelé, et le définit sur la propriété SignerCertificate .
  • Définit la requête PKCS #10 comme objet de requête interne.

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

IX509CertificateRequestPkcs7