Export (0) Print
Expand All
Expand Minimize
0 out of 1 rated this helpful - Rate this topic

CertAddSerializedElementToStore function

The CertAddSerializedElementToStore function adds a serialized certificate, certificate revocation list (CRL), or certificate trust list (CTL) element to the store. The serialized element contains the encoded certificate, CRL, or CTL and its extended properties. Extended properties are associated with a certificate and are not part of a certificate as issued by a certification authority. Extended properties are not available on a certificate when it is used on a non-Microsoft platform.

Syntax


BOOL WINAPI 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
);

Parameters

hCertStore [in]

The handle of a certificate store where the created certificate will be stored. If hCertStore is NULL, the function creates a copy of a certificate, CRL, or CTL context with its extended properties, but the certificate, CRL, or CTL is not persisted in any store.

pbElement [in]

A pointer to a buffer that contains the certificate, CRL, or CTL information to be serialized and added to the certificate store.

cbElement [in]

The size, in bytes, of the pbElement buffer.

dwAddDisposition [in]

Specifies the action to take if the certificate, CRL, or CTL already exists in the store. Currently defined disposition values are shown in the following table.

ValueMeaning
CERT_STORE_ADD_NEW

If the certificate, CRL, or CTL is new, it is created and persisted to the store. The operation fails if an identical certificate, CRL, or CTL already exists in the store. The last error code is set to CRYPT_E_EXISTS.

CERT_STORE_ADD_USE_EXISTING

If the certificate, CRL, or CTL is new, it is added to the store. If an identical certificate, CRL, or CTL already exists, the existing element is used. If ppvContext is not NULL, the existing context is duplicated. The function only adds properties that do not already exist. The SHA-1 and MD5 hash properties are not copied.

CERT_STORE_ADD_REPLACE_EXISTING

If an identical certificate, CRL, or CTL already exists in the store, the existing certificate, CRL, or CTL context is deleted before creating and adding the new context.

CERT_STORE_ADD_ALWAYS

No check is made to determine whether an identical certificate, CRL, or CTL already exists. A new element is always created. This can lead to duplicates in the store. To determine whether the element already exists in the store, call CertGetCRLFromStore or CertGetSubjectCertificateFromStore.

CERT_STORE_ADD_NEWER

If a matching CRL or CTL or a link to a matching CRL or CTL exists, the function compares the NotBefore times on the CRL or CTL. If the existing CRL or CTL has a NotBefore time less than the NotBefore time on the new element, the old element or link is replaced just as with CERT_STORE_ADD_REPLACE_EXISTING. If the existing element has a NotBefore time greater than or equal to the NotBefore time on the element to be added, the function fails with GetLastError returning the CRYPT_E_EXISTS code.

If a matching CRL or CTL or a link to a matching CRL or CTL is not found in the store, a new element is added to the store.

CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES

The action is the same as for CERT_STORE_ADD_NEWER. However, if an older CRL or CTL is replaced, the properties of the older element are incorporated into the replacement.

CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES

If a matching certificate exists in the store, the existing context is deleted before creating and adding the new context. The new added context inherits properties from the existing certificate.

 

dwFlags [in]

Reserved for future use and must be zero.

dwContextTypeFlags [in]

Specifics the contexts that can be added. For example, to add either a certificate, CRL, or CTL, set dwContextTypeFlags to CERT_STORE_CERTIFICATE_CONTEXT_FLAG or CERT_STORE_CRL_CONTEXT_FLAG.

Currently defined context type flags are shown in the following table.

ValueMeaning
CERT_STORE_ALL_CONTEXT_FLAG

Adds any context.

CERT_STORE_CERTIFICATE_CONTEXT_FLAG

Adds only a certificate context.

CERT_STORE_CRL_CONTEXT_FLAG

Adds only a CRL context.

CERT_STORE_CTL_CONTEXT_FLAG

Adds only a CTL context.

 

pdwContextType [out]

A pointer to the context type of the added serialized element. This is an optional parameter and can be NULL, which indicates that the calling application does not require the context type.

Currently defined context types are shown in the following table.

ValueMeaning
CERT_STORE_CERTIFICATE_CONTEXT

Certificates

CERT_STORE_CRL_CONTEXT

CRLs

CERT_STORE_CTL_CONTEXT

CTLs

 

ppvContext [out]

A pointer to a pointer to the decoded certificate, CRL, or CTL context. This is an optional parameter and can be NULL, which indicates that the calling application does not require the context of the added or existing certificate, CRL, or CTL.

