CertAddEncodedCertificateToStore

The CertAddEncodedCertificateToStore function creates a certificate context from an encoded certificate and adds it to the certificate store. CertAddEncodedCertificateToStore also makes a copy of the encoded certificate before adding it to the store

#include <wincrypt.h>
BOOL WINAPI CertAddEncodedCertificateToStore(
  HCERTSTORE hCertStore,                 // in
  DWORD dwCertEncodingType,              // in
  const BYTE *pbCertEncoded,             // in
  DWORD cbCertEncoded,                   // in
  DWORD dwAddDisposition,                // in
  PCCERT_CONTEXT *ppCertContext          // out, optional
);

Parameters

hCertStore

Handle to the certificate store.

dwCertEncodingType

Type of encoding used on the certificate. The currently defined certificate encoding type is X509_ASN_ENCODING.

pbCertEncoded

Pointer to the encoded certificate that is to be added to the certificate store.

cbCertEncoded

Size, in bytes, of the encoded certificate to be added to the certificate store.

dwAddDisposition

Value that specifies the action to take if a matching certificate or link to a matching certificate exists in the store. Currently defined disposition values are:

CERT_STORE_ADD_NEW: If a matching certificate or a link to a matching certificate exists in the store, the operation fails and GetLastError returns CRYPT_E_EXISTS.
CERT_STORE_ADD_USE_EXISTING: If a matching certificate or a link to a matching certificate exists, that existing certificate or link is used and properties from the new certificate are added. The function does not fail, but it does not add a new context. If ppCertContext is not NULL, the existing context is duplicated.
If a matching certificate or link to a matching certificate does not exist, a new certificate is added.
CERT_STORE_ADD_REPLACE_EXISTING: If a matching certificate or link to a matching certificate exists in the store, the existing certificate or link is deleted and a new certificate is created and added to the store. If a matching certificate or link to a matching certificate does not exist, a new certificate is created and added to the store.
CERT_STORE_ADD_ALWAYS: Does not check to see whether a matching certificate or a link to a matching certificate already exists. A new certificate is always added to the store. This may lead to duplicates in a store.
CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES.: If a matching certificate exists in the store, that existing context is deleted before creating and adding the new context. The added context inherits properties from the existing certificate
CERT_STORE_ADD_NEWER: If a matching certificate or a link to a matching certificate exists, compares the NotBefore times on the certificates. If the existing certificate has a NotBefore time less than the NotBefore time on the new certificate, the old certificate or link is replaced just as with CERT_STORE_ADD_REPLACE_EXISTING. If the existing certificate has a NotBefore time greater than or equal to the NotBefore time on the certificate to be added, the function fails with GetLastError returning CRYPT_E_EXISTS.
If a matching certificate or a link to a matching certificate is not found in the store, a new certificate is added to the store.
CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES: The action is the same as for CERT_STORE_ADD_NEWER except that if an older certificate is replaced, the properties of the older certificate are incorporated into the replacement certificate.

ppCertContext

Pointer to a pointer to the decoded certificate context. This is an optional parameter that can be NULL, indicating that the caller does not want a copy of the new or existing certificate. When a copy is made, its context must be freed by using CertFreeCertificateContext.

Return Values

TRUE if the function succeeded. FALSE if the function failed.

Call GetLastError to see the reason for any failures. This function has the following error codes:

GetLastError returns the reason for any failures using the following error codes:

CRYPT_E_EXISTS: This error is returned if CERT_STORE_ADD_NEW is set and the certificate already exists in the store or if CERT_STORE_ADD_NEWER is set and a there is a certificate in the store with a NotBefore date greater than or equal to the NotBefore date on the certificate to be added.
CRYPT_E_OSS_ERROR: ASN.1 decoding error occurred. To get the OSS error, subtract the value of CRYPT_E_OSS_ERROR from the returned error and see asn1code.h for details on the error.
E_INVALIDARG: An invalid add disposition was specified by the dwAddDisposition argument or an invalid certificate encoding type was specified. Currently only X509_ASN_ENCODING is supported.

Example

// The function handle_error() is defined in a separate file.
HCERTSTORE      hMemoryStoreHandle;    
HCERTSTORE      hStoreHandle;
PCCERT_CONTEXT  DesiredCert = NULL;
// Open a memory store where the certificate will be added.
// See CertOpenStore for details.
if(hMemoryStoreHandle = CertOpenStore(
CERT_STORE_PROV_MEMORY,0,NULL,0,NULL))
printf("Memory store open. \n");
else
handle_error("Store did not open.");
// Open a system store to get a certificate.
if(hStoreHandle = CertOpenSystemStore(0,"CA"))
// The system store opened. Continue.
printf("System store open.\n");
else
handle_error("The system store did not open.");
// Get the first certificate in the system store.
if(DesiredCert= CertEnumCertificatesInStore(
hStoreHandle,DesiredCert))
// A certificate was retrieved. Continue.
printf("A certificate has been retrieved.\n");              
else
handle_error("A certificate could not be retrieved. Perhaps the store is empty.");
// Add the encoded certificate to the store()  
if(CertAddEncodedCertificateToStore(
   hMemoryStoreHandle,         // Store where certificate
                               // is to be added. 
   X509_ASN_ENCODING,          // The encoding type used.
DesiredCert->pbCertEncoded, // The encoded certificate 
// from the system store certificate.
DesiredCert->cbCertEncoded, // The length of that encoded cert.
CERT_STORE_ADD_USE_EXISTING,// Flag to indicate that if a 
// matching cert already exists in 
// the store, it should be used.
   NULL                        // No duplicate cert is to be
                               // created.
   ))
// A certificate was added to the memory store. Continue.
printf("The certificate has been added.\n");
else   
handle_error("The certificate was not added.");

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Requires Windows 95 OSR2 or later.
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.

CertAddEncodedCertificateToStore

Parameters

Return Values

Example

QuickInfo

See Also