Share via

CertAddEncodedCertificateToStore

  • Article

This function creates a certificate context from an encoded certificate and adds it to the certificate store. The context created does not include any extended properties.

The CertAddEncodedCertificateToStore function also makes a copy of the encoded certificate before adding the certificate to the store.

BOOL WINAPI CertAddEncodedCertificateToStore(
HCERTSTORE hCertStore,
DWORD dwCertEncodingType,
const BYTE *pbCertEncoded,
DWORD cbCertEncoded,
DWORD dwAddDisposition,
PCCERT_CONTEXT *ppCertContext
);

Parameters

  • hCertStore
    [in] Handle to the certificate store.

  • dwCertEncodingType
    [in] Specifies the type of encoding used. Currently, only X509_ASN_ENCODING is used; however, additional encoding types may be added in the future.

  • pbCertEncoded
    [in] Pointer to a buffer containing the encoded certificate that is to be added to the certificate store.

  • cbCertEncoded
    [in] Size, in bytes, of the pbCertEncoded buffer.

  • dwAddDisposition
    [in] Specifies the action to take if a matching certificate or link to a matching certificate exists in the store. The following table lists the currently defined disposition values and their uses.

    Value Description
    CERT_STORE_ADD_ALWAYS The function makes no check for an existing matching certificate or link to a matching certificate. A new certificate is always added to the store. This can lead to duplicates in a store.
    CERT_STORE_ADD_NEW If a matching certificate or a link to a matching certificate exists in the store, the operation fails. The GetLastError function returns the CRYPT_E_EXISTS code.
    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, except that if an older certificate is replaced, the properties of the older certificate are incorporated into the replacement certificate.
    CERT_STORE_ADD_REPLACE_EXISTING If a matching certificate or link to a matching certificate exists in the store, the existing certificate or link is deleted and a new certificate is created and added to the store. If a matching certificate or link to a matching certificate does not exist, a new certificate is created and added to the store.
    CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES If a matching certificate exists in the store, that existing context is deleted before creating and adding the new context. The new context inherits properties from the existing certificate.
    CERT_STORE_ADD_USE_EXISTING If a matching certificate or a link to a matching certificate exists, that existing certificate or link is used and properties from the new certificate are added. The function does not fail, but it does not add a new context. If ppCertContext is not NULL, the existing context is duplicated.

    If a matching certificate or link to a matching certificate does not exist, a new certificate is added.

  • ppCertContext
    [out/optional] Pointer to a pointer to the decoded certificate context. This is an optional parameter that can be NULL, indicating that the calling application does not require a copy of the new or existing certificate. When a copy is made, its context must be freed by using the CertFreeCertificateContext function.

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.

Value Description
CRYPT_E_EXISTS This code is returned if CERT_STORE_ADD_NEW is set and the certificate already exists in the store, or if CERT_STORE_ADD_NEWER is set and there is a certificate in the store with a NotBefore date greater than or equal to the NotBefore date on the certificate to be added.
E_INVALIDARG An invalid disposition value was specified in the dwAddDisposition parameter, or an invalid certificate encoding type was specified. Currently, only the X509_ASN_ENCODING type is supported.

Remarks

The desktop platform supports the PKCS_7_ASN_ENCODING flag, but Windows CE does not. Windows CE ignores the flag when it is specified.

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 3.0 or later Wincrypt.h   Crypt32.lib

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

CertAddCertificateContextToStore, CertFreeCertificateContext

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.