Método IX509CertificateRequestPkcs10::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] 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] 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 o usuário ou o computador armazena 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 Unicode aplicada 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 OR 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 a propriedade RenewalCertificate .
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)

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
HRESULT_FROM_WIN32(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 #10 executando as seguintes ações:

  • Copia o certificado de renovação, se houver um e você tiver especificado InheritRenewalCertificateFlag, do certificado de entrada para a nova solicitação.
  • Copia o modelo se um for especificado no certificado existente e você definir o valor InheritTemplateFlag .
  • Copia o nome diferenciado da entidade para a nova solicitação se você especificar InheritSubjectFlag.
  • Copia o nome alternativo da entidade para a nova solicitação se você especificar InheritSubjectAltNameFlag.
  • Copia as extensões para a nova solicitação se você especificar InheritExtensionsFlag.

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

IX509CertificateRequestPkcs10