Metodo ICertAdmin::ImportCertificate (certadm.h)

Articolo
02/26/2024

Il metodo ImportCertificate accetta un certificato rilasciato in precedenza e lo importa nel database dell'autorità di certificazione (CA). Questo metodo è stato definito per la prima volta nell'interfaccia ICertAdmin .

Per i requisiti che il certificato deve soddisfare per essere importato correttamente, vedere La sezione Note.

Sintassi

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

Parametri

[in] strConfig

Rappresenta una stringa di configurazione valida per l'autorità di certificazione nel formato COMPUTERNAME\CANAME, dove COMPUTERNAME è il nome di rete del server servizi certificati e CANAME è il nome comune dell'autorità di certificazione, come immesso durante l'installazione di Servizi certificati. Per informazioni sul nome della stringa di configurazione, vedere ICertConfig.

ImportanteImportCertificate non cancella la cache interna quando viene modificata la stringa di configurazione. Quando si modifica la stringa di configurazione per la CA, è necessario creare un'istanza di un nuovo oggetto ICertAdmin e chiamare di nuovo questo metodo con la nuova stringa di configurazione.

[in] strCertificate

Rappresentazione binaria del certificato importato.

[in] Flags

Specifica il formato del certificato. Questo parametro può avere uno dei valori seguenti.

Valore	Significato
CR_IN_BASE64HEADER	Formato BASE64 con inizio/fine.
CR_IN_BASE64	Formato BASE64 senza inizio/fine.
CR_IN_BINARY	Formato binario.

[out] pRequestId

Puntatore a un valore LONG che riceve l'ID richiesta assegnato dal database per il certificato importato.

Valore restituito

C++

Se il metodo ha esito positivo e il parametro pRequestID viene impostato sul valore dell'ID richiesta assegnato dal database per il certificato importato, il metodo restituisce S_OK.

Se il metodo ha esito negativo, restituisce un valore HRESULT che indica l'errore. Per un elenco dei codici di errore comuni, vedere Valori HRESULT comuni.

VB

Il valore restituito è l'ID richiesta assegnato dal database per il certificato importato.

Commenti

Il metodo ImportCertificate è utile nel caso di un'autorità di certificazione parzialmente ripristinata dal backup: se un certificato non è presente nei nastri di backup usati per ripristinare l'autorità di certificazione ma esiste in un file, il certificato può essere importato tramite questo metodo.

Affinché questo metodo abbia esito positivo, il certificato importato deve essere stato rilasciato in precedenza dall'autorità di certificazione specificata in strConfig. L'autorità di certificazione ripristinata convaliderà la firma del certificato e, se la firma non è valida, la chiamata al metodo avrà esito negativo.

Inoltre, non è possibile importare un certificato se esiste già nel database. Ogni certificato nel database deve essere univoco. Il database garantisce l'univocità controllando il numero di serie del certificato.

Esempio

// 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);

Requisiti

Requisito	Valore
Client minimo supportato	Nessuno supportato
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	certadm.h (include Certsrv.h)
Libreria	Certidl.lib
DLL	Certadm.dll