The ds_bind( ) call establishes a session with the directory. The ds_bind( ) call corresponds to the DirectoryBind function in the Abstract Service defined in the X.500 standard.
When a ds_bind( ) call completes successfully, the directory returns a pointer to an OM private object of OM class DC_C_SESSION. This parameter is then passed as the first parameter to most interface function calls until a ds_unbind( ) is called to terminate the directory session.
XDS API supports multiple concurrent sessions so that an application can interact with the directory service by using several identities, and interact directly and concurrently with different parts of the directory service.
The following code fragment from example.c shows how an application binds to the GDS server (without credentials) by using the default session:
CHECK_DS_CALL(ds_bind(DS_DEFAULT_SESSION, workspace, &session));
If a user wants to do an authenticated bind and/or wants to specify the directory identifier, an instance of OM class DSX_C_GDS_SESSION from the GDS package is required. DSX_C_GDS_SESSION identifies a particular link from an application to a DSA. Since DSX_C_GDS_SESSION is a subclass of the standard OM class for a session, DS_C_SESSION, it may be passed as a parameter to an XDS API function, such as ds_bind( ), wherever a standard session is expected.
The following code fragment from acl.c shows how an application performs an authenticated bind to the GDS:
/*
* Create a default session object.
*/
if ((rc = om_create(DSX_C_GDS_SESSION,OM_TRUE,workspace,&session))
!= OM_SUCCESS)
printf("om_create() error %d\n", rc);
/*
* Alter the default session object to include the following
* credentials:
* requestor: /C=de/O=sni/OU=ap/CN=norbert
* password: "secret"
* authentication mechanism: simple
*/
if ((rc = om_put(session, OM_REPLACE_ALL, credentials, 0 ,0, 0))
!= OM_SUCCESS)
printf("om_put() error %d\n", rc);
/*
* Bind with credentials to the default GDS server.
* The returned session object is stored in the private object
* variable bound_session and is used for all further XDS
* function calls.
*/
if (ds_bind(session, workspace, &bound_session) != DS_SUCCESS)
printf("ds_bind() error\n");
The program creates a default session object by using the XOM API function om_create( ) and alters the default session object by using om_put( ). The bind credentials are initialized in the following code fragment from the example.h header file included in the main program module:
/* The following descriptor list specifies
* the bind credentials
*/
static OM_descriptor credentials[] = {
{DS_REQUESTOR, OM_S_OBJECT, {0, dn_norbert} },
{DSX_PASSWORD, OM_S_OCTET_STRING, OM_STRING("secret")},
{DSX_AUTH_MECHANISM, OM_S_ENUMERATION, {DSX_SIMPLE,0}},
OM_NULL_DESCRIPTOR
};
The credentials parameter is provided as an input parameter to the om_put( ) function call to modify the existing session object in the directory service. A private object is returned to the workspace by om_put( ) that is used for all subsequent directory calls.