RSA BSAFE Cert-C API Reference

ldapapi.h File Reference

This file defines the LDAP service Cert-C API and data types.

#include "certc.h"
#include "transprt.h"

Go to the source code of this file.

Data Structures
	LDAP_DATA
	Use the LDAP_DATA structure to store configuration data for LDAP servers. More...
	LDAP_DATA2
	Passes initialization parameters to S_InitializeLDAP2(). More...
struct	LDAP_INIT_PARAMS
	Passes initialization parameters to the Cert-C LDAP Database service provider's initialization functions. More...
	LDAP_OPTIONS_INFO
	Holds LDAP options. More...
Typedefs
typedef LDAP_DATA	LDAP_DATA
	Use the LDAP_DATA structure to store configuration data for LDAP servers. More...
typedef LDAP_DATA *	PLDAP_DATA
	Use the LDAP_DATA structure to store configuration data for LDAP servers. More...
typedef LDAP_OPTIONS_INFO	LDAP_OPTIONS_INFO
	Holds LDAP options. More...
typedef LDAP_OPTIONS_INFO *	PLDAP_OPTIONS_INFO
	Holds LDAP options. More...
typedef LDAP_DATA2	LDAP_DATA2
	Passes initialization parameters to S_InitializeLDAP2(). More...
typedef LDAP_DATA2 *	PLDAP_DATA2
	Passes initialization parameters to S_InitializeLDAP2(). More...
Functions
int	S_InitializeLDAPSource (POINTER ctx, POINTER params, SERVICE_FUNCS *funcs, POINTER *handle)
	Initializes the Cert-C LDAP Database service provider's functions and initialization parameters when the Cert-C Default Database service provider is used to specify the configuration information. More...
int	S_InitializeLDAP2 (POINTER ctx, POINTER params, SERVICE_FUNCS *funcs, POINTER *handle)
	Initializes the Cert-C LDAP Database service provider's functions and initialization parameters when the Cert-C Default Database service provider is not used to specify the configuration information. More...
int	S_InsertLDAPConfigRecord (CERTC_CTX ctx, char *dbName, PLDAP_DATA pLdapData)
	Call the S_InsertLDAPConfigRecord() function to insert a configuration record for this LDAP source into the LDAP configuration store. More...
int	S_SelectLDAPConfigRecord (CERTC_CTX ctx, char *dbName, PLDAP_DATA pLdapData)
	Call the S_SelectLDAPConfigRecord() function to retrieve the LDAP record indicated by the descriptiveName in pLdapData. More...
int	S_DeleteLDAPConfigRecord (CERTC_CTX ctx, char *dbName, char *sourceName)
	Call the S_DeleteLDAPConfigRecord() function to delete the LDAP configuration record that has sourceName for its descriptive name. More...
int	S_GetLDAPSourceList (CERTC_CTX ctx, char *dbName, LIST_OBJ *ldapSourceNames)
	Call the S_GetLDAPSourceList() function to return the list of all configured LDAP sources. More...

---

Typedef Documentation

typedef struct LDAP_DATA LDAP_DATA

