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

Artículo
03/14/2023

El método ImportCertificate toma un certificado emitido previamente y lo importa a la base de datos de la entidad de certificación (CA). Este método se definió por primera vez en la interfaz ICertAdmin .

Para conocer los requisitos que el certificado debe cumplir para importarse correctamente, vea Comentarios.

Sintaxis

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

Parámetros

[in] strConfig

Representa una cadena de configuración válida para la entidad de certificación con el formato COMPUTERNAME\CANAME, donde COMPUTERNAME es el nombre de red del servidor de Servicios de certificados y CANAME es el nombre común de la entidad de certificación, tal como se especifica durante la configuración de Servicios de certificados. Para obtener información sobre el nombre de la cadena de configuración, vea ICertConfig.

ImportanteImportCertificate no borra la caché interna cuando se cambia la cadena de configuración. Al cambiar la cadena de configuración de la ENTIDAD de certificación, debe crear una instancia de un nuevo objeto ICertAdmin y llamar a este método de nuevo con la nueva cadena de configuración.

[in] strCertificate

Representación binaria del certificado que se va a importar.

[in] Flags

Especifica el formato del certificado. Este parámetro puede ser uno de los valores siguientes.

Valor	Significado
CR_IN_BASE64HEADER	Formato BASE64 con begin/end.
CR_IN_BASE64	Formato BASE64 sin begin/end.
CR_IN_BINARY	Formato binario.

[out] pRequestId

Puntero a un valor LONG que recibe el identificador de solicitud asignado a la base de datos para el certificado importado.

Valor devuelto

C++

Si el método se ejecuta correctamente y el parámetro pRequestID se establece en el valor del identificador de solicitud asignado a la base de datos para el certificado importado, el método devuelve S_OK.

Si se produce un error en el método, devuelve un valor HRESULT que indica el error. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

VB

El valor devuelto es el identificador de solicitud asignado a la base de datos para el certificado importado.

Comentarios

El método ImportCertificate es útil en el caso de una entidad de certificación que se ha restaurado parcialmente a partir de la copia de seguridad: si un certificado no está en las cintas de copia de seguridad usadas para restaurar la entidad de certificación, pero existe en un archivo, el certificado se puede importar mediante este método.

Para que este método se realice correctamente, el certificado que se está importando debe haber sido emitido previamente por la entidad de certificación especificada en strConfig. La entidad de certificación restaurada validará la firma del certificado y, si la firma no es válida, se producirá un error en la llamada al método.

Además, no puede importar un certificado si ya existe en la base de datos. Cada certificado de la base de datos debe ser único. La base de datos garantiza la unicidad comprobando el número de serie del certificado.

Ejemplos

// 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	Value
Cliente mínimo compatible	No se admite ninguno
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	certadm.h (incluya Certsrv.h)
Library	Certidl.lib
Archivo DLL	Certadm.dll