The CertCreateCertificateContext function creates a certificatecontext from an encoded certificate. The created context is not persisted（不变的） to a certificate store. The function makes a copy of the encoded certificate within the created context.

PCCERT_CONTEXT WINAPI CertCreateCertificateContext(
  __in  DWORD dwCertEncodingType,
  __in  const BYTE* pbCertEncoded,
  __in  DWORD cbCertEncoded
);

Parameters

dwCertEncodingType

Specifies the type of encoding used. It is always acceptable to specify both the certificate andmessage encoding types 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:

• X509_ASN_ENCODING
• PKCS_7_ASN_ENCODING

pbCertEncoded

A pointer to a buffer that contains the encoded certificate from which the context is to be created.

cbCertEncoded

The size, in bytes, of the pbCertEncoded buffer.

Return Value

If the function succeeds, the function returns a pointer to a read-only CERT_CONTEXT. When you have finished using the certificate context, free it by calling theCertFreeCertificateContext function.

If the function is unable to decode and create the certificate context, it returns NULL. For extended error information, callGetLastError. Some possible error codes follow.

If the function fails, GetLastError may return an Abstract Syntax Notation One (ASN.1) encoding/decoding error. For information about these errors, seeASN.1 Encoding/Decoding Return Values.

Remarks

The CERT_CONTEXT must be freed by calling CertFreeCertificateContext.CertDuplicateCertificateContext can be called to make a duplicate.CertSetCertificateContextProperty andCertGetCertificateContextProperty can be called to store and read properties for the certificate.

Example Code [C++]

The following example shows creating a certificate context from an encoded certificate. The created context is not put in a certificate store. For another example that uses this function, seeExample C Program: Certificate Store Operations.

#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

PCCERT_CONTEXT  pCertContext = NULL; 

//------------------------------------------------------------------ 
//  Create a new certificate from the encoded part of
//  an available certificate. pDesiredCert is a previously
//  assigned PCCERT_CONTEXT variable.
if(pCertContext = CertCreateCertificateContext(
    MY_ENCODING_TYPE,              // The encoding type
    pDesiredCert->pbCertEncoded,   // The encoded data from
                                   // the certificate retrieved
    pDesiredCert->cbCertEncoded))  // The length of the encoded data
{
    printf("A new certificate as been created.\n");
 
    // Use the certificate context as needed.
    // ...

    // When finished, free the certificate context.
    CertFreeCertificateContext(pCertContext);
}
else
{
    printf("A new certificate could not be created.\n");
    exit(1);
}

CertAddCertificateContextToStore Function

The CertAddCertificateContextToStore function adds a certificate context to the certificate store.

Syntax

BOOL WINAPI CertAddCertificateContextToStore(
  __in       HCERTSTORE hCertStore,
  __in       PCCERT_CONTEXT pCertContext,
  __in       DWORD dwAddDisposition,
  __out_opt  PCCERT_CONTEXT* ppStoreContext
);

Parameters

hCertStore

Handle of a certificate store.

pCertContext

A pointer to the CERT_CONTEXT structure to be added to the store.

dwAddDisposition

Specifies the action to take if a matching certificate or a link to a matching certificate already exists in the store. Currently defined disposition values and their uses are as follows.

Value	Meaning
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, the operation fails.GetLastError returns the CRYPT_E_EXISTS code.
CERT_STORE_ADD_REPLACE_EXISTING	If a link to a matching certificate exists, that existing certificate or link is deleted and a new certificate is created and added to the store. If a matching certificate or a link to a matching certificate does not exist, a new link is added.
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.
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. IfppCertContext is not NULL, the existing context is duplicated. If a matching certificate or a link to a matching certificate does not exist, a new certificate is added.

ppStoreContext

A pointer to a pointer to the copy to be made of the certificate that was added to the store.

The ppStoreContext parameter can be NULL, indicating that the calling application does not require a copy of the added certificate. If a copy is made, it must be freed by usingCertFreeCertificateContext.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. For extended error information, callGetLastError. Some possible error codes follow.

CertEnumCertificatesInStore Function

The CertEnumCertificatesInStore function retrieves the first or next certificate in a certificate store. Used in a loop, this function can retrieve in sequence all certificates in a certificate store.

Syntax

PCCERT_CONTEXT WINAPI CertEnumCertificatesInStore(
  __in  HCERTSTORE hCertStore,
  __in  PCCERT_CONTEXT pPrevCertContext
);

Parameters

hCertStore

A handle of a certificate store.

pPrevCertContext

A pointer to the CERT_CONTEXT of the previouscertificate context found.

This parameter must be NULL to begin the enumeration and get the first certificate in the store. Successive certificates are enumerated by settingpPrevCertContext to the pointer returned by a previous call to the function. This function frees theCERT_CONTEXT referenced by non-NULL values of this parameter.

For logical stores, including collection stores, a duplicate of the pCertContext returned by this function cannot be used to begin a new subsequence of enumerations because the duplicated certificate loses the initial enumerationstate. The enumeration skips any certificate previously deleted by CertDeleteCertificateFromStore.

Return Value

If the function succeeds, the function returns a pointer to the next CERT_CONTEXT in the store. If no more certificates exist in the store, the function returns NULL.

For extended error information, call GetLastError. Some possible error codes follow.

Remarks

The returned pointer is freed when passed as the pPrevCertContext parameter on a subsequent call. Otherwise, the pointer must be freed by callingCertFreeCertificateContext. A non-NULLpPrevCertContext passed toCertEnumCertificatesInStore is always freed even for an error.

A duplicate of the currently enumerated certificate can be made by calling CertDuplicateCertificateContext.

Example Code [C++]

The following example lists the certificate contexts in the certificate store. For another example that uses this function, seeExample C Program: Deleting Certificates from a Certificate Store.

void TestCertEnumCertificatesInStore()
{
	// Declare and initialize variables.
	HANDLE          hStoreHandle = NULL;
	PCCERT_CONTEXT  pCertContext = NULL;   
	char * pszStoreName = "CA";

	//--------------------------------------------------------------------
	// Open a system certificate store.
	if (hStoreHandle = CertOpenSystemStore(
		NULL,     
		pszStoreName))
	{
		printf("The %s store has been opened. \n", pszStoreName);
	}
	else
	{
		printf("The store was not opened.\n");
		exit(1);
	}

	//-------------------------------------------------------------------
	// Find the certificates in the system store. 
	while(pCertContext= CertEnumCertificatesInStore(
		hStoreHandle,
		pCertContext)) // on the first call to the function,
		// this parameter is NULL 
		// on all subsequent calls, 
		// this parameter is the last pointer 
		// returned by the function
	{
		//----------------------------------------------------------------
		// Do whatever is needed for a current certificate.
		// ...
	} // End of while.

	//--------------------------------------------------------------------
	//   Clean up.
	if (!CertCloseStore(
		hStoreHandle,
		0))
	{
		printf("Failed CertCloseStore\n");
		exit(1);
	}
}