Use the LDAP_DATA structure to store configuration data for LDAP servers. This configuration data is necessary because each LDAP server's parameters can vary significantly. Cert-C LDAP Database service-provider-specific APIs allow you to add, modify, and delete LDAP configuration records. The configuration data is used by the Cert-C LDAP Database service provider when it needs to perform an LDAP operation. When the Cert-C LDAP Database service provider is registered, the corresponding configuration record is retrieved and cached for use in subsequent LDAP connections. If any of the configuration APIs are invoked to modify the configuration data, that change does not affect any currently registered Cert-C LDAP Database service providers. For a change to take place, the service provider must be unregistered and then re-registered. For example, if you register a Cert-C LDAP Database service provider and call the S_SelectLDAPConfigRecord() function to modify the data, and then call S_InsertLDAPConfigRecord(), the data store contains the new configuration values. However, the currently registered Cert-C LDAP Database service provider still uses the old values. For the new values to take effect, unregister and then re-register the Cert-C LDAP Database service provider. Parameters: descriptiveName The descriptive name for this LDAP server. It is a human-readable string that an application can display to the end user. The descriptiveName is used as the unique ID for the LDAP data record and cannot be changed. If a user wants to change the name, then they have to delete the old record and add it again with a new name. networkAddress The network address for the LDAP host. It is the Internet address of the LDAP host in a string format. portNo The TCP LDAP port number. authType The authentication method. The following authentication methods are supported by Cert-C: Authentication Method Description LDAP_AUTH_NONE No authentication is required. LDAP_INIT_PARAMS's userName and userPassword are ignored. LDAP_AUTH_SIMPLE Simple authentication. LDAP_INIT_PARAMS's userName and userPassword are used to authenticate the user when connecting to the LDAP server. sizeLimit The limit on the number of entries to return from the search. A value of 0 (zero) means no limit. timeLimit The limit on the number of seconds to spend on the search. A value of 0 (zero) means no limit. baseDNAttrs A string consisting of a comma-separated list of DN attributes, such as o,c. An optional white space can follow the commas. This is used in an LDAP search to build the base DN. searchRoot The base DN where the LDAP search should start, when a search using the given subject name or given base DN has failed, such as c=us. searchFilterAttrs The search filter used in an LDAP search when retrieving a certificate by subject name. searchFilterAttrs is a string and follows the same syntax as baseDNAttrs. certificateAttrs A string that follows the same syntax as baseDNAttrs, and contains the directory attribute, or attributes, that can have certificates as their values. It should include both end-entity and CA certificate attributes such as, <userCertificate; binary> and <cACertificate; binary>. Cross-certificates, issued by cross-certifying CAs, are in the <crossCertificatePair;binary> directory entry attribute. certificateRevocationAttrs A directory attribute, or attributes, that can have CRLs as their values. It should include both end-entity and CA CRL attributes; for example, authorityRevocationList;binary and certificateRevocationList;binary. In many LDAP schemas, both of these directory entry attributes can have a CRL as their value. certificateRevocationAttrs is a string and follows the same syntax as baseDNAttrs. searchPriority The order in which the service provider searches multiple LDAP sources. Sources with the same priority search are searched in arbitrary order. Zero is the highest priority. disconnectBeforeConnect Determines if the LDAP source requires disconnecting before performing another operation. You should set this field to TRUE if it is to be disconnected. If more than one operation can be performed with the same LDAP connection, then you should set this to FALSE to enhance performance. otherData This field is reserved for future use; it should remain empty.

typedef struct LDAP_DATA2 LDAP_DATA2

Passes initialization parameters to S_InitializeLDAP2(). Most of the parameters are passed through a LDAP_OPTIONS_INFO structure. Parameters: ldapTransportInfo This input parameter hold all URLs of any directory servers. The client application can provide multiple directory server URLs to allow the LDAP provider to connect to a secondary host in case the primary server is unavailable. Only the destList members of the TRANSPORT_INFO structure is used by the LDAP provider. The URL format for this parameter is ldap://hostname:portNumber/searchRoot. ldapOptionsInfo This input parameter is a LDAP_OPTIONS_INFO structure that contains LDAP options.

typedef struct LDAP_OPTIONS_INFO LDAP_OPTIONS_INFO

Holds LDAP options. Parameters: authType A flag that determines if authentication is required at bind time. sizeLimit The maximum number of entries the server should return from the search. timeLimit The maximum number of seconds that client is willing to wait for a search. baseDNAttrs A comma-separated list of attributes. searchFilterAttrs The criteria used during the search to determine which entries to return. certificateAttrs One of certificate attributes. certificateRevocationAttrs One of certificate revocation aributtes. disconnectBeforeConnect A flag that determines whether to disconnect after a search. userName The user name used to bind to the directory if authType is set to 1. userPassword The password for the user name used to bind to the directory if authType is set to 1.

typedef struct LDAP_DATA * PLDAP_DATA

