CertAddSerializedElementToStore

This function adds a serialized certificate element to the store. The serialized element contains the encoded certificate and its extended properties. Extended properties are associated with a certificate and are not part of a certificate as issued by a certificate authority (CA). Extended properties are not available on a certificate when it is used on a non-Microsoft platform.

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

Parameters

• hCertStore
  [in] Handle of a certificate store where the created certificate will be stored. If hCertStore is NULL, the function creates a copy of a certificate context with its extended properties, but the certificate is not persisted in any store.

• pbElement
  [in] Pointer to a buffer containing the certificate information to be serialized and added to the certificate store.

• cbElement
  [in] Size, in bytes, of the pbElement buffer.

• dwAddDisposition
  [in] Specifies the action to take if the certificate already exists in the store. Currently defined disposition values are shown in the following table.

  Disposition value	Description
  CERT_STORE_ADD_NEW	If the certificate is new, it is created and persisted to the store. The operation fails if an identical certificate already exists in the store. The last error code is set to CRYPT_E_EXISTS.
  CERT_STORE_ADD_USE_EXISTING	If the certificate is new, it is added to the store. If an identical certificate 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 SHA1 and MD5 hash properties are not copied.
  CERT_STORE_ADD_REPLACE_EXISTING	If an identical certificate already exists in the store, the existing certificate context is deleted before creating and adding the new context.
  CERT_STORE_ADD_ALWAYS	No check is made to see if an identical certificate already exists. A new element is always created. This can lead to duplicates in the store. To determine if the element already exists in the store, call the CertGetSubjectCertificateFromStore function.
  CERT_STORE_ADD_NEWER	If a matching certificate or a link to a matching certificate exists, the function 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 the GetLastError function returning the CRYPT_E_EXISTS code. 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. However, if an older certificate is replaced, the properties of the older certificate are incorporated into the replacement certificate.
  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 a certificate, set dwContextTypeFlags to CERT_STORE_CERTIFICATE_CONTEXT_FLAG.

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

  Context type flag	Description
  CERT_STORE_ALL_CONTEXT_FLAG	Adds any context.
  CERT_STORE_CERTIFICATE_CONTEXT_FLAG	Adds only a certificate context.

• pdwContextType
  [out] Pointer to the context type of the added serialized element. This is an optional parameter and can be NULL, indicating that the calling application does not require the context type.

  The currently defined context type is shown in the following table.

  Context type	Description
  CERT_STORE_CERTIFICATE_CONTEXT	Certificates

• ppvContext
  [out] Pointer to a pointer to the decoded certificate context. This is an optional parameter and can be NULL, indicating that the calling application does not require the context of the added or existing certificate.

  If ppvContext is not NULL, it must be the address of a pointer to a CERT_CONTEXT structure. When the application is finished with the context, the context must be freed by using the CertFreeCertificateContext function for a certificate.

Return Values

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

For extended error information, call the GetLastError function. The following table lists some possible error codes.

Remarks

Note   The Windows CE version of this function does not support CRL and CTL flags.

The desktop platform supports the following flags, but Windows CE does not:

CERT_STORE_CRL_CONTEXT

CERT_STORE_CRL_CONTEXT_FLAG

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CertFreeCertificateContext, CertGetSubjectCertificateFromStore, CERT_CONTEXT

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.