CertAddSerializedElementToStore

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

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 operating system.

Syntax

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 to 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. The following table shows disposition values that are currently defined.

  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 set to zero.

• dwContextTypeFlags
  [in] Specifies the contexts that can be added.

  The following table shows context type flags that are currently defined.

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

• pdwContextType
  [out] Optional. Pointer to the context type of the added serialized element. If the value of this parameter is NULL, the calling application does not require the context type.

  The CERT_STORE_CERTIFICATE_CONTEXT context type indicates a certificate.

• ppvContext
  [out] Optional. Pointer to a pointer to the decoded certificate context. If the value of this parameter is NULL, 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 Value

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 shows some possible error codes.

Remarks

The Windows Embedded CE version of this function does not support CRL and CTL flags. The desktop operating system supports the following flags that Windows Embedded CE does not support:

CERT_STORE_CRL_CONTEXT

CERT_STORE_CRL_CONTEXT_FLAG

Requirements

See Also

Reference

CertFreeCertificateContext
CertGetSubjectCertificateFromStore
CERT_CONTEXT