Use the LDAP_DATA structure to store configuration data for LDAP servers. This configuration data is necessary because each LDAP server's parameters can vary significantly. Cert-C LDAP Database service-provider-specific APIs allow you to add, modify, and delete LDAP configuration records. The configuration data is used by the Cert-C LDAP Database service provider when it needs to perform an LDAP operation. When the Cert-C LDAP Database service provider is registered, the corresponding configuration record is retrieved and cached for use in subsequent LDAP connections. If any of the configuration APIs are invoked to modify the configuration data, that change does not affect any currently registered Cert-C LDAP Database service providers. For a change to take place, the service provider must be unregistered and then re-registered. For example, if you register a Cert-C LDAP Database service provider and call the S_SelectLDAPConfigRecord() function to modify the data, and then call S_InsertLDAPConfigRecord(), the data store contains the new configuration values. However, the currently registered Cert-C LDAP Database service provider still uses the old values. For the new values to take effect, unregister and then re-register the Cert-C LDAP Database service provider. Parameters: descriptiveName The descriptive name for this LDAP server. It is a human-readable string that an application can display to the end user. The descriptiveName is used as the unique ID for the LDAP data record and cannot be changed. If a user wants to change the name, then they have to delete the old record and add it again with a new name. networkAddress The network address for the LDAP host. It is the Internet address of the LDAP host in a string format. portNo The TCP LDAP port number. authType The authentication method. The following authentication methods are supported by Cert-C: Authentication Method Description LDAP_AUTH_NONE No authentication is required. LDAP_INIT_PARAMS's userName and userPassword are ignored. LDAP_AUTH_SIMPLE Simple authentication. LDAP_INIT_PARAMS's userName and userPassword are used to authenticate the user when connecting to the LDAP server. sizeLimit The limit on the number of entries to return from the search. A value of 0 (zero) means no limit. timeLimit The limit on the number of seconds to spend on the search. A value of 0 (zero) means no limit. baseDNAttrs A string consisting of a comma-separated list of DN attributes, such as o,c. An optional white space can follow the commas. This is used in an LDAP search to build the base DN. searchRoot The base DN where the LDAP search should start, when a search using the given subject name or given base DN has failed, such as c=us. searchFilterAttrs The search filter used in an LDAP search when retrieving a certificate by subject name. searchFilterAttrs is a string and follows the same syntax as baseDNAttrs. certificateAttrs A string that follows the same syntax as baseDNAttrs, and contains the directory attribute, or attributes, that can have certificates as their values. It should include both end-entity and CA certificate attributes such as, <userCertificate; binary> and <cACertificate; binary>. Cross-certificates, issued by cross-certifying CAs, are in the <crossCertificatePair;binary> directory entry attribute. certificateRevocationAttrs A directory attribute, or attributes, that can have CRLs as their values. It should include both end-entity and CA CRL attributes; for example, authorityRevocationList;binary and certificateRevocationList;binary. In many LDAP schemas, both of these directory entry attributes can have a CRL as their value. certificateRevocationAttrs is a string and follows the same syntax as baseDNAttrs. searchPriority The order in which the service provider searches multiple LDAP sources. Sources with the same priority search are searched in arbitrary order. Zero is the highest priority. disconnectBeforeConnect Determines if the LDAP source requires disconnecting before performing another operation. You should set this field to TRUE if it is to be disconnected. If more than one operation can be performed with the same LDAP connection, then you should set this to FALSE to enhance performance. otherData This field is reserved for future use; it should remain empty.

typedef struct LDAP_DATA2 * PLDAP_DATA2

Passes initialization parameters to S_InitializeLDAP2(). Most of the parameters are passed through a LDAP_OPTIONS_INFO structure. Parameters: ldapTransportInfo This input parameter hold all URLs of any directory servers. The client application can provide multiple directory server URLs to allow the LDAP provider to connect to a secondary host in case the primary server is unavailable. Only the destList members of the TRANSPORT_INFO structure is used by the LDAP provider. The URL format for this parameter is ldap://hostname:portNumber/searchRoot. ldapOptionsInfo This input parameter is a LDAP_OPTIONS_INFO structure that contains LDAP options.

