CertAddEncodedCTLToStore

The CertAddEncodedCTLToStore function creates a CTL context from an encoded CTL and adds it to the certificate store. The function makes a copy of the CTL context before adding it to the store.

#include <wincrypt.h>
BOOL WINAPI CertAddEncodedCTLToStore(
  HCERTSTORE hCertStore,                   // in
  DWORD dwMsgAndCertEncodingType,          // in
  const BYTE *pbCtlEncoded,                // in
  DWORD cbCtlEncoded,                      // in
  DWORD dwAddDisposition,                  // in
  PCCTL_CONTEXT *ppCtlContext              // out, optional
);

Parameters

hCertStore

Handle to the certificate store.

dwMsgAndCertEncodingType

The type of encoding used. The message encoding pertains to the signed message and to the encoded CTL. The certificate encoding pertains to certificates that might be included in the signed message. Note that both a certificate and message encoding type is required to be specified by combining them with a bitwise OR operation as shown in the following example:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Currently defined encoding types are shown in the following table.

Encoding type Value

X509_ASN_ENCODING 0x00000001

PKCS_7_ASN_ENCODING 0x00010000

pbCtlEncoded

Pointer to the encoded CTL that is to be added to the certificate store.

cbCtlEncoded

Size, in bytes, of the encoded CTL to be added to the certificate store.

dwAddDisposition

Encoding type	Value
X509_ASN_ENCODING	0x00000001
PKCS_7_ASN_ENCODING	0x00010000

Value that specifies the action to take if a matching CTL or a link to a matching CTL already exists in the store. Currently defined disposition values and their uses are:

CERT_STORE_ADD_NEW.

If a matching CTL or a link to a matching CTL exists, the operation fails. GetLastError returns CRYPT_E_EXISTS.

CERT_STORE_ADD_USE_EXISTING.

If a matching CTL or a link to a matching CTL exists, that existing CTL is used and properties from the new CTL are addedIf 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.

The function does not fail, but no new CTL is added. If ppCertContext is not NULL, the existing context is duplicated.

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

CERT_STORE_ADD_REPLACE_EXISTING.

If a matching CTL or a link to a matching CTL exists, that existing CTL or link is deleted and a new CTL is created and added to the store. If a matching CTL or a link to a matching CTL does not exist, one is added.

CERT_STORE_ADD_ALWAYS.

Makes no check for an existing matching CTL or a link to a matching CTL. A new CTL is always added to the store. This may lead to duplicates in a store.

CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES.

If a matching CTL exists in the store, that existing context is deleted before creating and adding the new context. The new context inherits properties from the existing CTL.

CERT_STORE_ADD_NEWER

If a matching CTL or a link to a matching CTL exists, the ThisUpdate times on the CTLs are compared. If the existing CTL has a ThisUpdate time less than the ThisUpdate time on the new CTL, the old CTL or link is replaced just as with CERT_STORE_ADD_REPLACE_EXISTING. If the existing CTL has a ThisUpdate time greater than or equal to the ThisUpdate time on the CTL to be added, the function fails with GetLastError returning CRYPT_E_EXISTS.

If a matching CTL or a link to a matching CTL is not found in the store, a new CTL 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 CTL is replaced, the properties of the older CTL are incorporated into the replacement CTL.

ppCtlContext

Pointer to a pointer to the decoded CTL context. This is an optional parameter that can be NULL, indicating that the caller does not want a copy of the added or existing CTL. If a copy is made, it must be freed by using CertFreeCTLContext.

Return Values

TRUE if the function succeeded. FALSE if the function failed.

GetLastError returns the reason for any failures using the following error codes:

CRYPT_E_EXISTS: This error is returned if CERT_STORE_ADD_NEW is set and the CTL already exists in the store or if CERT_STORE_ADD_NEWER is set and a there is a CTL in the store with a ThisUpdate time greater than or equal to the ThisUpdate time on the CTL to be added.
CRYPT_E_OSS_ERROR: An ASN.1 decoding error occurred. To get the OSS error, subtract CRYPT_E_OSS_ERROR from the returned error and see asn1code.h for details on the error.
E_INVALIDARG: An invalid add disposition was specified by the dwAddDisposition argument or an invalid encoding type was specified. Currently only X509_ASN_ENCODING and PKCS_7_ASN_ENCODING are supported.

Example

See CertAddEncodedCertificateToStore. In that example, change all references to "certificate" to "CTL."

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.

CertAddEncodedCTLToStore

Parameters

Return Values

Example

QuickInfo

See Also