CertAddSerializedElementToStore function (wincrypt.h)
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 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
[in] hCertStore
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.
[in] pbElement
A pointer to a buffer that contains the certificate, CRL, or CTL information to be serialized and added to the certificate store.
[in] cbElement
The size, in bytes, of the pbElement buffer.
[in] dwAddDisposition
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.
| Value | Meaning |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
[in] dwFlags
Reserved for future use and must be zero.
[in] dwContextTypeFlags
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.
[out] pdwContextType
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.
| Value | Meaning |
|---|---|
|
Certificates |
|
CRLs |
|
CTLs |
[out] ppvContext
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 code | Description |
|---|---|
|
If the dwAddDisposition parameter is set to CERT_STORE_ADD_NEW, the certificate, CRL, or CTL already exists in the store. |
|
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Crypt32.lib |
| DLL | Crypt32.dll |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for