typedef struct LDAP_OPTIONS_INFO * PLDAP_OPTIONS_INFO

Holds LDAP options. Parameters: authType A flag that determines if authentication is required at bind time. sizeLimit The maximum number of entries the server should return from the search. timeLimit The maximum number of seconds that client is willing to wait for a search. baseDNAttrs A comma-separated list of attributes. searchFilterAttrs The criteria used during the search to determine which entries to return. certificateAttrs One of certificate attributes. certificateRevocationAttrs One of certificate revocation aributtes. disconnectBeforeConnect A flag that determines whether to disconnect after a search. userName The user name used to bind to the directory if authType is set to 1. userPassword The password for the user name used to bind to the directory if authType is set to 1.

---

Function Documentation

int S_DeleteLDAPConfigRecord (  CERTC_CTX    ctx, char *    dbName, char *    sourceName )  ;

Call the S_DeleteLDAPConfigRecord() function to delete the LDAP configuration record that has sourceName for its descriptive name. If the desired record does not exist, a return value of E_NOT_FOUND is returned. Parameters: ctx This input parameter points to an initialized Cert-C context handle. dbName This input parameter is the database name for opening a configuration data store. If empty, the default LDAP configuration database is used. sourceName This input parameter is the descriptive name for the record to be deleted. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int S_GetLDAPSourceList (  CERTC_CTX    ctx, char *    dbName, LIST_OBJ *    ldapSourceNames )  ;

Call the S_GetLDAPSourceList() function to return the list of all configured LDAP sources. Cert-C creates a LIST_OBJ and allocates storage for ldapSourceNames. The list is ordered in ascending order according to searchPriority; zero is the highest priority. Sources with the same priority are arranged in arbitrary order. The client may modify the list and must free it when done. Parameters: ctx This input parameter points to an initialized Cert-C context handle. dbName This input parameter is the database name for opening a configuration data store. If empty, the default LDAP configuration database is used. ldapSourceNames This output parameter is the list of names for all configured LDAP sources. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int S_InitializeLDAP2 (  POINTER    ctx, POINTER    params, SERVICE_FUNCS *    funcs, POINTER *    handle )  ;

Initializes the Cert-C LDAP Database service provider's functions and initialization parameters when the Cert-C Default Database service provider is not used to specify the configuration information. S_InitializeLDAP2() stores pointers to the Cert-C LDAP Database service provider's functions in funcs's db member, which is a DB_FUNCS structure. S_InitializeLDAP2() uses the Cert-C LDAP service provider's initialization parameters in params, which points to an LDAP_INIT_PARAMS structure. S_InitializeLDAPSource() gets the name of the LDAP repository to register and its configuration data store from params. It then registers the Cert-C LDAP Database service provider for the LDAP repository indicated by descriptiveName, which is passed by params. Never call the S_InitializeLDAP2() function directly. Instead, to initialize or register the Cert-C LDAP Database service provider, call the C_InitializeCertC() or C_RegisterService() function. Both functions take SERVICE_HANDLER and a POINTER to a parameters structure as a parameters. SERVICE_HANDLER's Initialize parameter points to the S_InitializeLDAPSource() function, and the corresponding POINTER must point to a LDAP_INIT_PARAMS structure. Note: S_InitializeLDAP2() does not require the use of the Cert-C Default Database service provider to specify the configuration information. If the Cert-C Default Database service provider is used, call S_InitializeLDAPSource() instead. Parameters: ctx This input parameter points to an initialized Cert-C context handle. params This input parameter points to a structure of type LDAP_INIT_PARAMS2. funcs This is both an input and output parameter. As an input parameter, it points to an allocated but uninitialized SERVICE_FUNCS union. As an output parameter, it points to the initialized Cert-C LDAP Database service-provider-specific functions in SERVICE_FUNCS's db member, which is a DB_FUNCS structure. handle This output parameter points to this instance of the Cert-C LDAP Database service provider handle. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int S_InitializeLDAPSource (  POINTER    ctx, POINTER    params, SERVICE_FUNCS *    funcs, POINTER *    handle )  ;

