Método ICertAdmin::ImportCertificate (certadm.h)

Artigo
08/22/2023

O método ImportCertificate usa um certificado emitido anteriormente e o importa para o banco de dados da AC (autoridade de certificação ). Esse método foi definido pela primeira vez na interface ICertAdmin .

Para obter os requisitos que o certificado deve atender para ser importado com êxito, consulte Comentários.

Sintaxe

HRESULT ImportCertificate(
  [in]  const BSTR strConfig,
  [in]  const BSTR strCertificate,
  [in]  LONG       Flags,
  [out] LONG       *pRequestId
);

Parâmetros

[in] strConfig

Representa uma cadeia de caracteres de configuração válida para a autoridade de certificação no formato COMPUTERNAME\CANAME, em que COMPUTERNAME é o nome de rede do servidor dos Serviços de Certificados e CANAME é o nome comum da autoridade de certificação, conforme inserido durante a instalação dos Serviços de Certificados. Para obter informações sobre o nome da cadeia de caracteres de configuração, consulte ICertConfig.

ImportanteImportCertificate não limpa o cache interno quando a cadeia de caracteres de configuração é alterada. Ao alterar a cadeia de caracteres de configuração para a AC, você deve instanciar um novo objeto ICertAdmin e chamar esse método novamente com a nova cadeia de caracteres de configuração.

[in] strCertificate

A representação binária do certificado que está sendo importado.

[in] Flags

Especifica o formato do certificado. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
CR_IN_BASE64HEADER	Formato BASE64 com início/término.
CR_IN_BASE64	Formato BASE64 sem início/término.
CR_IN_BINARY	Formato binário.

[out] pRequestId

Um ponteiro para um valor LONG que recebe a ID de solicitação atribuída pelo banco de dados para o certificado importado.

Retornar valor

C++

Se o método for bem-sucedido e o parâmetro pRequestID for definido como o valor da ID de solicitação atribuída ao banco de dados para o certificado importado, o método retornará S_OK.

Se o método falhar, ele retornará um valor HRESULT que indica o erro. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.

VB

O valor retornado é a ID de solicitação atribuída pelo banco de dados para o certificado importado.

Comentários

O método ImportCertificate é útil no caso de uma autoridade de certificação que foi parcialmente restaurada do backup: se um certificado não estiver nas fitas de backup usadas para restaurar a autoridade de certificação, mas existir em um arquivo, o certificado poderá ser importado por meio desse método.

Para que esse método tenha êxito, o certificado que está sendo importado deve ter sido emitido anteriormente pela autoridade de certificação especificada em strConfig. A autoridade de certificação restaurada validará a assinatura do certificado e, se a assinatura não for válida, a chamada de método falhará.

Além disso, você não poderá importar um certificado se ele já existir no banco de dados. Cada certificado no banco de dados deve ser exclusivo. O banco de dados garante a exclusividade verificando o número de série do certificado.

Exemplos

// This code imports a binary certificate file.
BSTR   bstrCert = NULL;  // Variable for certificate.
HANDLE hFile;  
DWORD  cchFile, cbRead;
LONG   nID;  // Variable for request ID.

// Open the file that contains the certificate.
hFile = CreateFile((LPCSTR) "d:\\cert1.cer",
                  GENERIC_READ,
                  FILE_SHARE_READ,
                  NULL,
                  OPEN_EXISTING,
                  0,
                  NULL);
if (INVALID_HANDLE_VALUE == hFile)
{
    printf("Unable to open file\n");
    // Take error action as needed.
}
// Determine the file size.
cchFile = GetFileSize(hFile, NULL);
if ( (DWORD)-1 == cchFile )
{
    printf("Failed GetFileSize\n");
    CloseHandle(hFile);
    // Take error action as needed.
}
// Allocate the memory for the certificate.
bstrCert = SysAllocStringByteLen(NULL, cchFile);
if (NULL == bstrCert)
{
    printf("Failed SysAllocStringByteLen\n");
    CloseHandle(hFile);
    // Take error action as needed.
}
// Read in the certificate.
if (!ReadFile(hFile,
             (char *)bstrCert,
             cchFile,
             &cbRead,
             NULL) || (cbRead != cchFile))
{
    printf("Failed to successfully read file\n");
    CloseHandle(hFile);
    SysFreeString(bstrCert);
    // Take error action as needed.
}
// Close the file.
CloseHandle(hFile);

// Import the certificate.
bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
if (FAILED(hr))
{
    printf("Failed to allocate memory for bstrCA\n");
    SysFreeString(bstrCert);
    // Take error action as needed.
}

hr = pCertAdmin->ImportCertificate(bstrCA,
                                   bstrCert,
                                   CR_IN_BINARY,
                                   &nID);
if (FAILED(hr))
    printf("Failed ImportCertificate [%x]\n", hr);
else
    printf("Imported certificated has Request ID: %d\n", nID);

SysFreeString(bstrCert);
SysFreeString(bstrCA);

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Nenhum compatível
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	certadm.h (inclua Certsrv.h)
Biblioteca	Certidl.lib
DLL	Certadm.dll