Funzione CertAddSerializedElementToStore (wincrypt.h)

  • Articolo

La funzione CertAddSerializedElementToStore aggiunge un certificato serializzato, un elenco di revoche di certificati (CRL) o un elemento CTL ( Certificate Trust List ) all'archivio. L'elemento serializzato contiene il certificato codificato, CRL o CTL e le relative proprietà estese. Le proprietà estese sono associate a un certificato e non fanno parte di un certificato rilasciato da un'autorità di certificazione. Le proprietà estese non sono disponibili in un certificato quando viene usato in una piattaforma non Microsoft.

Sintassi

BOOL CertAddSerializedElementToStore(
  [in]  HCERTSTORE hCertStore,
  [in]  const BYTE *pbElement,
  [in]  DWORD      cbElement,
  [in]  DWORD      dwAddDisposition,
  [in]  DWORD      dwFlags,
  [in]  DWORD      dwContextTypeFlags,
  [out] DWORD      *pdwContextType,
  [out] const void **ppvContext
);

Parametri

[in] hCertStore

Handle di un archivio certificati in cui verrà archiviato il certificato creato. Se hCertStore è NULL, la funzione crea una copia di un contesto certificato, CRL o CTL con le relative proprietà estese, ma il certificato, CRL o CTL non viene salvato in modo permanente in alcun archivio.

[in] pbElement

Puntatore a un buffer che contiene il certificato, il CRL o le informazioni sulla durata (CTL) da serializzare e aggiungere all'archivio certificati.

[in] cbElement

Dimensione, in byte, del buffer pbElement .

[in] dwAddDisposition

Specifica l'azione da eseguire se il certificato, il CRL o CTL esiste già nell'archivio. I valori di eliminazione attualmente definiti sono illustrati nella tabella seguente.

Valore Significato
CERT_STORE_ADD_NEW
 Se il certificato, CRL o CTL è nuovo, viene creato e salvato in modo permanente nell'archivio. L'operazione ha esito negativo se nell'archivio esiste già un certificato identico, CRL o CTL. L'ultimo codice di errore è impostato su CRYPT_E_EXISTS.
CERT_STORE_ADD_USE_EXISTING
 Se il certificato, CRL o CTL è nuovo, viene aggiunto all'archivio. Se esiste già un certificato identico, CRL o CTL, viene usato l'elemento esistente. Se ppvContext non è NULL, il contesto esistente viene duplicato. La funzione aggiunge solo proprietà che non esistono già. Le proprietà hash SHA-1 e MD5 non vengono copiate.
CERT_STORE_ADD_REPLACE_EXISTING
 Se esiste già un certificato identico, CRL o CTL nell'archivio, il certificato esistente, il contesto CRL o CTL viene eliminato prima di creare e aggiungere il nuovo contesto.
CERT_STORE_ADD_ALWAYS
 Non viene eseguito alcun controllo per determinare se esiste già un certificato identico, CRL o CTL. Viene sempre creato un nuovo elemento. Ciò può causare duplicati nell'archivio. Per determinare se l'elemento esiste già nell'archivio, chiamare CertGetCRLFromStore o CertGetSubjectCertificateFromStore.
CERT_STORE_ADD_NEWER
 Se esiste un CRL o CTL corrispondente o un collegamento a un CRL o CTL corrispondente, la funzione confronta i tempi NotBefore in CRL o CTL. Se il CRL o il CTL esistente ha un tempo NotBefore inferiore al tempo NotBefore per il nuovo elemento, l'elemento o il collegamento precedente viene sostituito esattamente come con CERT_STORE_ADD_REPLACE_EXISTING. Se l'elemento esistente ha un tempo NotBefore maggiore o uguale all'ora NotBefore dell'elemento da aggiungere, la funzione ha esito negativo con GetLastError che restituisce il codice CRYPT_E_EXISTS.

Se un CRL o CTL corrispondente o un collegamento a un CRL o CTL corrispondente non viene trovato nell'archivio, viene aggiunto un nuovo elemento all'archivio.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES
 L'azione è la stessa di per CERT_STORE_ADD_NEWER. Tuttavia, se viene sostituito un CRL o CTL precedente, le proprietà dell'elemento precedente vengono incorporate nella sostituzione.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES
 Se esiste un certificato corrispondente nell'archivio, il contesto esistente viene eliminato prima di creare e aggiungere il nuovo contesto. Il nuovo contesto aggiunto eredita le proprietà dal certificato esistente.

[in] dwFlags

Riservato per uso futuro e deve essere zero.

[in] dwContextTypeFlags

Specifica i contesti che è possibile aggiungere. Ad esempio, per aggiungere un certificato, CRL o CTL, impostare dwContextTypeFlags su CERT_STORE_CERTIFICATE_CONTEXT_FLAG o CERT_STORE_CRL_CONTEXT_FLAG.

I flag di tipo di contesto attualmente definiti sono illustrati nella tabella seguente.

Valore Significato
CERT_STORE_ALL_CONTEXT_FLAG
 Aggiunge qualsiasi contesto.
CERT_STORE_CERTIFICATE_CONTEXT_FLAG
 Aggiunge solo un contesto di certificato.
CERT_STORE_CRL_CONTEXT_FLAG
 Aggiunge solo un contesto CRL.
CERT_STORE_CTL_CONTEXT_FLAG
 Aggiunge solo un contesto CTL.

[out] pdwContextType

Puntatore al tipo di contesto dell'elemento serializzato aggiunto. Si tratta di un parametro facoltativo e può essere NULL, che indica che l'applicazione chiamante non richiede il tipo di contesto .

I tipi di contesto attualmente definiti sono illustrati nella tabella seguente.

Valore Significato
CERT_STORE_CERTIFICATE_CONTEXT
 Certificati
CERT_STORE_CRL_CONTEXT
 CRL (Certificate Revocation List
CERT_STORE_CTL_CONTEXT
 CTL (Certificate Trust List

[out] ppvContext

Puntatore a un puntatore al contesto di certificato decodificato, CRL o CTL. Si tratta di un parametro facoltativo e può essere NULL, che indica che l'applicazione chiamante non richiede il contesto del certificato, CRL o CTL aggiunto o esistente.

Se ppvContext non è NULL, deve essere l'indirizzo di un puntatore a un CERT_CONTEXT, CRL_CONTEXT o CTL_CONTEXT. Al termine dell'applicazione con il contesto, il contesto deve essere liberato usando CertFreeCertificateContext per un certificato, CertFreeCRLContext per un CRL o CertFreeCTLContext per un CTL.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero.

Se la funzione ha esito negativo, restituisce zero. Per informazioni sugli errori estesi, chiamare GetLastError. Di seguito sono riportati alcuni possibili codici di errore.

Codice restituito Descrizione
CRYPT_E_EXISTS
 Se il parametro dwAddDisposition è impostato su CERT_STORE_ADD_NEW, il certificato, CRL o CTL esiste già nell'archivio.
E_INVALIDARG
 Un valore di eliminazione non valido è stato specificato nel parametro dwAddDisposition .
 

Se la funzione ha esito negativo, GetLastError può restituire un errore di codifica/decodifica ASN.1 ( Abstract Syntax Notation One ). Per informazioni su questi errori, vedere Codifica ASN.1/Decodifica dei valori restituiti.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione wincrypt.h
Libreria Crypt32.lib
DLL Crypt32.dll

Vedi anche

CertSerializeCRLStoreElement

CertSerializeCertificateStoreElement

Funzioni di manutenzione dell'archivio certificati e certificati