Initializes the Cert-C LDAP Database service provider's functions and initialization parameters when the Cert-C Default Database service provider is used to specify the configuration information. S_InitializeLDAPSource() stores pointers to the Cert-C LDAP Database service provider's functions in funcs's db member, which is a DB_FUNCS structure. S_InitializeLDAPSource() uses the Cert-C LDAP service provider's initialization parameters in params, which points to an LDAP_INIT_PARAMS structure. S_InitializeLDAPSource() gets the name of the LDAP repository to register and its configuration data store from params. It then registers the Cert-C LDAP Database service provider for the LDAP repository indicated by descriptiveName, which is passed by params. Never call the S_InitializeLDAPSource() function directly. Instead, to initialize or register the Cert-C LDAP Database service provider, call the C_InitializeCertC() or C_RegisterService() function. Both functions take SERVICE_HANDLER and a POINTER to a parameters structure as a parameters. SERVICE_HANDLER's Initialize parameter points to the S_InitializeLDAPSource() function, and the corresponding POINTER must point to a LDAP_INIT_PARAMS structure. Note: S_InitializeLDAPSource() requires the use of the Cert-C Default Database service provider to specify the configuration information. If the Cert-C Default Database service provider is not used, call S_InitializeLDAP2() instead. Parameters: ctx This input parameter points to an initialized Cert-C context handle. params This input parameter points to a structure of type LDAP_INIT_PARAMS, that contains the database name and the name of the LDAP repository to be registered. If the database name is not specified, then the default database name in the current directory, ldcfdflt, is used. funcs This is both an input and output parameter. As an input parameter, it points to an allocated but uninitialized SERVICE_FUNCS union. As an output parameter, it points to the initialized Cert-C LDAP Database service-provider-specific functions in SERVICE_FUNCS's db member, which is a DB_FUNCS structure. handle This output parameter points to this instance of the Cert-C LDAP Database service provider handle. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int S_InsertLDAPConfigRecord (  CERTC_CTX    ctx, char *    dbName, PLDAP_DATA    pLdapData )  ;

Call the S_InsertLDAPConfigRecord() function to insert a configuration record for this LDAP source into the LDAP configuration store. If the record already exists (as determined by matching descriptive names) the existing record is overwritten and no error code is returned. This is considered equivalent to a successful modification operation. If the record already exists, all fields are overwritten with the values in pLdapData. Be careful not to inadvertently overwrite data when using this function. To modify an existing record, first call C_SelectLDAPDataRecord() to retrieve the existing record. Next, change only those fields that are to be modified. Finally, call this function to insert the new information. To change the name for this record, delete the record, and then re-insert it under the new name. Parameters: ctx This input parameter points to an initialized Cert-C context handle. dbName This input parameter is the database name for opening the configuration data store. If empty, the default LDAP configuration database is used. pLdapData This input parameter is the LDAP configuration data to add to the configuration store. Returns: If successful, returns 0. If not, returns a Cert-C error code.

int S_SelectLDAPConfigRecord (  CERTC_CTX    ctx, char *    dbName, PLDAP_DATA    pLdapData )  ;

Call the S_SelectLDAPConfigRecord() function to retrieve the LDAP record indicated by the descriptiveName in pLdapData. S_SelectLDAPConfigRecord() then fills in all the pLdapData fields with information found in the database for this record. You own pLdapData, and therefore must manage storage for it. Storage for pLdapData must be allocated before calling S_SelectLDAPConfigRecord(). Parameters: ctx This input parameter points to an initialized Cert-C context handle. dbName This input parameter is the database name for opening a configuration data store. If empty, the default LDAP configuration database is used. pLdapData This is both an input and an output parameter. As an input parameter, it contains the descriptiveName used to retrieve the LDAP record. As an output parameter, it is the LDAP configuration data that is retrieved from the configuration store. Returns: If successful, returns 0. If not, returns a Cert-C error code.

---

RSA BSAFE^® Cert-C 2.7 API Reference