IX509CertificateRequestPkcs10::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] 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] 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 el usuario o el equipo 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 Unicode 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 OR 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 la propiedad RenewalCertificate .
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)

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
HRESULT_FROM_WIN32(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 #10 realizando las siguientes acciones:

  • Copia el certificado de renovación, si hay uno y ha especificado InheritRenewalCertificateFlag, del certificado de entrada a la nueva solicitud.
  • Copia la plantilla si se especifica uno en el certificado existente y establece el valor InheritTemplateFlag .
  • Copia el nombre distintivo del firmante en la nueva solicitud si especifica InheritSubjectFlag.
  • Copia el nombre alternativo del firmante en la nueva solicitud si especifica InheritSubjectAltNameFlag.
  • Copia las extensiones en la nueva solicitud si especifica InheritExtensionsFlag.

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

IX509CertificateRequestPkcs10