CertEnumSubjectInSortedCTL function (wincrypt.h)

Article
02/22/2024

The CertEnumSubjectInSortedCTL function retrieves the first or next TrustedSubject in a sorted certificate trust list (CTL). A sorted CTL is a CTL created with the CERT_CREATE_CONTEXT_SORTED_FLAG set. Used in a loop, this function can retrieve in sequence all TrustedSubjects in a sorted CTL.

Syntax

BOOL CertEnumSubjectInSortedCTL(
  [in]      PCCTL_CONTEXT   pCtlContext,
  [in, out] void            **ppvNextSubject,
  [out]     PCRYPT_DER_BLOB pSubjectIdentifier,
  [out]     PCRYPT_DER_BLOB pEncodedAttributes
);

Parameters

[in] pCtlContext

A pointer to the CTL_CONTEXT structure to be searched.

[in, out] ppvNextSubject

A pointer to the address of the last TrustedSubject found. To start the enumeration, ppvNextSubject must point to a pointer set to NULL. Upon return, the pointer addressed by ppvNextSubject is updated to point to the next TrustedSubject in the encoded sequence.

[out] pSubjectIdentifier

A pointer to a CRYPT_DER_BLOB structure, uniquely identifying a TrustedSubject. The information in this structure can be a hash or any unique byte sequence.

[out] pEncodedAttributes

A pointer to a CRYPT_DER_BLOB structure containing a byte count and a pointer to the TrustedSubject's encoded attributes.

Return value

If the function succeeds, the return value is TRUE, with ppvNextSubject updated to point to the next TrustedSubject in the encoded sequence.

If the function fails, the return value is FALSE. The return value is FALSE if there are no more subjects or there is an argument that is not valid.

Remarks

The pbData members of CRYPT_DER_BLOB structures point directly to the encoded bytes. The CRYPT_DER_BLOB structures, themselves, must be allocated and freed by the application, but the memory addressed by the pbData members of these structures is not allocated by the application and must not be freed by the application.

If the CTL is not sorted with the CERT_CREATE_CONTEXT_SORTED_FLAG flag set, an error results.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll