Método IX509CertificateRequestPkcs7::InitializeFromCertificate (certenroll.h)

  • Artigo

O método InitializeFromCertificate inicializa a solicitação de certificado usando um certificado existente. O certificado está contido em uma matriz de bytes codificada usando Distinguished Encoding Rules (DER), conforme definido pelo padrão ASN.1 (Abstract Syntax Notation One). A matriz de bytes codificada em DER é representada por uma cadeia de caracteres que é uma sequência binária pura ou codificada por Unicode.

Sintaxe

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

Parâmetros

[in] Context

Um valor de enumeração X509CertificateEnrollmentContext que especifica se o certificado solicitado destina-se a um usuário final, um computador ou um administrador agindo em nome do computador.

[in] RenewalRequest

Um VARIANT_BOOL que indica se a entidade final está solicitando que o certificado identificado pelo parâmetro strCertificate seja renovado.

[in] strCertificate

Uma variável BSTR que contém o certificado codificado em DER.

A partir do Windows 7 e do Windows Server 2008 R2, você pode especificar uma impressão digital do certificado ou um número de série em vez de um certificado codificado. Isso faz com que a função pesquise os repositórios locais apropriados para o certificado correspondente. Tenha em mente os seguintes pontos:

  • O BSTR deve ser um número par de dígitos hexadecimais.
  • O espaço em branco entre pares hexadecimais é ignorado.
  • O parâmetro Encoding deve ser definido como XCN_CRYPT_STRING_HEXRAW.
  • O parâmetro Context determina se os repositórios locais ou de computador ou ambos são pesquisados.
  • Se uma chave privada for necessária, somente os repositórios pessoais e de solicitação serão pesquisados.
  • Se uma chave privada não for necessária, os repositórios de AC raiz e intermediária também serão pesquisados.

[in] Encoding

Um valor de enumeração EncodingType que especifica o tipo de codificação aplicado ao certificado codificado em DER. O valor padrão é XCN_CRYPT_STRING_BASE64.

[in] InheritOptions

Um valor de enumeração X509RequestInheritOptions que especifica como criar o objeto de solicitação de certificado do certificado existente. Você pode especificar como herdar uma chave escolhendo um dos valores a seguir. O valor padrão é InheritDefault.

Valor Significado
InheritDefault
 A herança de provedor e chave não é especificada.
InheritNewDefaultKey
 Cria uma nova chave, mas herda o provedor criptográfico padrão.
InheritNewSimilarKey
 Cria uma nova chave, mas herda o provedor criptográfico usado para criar o certificado existente.
InheritPrivateKey
 Herda as chaves privadas e públicas.
InheritPublicKey
 Herda apenas a chave pública.
 

Você também pode usar uma operação AND bit a bit para combinar o valor de herança de chave com qualquer combinação dos valores a seguir.

Valor Significado
InheritRenewalCertificateFlag
 Herda o certificado de renovação. Especificar esse sinalizador define um valor ICertPropertyRenewal .
InheritTemplateFlag
 Herda o modelo de certificado.
InheritSubjectFlag
 Herda o nome diferenciado do assunto.
InheritExtensionsFlag
 Herda as extensões relevantes do certificado.
InheritSubjectAltNameFlag
 Herda a extensão SubjectAlternativeName .
InheritValidityPeriodFlag
 Herda o período de validade.
 

Você também pode especificar InheritNone para impedir que qualquer um dos sinalizadores na tabela anterior (sinalizadores não relacionados à herança de chave) seja implementado por padrão. Se você especificar InheritNone , mas também especificar um sinalizador não relacionado à herança de chave, o método retornará E_INVALIDARG.

Se você definir o parâmetro InheritOptions como zero (0) ou especificar InheritDefault e não especificar um valor de herança de chave, InheritNewSimilarKey será usado por padrão.

Se você definir o parâmetro InheritOptions como zero (0) ou especificar InheritDefault e não especificar nenhum dos valores não relacionados à herança de chave, os seguintes sinalizadores serão definidos por padrão:

  • InheritSubjectFlag
  • InheritExtensionsFlag
  • InheritValidityPeriodFlag
  • InheritTemplateFlag (se o certificado contiver uma extensão de modelo)
  • InheritRenewalCertificateFlag (se o cliente estiver renovando um certificado)

Retornar valor

Se a função for bem-sucedida, a função retornará S_OK.

Se a função falhar, ela retornará um valor HRESULT que indica o erro. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.

Código de retorno Descrição
ERROR_ALREADY_INITIALIZED
 O objeto de solicitação de certificado já foi inicializado.

Comentários

O método InitializeFromCertificate valida as opções especificadas no parâmetro InheritOptions e inicializa um novo objeto de solicitação PKCS nº 7 executando as seguintes ações:

  • Cria um objeto de solicitação PKCS nº 10 do certificado, do contexto de registro e das opções de herdamento especificadas na entrada. O objeto PKCS nº 10 herda:
    • O modelo se houver um no certificado original e você definir o valor InheritTemplateFlag .
    • O nome diferenciado da entidade se você especificar InheritSubjectFlag.
    • O nome alternativo da entidade se você especificar InheritSubjectAltNameFlag.
    • As extensões se você especificar InheritExtensionsFlag.
  • Copia o certificado original, se for para ser renovado, para a propriedade RenewalCertificate na nova solicitação PKCS nº 10.
  • Cria um ISignerCertificate com base no certificado original, se for para ser renovado, e o define na propriedade SignerCertificate .
  • Define a solicitação PKCS nº 10 como o objeto de solicitação interna.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho certenroll.h
DLL CertEnroll.dll

Confira também

IX509CertificateRequestPkcs7