gsk_get_directory_certificates()

Gets the certificates stored in the LDAP directory for the subject.

Format

   #include <gskcms.h>

   gsk_status gsk_get_directory_certificates ( 
                                               gsk_handle                  directory_handle, 
                                               x509_name *                 subject_name,
                                               gsk_boolean                 ca_certificates,   
                                               pkcs_certificates *         certificates)

Parameters

directory_handle: Specifies the directory handle returned by the gsk_open_directory() routine.
subject_name: Specifies the certificate subject.
ca_certificates: Specify TRUE if the subject is a certification authority or FALSE if the subject is an end entity.
certificates: Returns the certificates for the subject. The application should call the gsk_free_certificates() routine to release the certificates when they are no longer needed.

Results

The function return value will be 0 if no error is detected. Otherwise, it will be one of the return codes listed in the gskcms.h include file. These are some possible errors:

[CMSERR_BAD_HANDLE]: The directory handle is not valid.
[CMSERR_LDAP]: An error is detected by the LDAP runtime support.
[CMSERR_LDAP_NOT_AVAILABLE]: The LDAP server is not available.
[CMSERR_NO_MEMORY]: Insufficient storage is available.
[CMSERR_RECORD_NOT_FOUND]: The requested certificate is not found.

Usage

The gsk_get_directory_certificates() routine retrieves the certificates that are stored in the LDAP directory for the specified subject name. When matching UTF-8 encoded attribute values in the subject name, System SSL uses a case sensitive (exact match) comparison. The directory schema is defined by RFC 2587: PKIX LDAP Version 2 Schema. The certificates are stored as attributes of the subject directory entry. Each certificate is encoded as defined by RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. The userCertificate attribute is used to retrieve end-entity certificates while the caCertificate attribute is used to retrieve certification authority certificates.

Retrieved certificates are cached so that it is not necessary to contact the LDAP server for subsequent requests for the same certificates. The cached certificates are released when the gsk_close_directory() routine is called to close the directory handle.