IX509CertificateRequestPkcs7::InitializeFromCertificate (certenroll.h)

  • Artículo

El método InitializeFromCertificate inicializa la solicitud de certificado mediante un certificado existente. El certificado está incluido en una matriz de bytes codificada mediante reglas de codificación distinguida (DER) tal como se define en el estándar Notación de sintaxis abstracta Uno (ASN.1). La matriz de bytes con codificación DER se representa mediante una cadena que es una secuencia binaria pura o está codificada en Unicode.

Sintaxis

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

Parámetros

[in] Context

Valor de enumeración X509CertificateEnrollmentContext que especifica si el certificado solicitado está pensado para un usuario final, un equipo o un administrador que actúa en nombre del equipo.

[in] RenewalRequest

Un VARIANT_BOOL que indica si la entidad final solicita que se renueve el certificado identificado por el parámetro strCertificate .

[in] strCertificate

Variable BSTR que contiene el certificado codificado en DER.

A partir de Windows 7 y Windows Server 2008 R2, puede especificar una impresión digital de certificado o un número de serie en lugar de un certificado codificado. Al hacerlo, la función buscará en los almacenes locales adecuados el certificado coincidente. Tenga en cuenta los siguientes puntos:

  • El BSTR debe ser un número par de dígitos hexadecimales.
  • Se omite el espacio en blanco entre pares hexadecimales.
  • El parámetro Encoding debe establecerse en XCN_CRYPT_STRING_HEXRAW.
  • El parámetro Context determina si se buscan los almacenes locales o de equipos o ambos.
  • Si se necesita una clave privada, solo se buscan los almacenes personales y de solicitudes.
  • Si no se necesita una clave privada, también se buscan los almacenes de CA raíz e intermedio.

[in] Encoding

Valor de enumeración EncodingType que especifica el tipo de codificación aplicada al certificado codificado en DER. El valor predeterminado es XCN_CRYPT_STRING_BASE64.

[in] InheritOptions

Valor de enumeración X509RequestInheritOptions que especifica cómo crear el objeto de solicitud de certificado a partir del certificado existente. Para especificar cómo heredar una clave, elija uno de los valores siguientes. El valor predeterminado es InheritDefault.

Valor Significado
InheritDefault
 No se especifica la herencia de proveedor y clave.
InheritNewDefaultKey
 Crea una nueva clave, pero hereda el proveedor criptográfico predeterminado.
InheritNewSimilarKey
 Crea una nueva clave, pero hereda el proveedor criptográfico usado para crear el certificado existente.
InheritPrivateKey
 Hereda las claves privadas y públicas.
InheritPublicKey
 Hereda solo la clave pública.
 

También puede usar una operación AND bit a bit para combinar el valor de herencia de claves con cualquier combinación de los valores siguientes.

Valor Significado
InheritRenewalCertificateFlag
 Hereda el certificado de renovación. Al especificar esta marca, se establece un valor ICertPropertyRenewal .
InheritTemplateFlag
 Hereda la plantilla de certificado.
InheritSubjectFlag
 Hereda el nombre distintivo del sujeto.
InheritExtensionsFlag
 Hereda las extensiones pertinentes del certificado.
InheritSubjectAltNameFlag
 Hereda la extensión SubjectAlternativeName .
InheritValidityPeriodFlag
 Hereda el período de validez.
 

También puede especificar InheritNone para evitar que cualquiera de las marcas de la tabla anterior (marcas no relacionadas con la herencia de claves) se implemente de forma predeterminada. Si especifica InheritNone , pero también especifica una marca no relacionada con la herencia de claves, el método devuelve E_INVALIDARG.

Si establece el parámetro InheritOptions en cero (0) o especifica InheritDefault y no especifica un valor de herencia de clave, InheritNewSimilarKey se usa de forma predeterminada.

Si establece el parámetro InheritOptions en cero (0) o especifica InheritDefault y no especifica ninguno de los valores no relacionados con la herencia de claves, las marcas siguientes se establecen de forma predeterminada:

  • InheritSubjectFlag
  • InheritExtensionsFlag
  • InheritValidityPeriodFlag
  • InheritTemplateFlag (si el certificado contiene una extensión de plantilla)
  • InheritRenewalCertificateFlag (si el cliente renueva un certificado)

Valor devuelto

Si la función se realiza correctamente, la función devuelve S_OK.

Si se produce un error en la función, devuelve un valor HRESULT que indica el error. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

Código devuelto Descripción
ERROR_ALREADY_INITIALIZED
 El objeto de solicitud de certificado ya se ha inicializado.

Comentarios

El método InitializeFromCertificate valida las opciones especificadas en el parámetro InheritOptions e inicializa un nuevo objeto de solicitud PKCS #7 realizando las siguientes acciones:

  • Crea un objeto de solicitud PKCS #10 a partir del certificado, el contexto de inscripción y hereda las opciones especificadas en la entrada. El objeto PKCS #10 hereda:
    • La plantilla si existe en el certificado original y establece el valor InheritTemplateFlag .
    • Nombre distintivo del firmante si especifica InheritSubjectFlag.
    • Nombre alternativo del firmante si especifica InheritSubjectAltNameFlag.
    • Extensiones si especifica InheritExtensionsFlag.
  • Copia el certificado original, si se va a renovar, a la propiedad RenewalCertificate en la nueva solicitud PKCS #10.
  • Crea un ISignerCertificate a partir del certificado original, si se va a renovar y lo establece en la propiedad SignerCertificate .
  • Establece la solicitud PKCS #10 como objeto de solicitud interna.

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado certenroll.h
Archivo DLL CertEnroll.dll

Consulte también

IX509CertificateRequestPkcs7