CertSerializeCertificateStoreElement

The CertSerializeCertificateStoreElement function serializes a certificate context's encoded certificate and an encoded representation of its properties. The result may be persisted to storage so that the certificate and properties may be retrieved at a later time.

#include <wincrypt.h>
BOOL WINAPI CertSerializeCertificateStoreElement(
  PCCERT_CONTEXT pCertContext,    // in
  DWORD dwFlags,                  // in
  BYTE *pbElement,                // out
  DWORD *pcbElement               // in, out
);
 

Parameters

pCertContext

Pointer to the certificate context being serialized.

dwFlags

This parameter is not currently used and should be set to zero.

pbElement

Pointer to a buffer that receives the serialized output, including the encoded certificate and possibly its properties.

This parameter can be NULL to set the size of this information for memory allocation purposes. For more information, see Common In/Out Parameter Conventions.

pcbElement

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the pbElement parameter. When the function returns, the variable pointed to by the pcbElement parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if pbElement is NULL.

Note  When processing the data returned in the buffer, applications need to use the actual size of the data returned. The actual size may be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data will fit in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

TRUE if the function succeeded. FALSE if the function failed

Call GetLastError to see the reason for any failures.

Example

//Serialize the data from a certificate, 
//and add that data as a new certificate to a store.
// handle_error() is a function defined in a separate file.
HCERTSTORE         hStoreHandle1;
HCERTSTORE         hStoreHandle2;
PCCERT_CONTEXT     pCertContext; 
BYTE*              pbElement;
DWORD              cbElement;

// Open a system certificate store. 
if(hStoreHandle1 = CertOpenSystemStore(0,"MY"))
printf("The MY system store is open. Continue.\n");
else
handle_error("The first system store did not open.");
//
if(hStoreHandle2 = CertOpenSystemStore(0,"CA"))
printf("The CA system store is open. Continue.");
else
handle_error("The second system store did not open.");
//
// Retrieve the first certificate from the MY store.
if(pCertContext=CertEnumCertificatesInStore(
hStoreHandle1,
NULL))
printf("A certificate is available. Continue.\n");
else
handle_error("No certificate is available. The store may be empty.");
//
// 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 first call to the function succeeded. Continue.\n");
else
handle_error("The first call to CertSerialize failed.");
//
// Allocate memory for the serialized element.
if(pbElement = (BYTE*)malloc(cbElement))
printf("Memory has been allocated. Continue.\n");
else
handle_error("The allocation of memory failed.");
//
// 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 seralized element,
    ))
printf("The encode element has been serialized. Continue. \n");
else
handle_error("The second call to the function failed.");
//
// Add the newly created element to the store.
if(CertAddSerializedElementToStore(
    hStoreHandle2,       // Store where cert is to be added.
    pbElement ,          // The serialized element for another
                         // cert. 
    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 second store.\n");
    else
    handle_error("The new element was not added to a store.");
//
// Free memory.
free(pbElement);
CertCloseStore(hStoreHandle1,0);
CertCloseStore(hStoreHandle2,0); 
printf("The program ran without error to the end.\n");
 

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.

See Also

CertAddSerializedElementToStore