If ppvContext is not NULL, it must be the address of a pointer to a CERT_CONTEXT, CRL_CONTEXT, or CTL_CONTEXT. When the application is finished with the context, the context must be freed by using CertFreeCertificateContext for a certificate, CertFreeCRLContext for a CRL, or CertFreeCTLContext for a CTL.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. For extended error information, call GetLastError. Some possible error codes follow.

Return codeDescription
CRYPT_E_EXISTS

If the dwAddDisposition parameter is set to CERT_STORE_ADD_NEW, the certificate, CRL, or CTL already exists in the store.

E_INVALIDARG

A disposition value that is not valid was specified in the dwAddDisposition parameter.

 

If the function fails, GetLastError may return an Abstract Syntax Notation One (ASN.1) encoding/decoding error. For information about these errors, see ASN.1 Encoding/Decoding Return Values.

Examples

The following example shows adding a serialized certificate to a certificate store. This example uses the serialized form of a certificate from one store. That serialized form of the certificate is converted into a full certificate and added to a different store. In this example, pbElement is the serialized element of a certificate, and cbElement is the length of pbElement. For information about retrieval of a certificate and of serializing that certificate, see Example C Program: Serializing Certificates. For the full example including the complete context for this example, see Example C Program: Serializing Certificates and Adding Serialized Elements to Stores.


#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")

//--------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE         hSystemStore;
BYTE*              pbElement;
DWORD              cbElement;
PCCERT_CONTEXT     pCertContext = NULL;

// Open the store where the new certificate will be added.

if(hSystemStore = CertOpenSystemStore(
    0,
    "CA"))
{
  printf("The CA system store is open. Continue.\n");
}
else
{
  printf("The first system store did not open.\n");
  exit(1);
}

//--------------------------------------------------------------------
// Retrieve the first certificate from the Root store.
// CertFindCertificateInStore could be used here to find
// a certificate with a specific property.

if(pCertContext=CertEnumCertificatesInStore(
    hSystemStore,
    pCertContext))
{
printf("A certificate is available. Continue.\n");
}
else
{
     printf("No certificate available. The store may be empty.");
     exit(1);
}

//--------------------------------------------------------------------
// Find out how much memory to allocate for the serialized element.

if(CertSerializeCertificateStoreElement(
    pCertContext,      // The existing certificate.
    0,                 // Accept default for dwFlags, 
    NULL,              // NULL for the first function call.
    &cbElement))       // Address where the length of the 
                       // serialized element will be placed.
{
     printf("The length of the serialized string is %d.\n",cbElement);
}
else
{
     printf("Finding the length of the serialized element failed.");
     exit(1);
}
//--------------------------------------------------------------------
// Allocate memory for the serialized element.

if(pbElement = (BYTE*)malloc(cbElement))
{
     printf("Memory has been allocated. Continue.\n");
}
else
{
     printf("The allocation of memory failed.");
     exit(1);
}
//--------------------------------------------------------------------
// Create the serialized element from a certificate context.

if(CertSerializeCertificateStoreElement(
    pCertContext,        // The certificate context source for the 
                         // serialized element.
    0,                   // dwFlags. Accept the default.
    pbElement,           // A pointer to where the new element will
                         // be stored.
    &cbElement))         // The length of the serialized element,
{
     printf("The encoded element has been serialized. \n");
}
else
{
     printf("The element could not be serialized.");
     exit(1);
}

//  The following process uses the serialized 
//  pbElement and its length, cbElement, to 
//  create a new certificate and add it to a store.

if(CertAddSerializedElementToStore(
    hSystemStore,        // Store where certificate is to be added.
    pbElement,           // The serialized element for another
                         // certificate. 
    cbElement,           // The length of pbElement.  
    CERT_STORE_ADD_REPLACE_EXISTING,
                         // Flag to indicate what to do if a matching
                         // certificate is already in the store.
    0,                   // dwFlags. Accept the default.
    CERT_STORE_CERTIFICATE_CONTEXT_FLAG, 
    NULL,
    NULL
    ))
{
     printf("The new certificate is added to the open store.\n");
}
else
{
     printf("The new element was not added to a store.\n");
}

// Clean up.

if(pCertContext)
    CertFreeCertificateContext(pCertContext);
if(hSystemStore)
{
    if(!(CertCloseStore(hSystemStore, 0)))
    {
        printf("Could not close system store.");
        exit(1);
    }
}
if(pbElement)
    free(pbElement);


Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

Certificate and Certificate Store Maintenance Functions
CertSerializeCertificateStoreElement
CertSerializeCRLStoreElement

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.