Programming Guides › Programming Guide for C › Context Structures

Context Structures

This section contains the following topics:

Sm_Api_AppSpecificContext_t

Sm_Api_Context_t

Sm_Api_RequestContext_t

Sm_Api_TunnelContext_t

Sm_Api_UserContext_t

Sm_AuthApi_UserCredentials_t

Sm_Api_AppSpecificContext_t

This structure contains shared memory information.

Syntax

The syntax of this structure is:

typedef struct
{
   void* pHandle;
   Sm_Api_GetBufferFunc fGetBuffer;
   Sm_Api_AllocBufferFunc fAllocBuffer; 
   Sm_Api_FreeBufferFunc fFreeBuffer;
   Sm_Api_GetBufferSizefunc fGetBufferSize;
} Sm_Api_AppSpecificContext_t;

Field	Description
pHandle	A handle to be passed, required by memory management functions. This handle is obtained from the pAppSpecific field of Sm_Api_Context_t.
fGetBuffer	Function that returns a pointer to the previously allocated request-specific memory or NULL if no memory was allocated. pHandle is the function’s only parameter.
fAllocBuffer	Function that allocates request-specific memory and returns a pointer to the allocated buffer. It returns NULL if the buffer has already been allocated or no memory is available. Parameters are pHandle and an int specifying the size of the buffer.
fFreeBuffer	Function that releases any request-specific memory associated with the passed pHandle argument. No value is returned.
fGetBufferSize	Function that retrieves the size of the buffer.

Function Declarations

In structure Sm_Api_AppSpecificContext_t, the functions fGetBuffer, fAllocBuffer, fFreeBuffer, and fGetBufferSize are declared in SmApi.h as follows:

fGetBuffer

typedef void* (SM_EXTERN *Sm_Api_GetBufferFunc) 
    (const void *pHandle);

fAllocBuffer

typedef void* (SM_EXTERN *Sm_Api_AllocBufferFunc) 
    (const void *pHandle, const int nSize);

fFreeBuffer

typedef void (SM_EXTERN *Sm_Api_FreeBufferFunc) 
   (const void *pHandle);

fGetBufferSize

typedef int (SM_EXTERN *Sm_Api_GetBufferSizeFunc) 
   (const void *pHandle);

Example

// Allocate 64 bytes
char* pBuffer = (char*) lpApiContext->pAppSpecific->fAllocBuffer
                (lpApiContext->pAppSpecific->pHandle, 64);
strcpy (pBuffer, "id=5");
...

// Use it somewhere else
char id[20];
char* pBuffer = (char*) lpApiContext->pAppSpecific->fGetBuffer
                (lpApiContext->pAppSpecific->pHandle);
if (pBuffer != NULL)
{
   strcpy (id, pBuffer);
}

//Free the memory when done
...
(char*) lpApiContext->pAppSpecific->fFreeBuffer
                (lpApiContext->pAppSpecific->pHandle);

Sm_Api_Context_t

This structure contains general API information.

Syntax

typedef struct
{
   int nVersion;
   Sm_Api_LogFunc fLog;
   Sm_Api_TraceFunc fTrace;
   Sm_Api_ErrorFunc fError;
   Sm_Api_AppSpecificContext_t*  pAppSpecific;
} Sm_Api_Context_t;

Field	Description
nVersion	Version number of the API being used. Possible values: Sm_Api_Version_V3 Sm_Api_Version_V4 Sm_Api_Version_V4_1 Version constants are defined in SmApi.h.
fLog	Function for accessing the SiteMinder logging utility. SiteMinder must be running with logging enabled. The calling syntax for this function is: char* lpszMessage = "Log this text"; lpApiContext->fLog (lpszMessage);
fTrace	Function for accessing the SiteMinder trace utility. SiteMinder must be running with tracing enabled. The calling syntax for this function is: char* lpszCheckpoint = "MyLib"; char* lpszTraceMessage = "Trace text"; lpApiContext->fTrace (lpszCheckpoint, lpszTraceMessage);
fError	Function for accessing the SiteMinder error utility. SiteMinder must be running with logging enabled. The calling syntax for this function is: char* lpszMessage = "Log this Error text"; lpApiContext->fError (lpszMessage);
pAppSpecific	The pAppSpecific pointer has access to the methods in the Sm_Api_AppSpecificContext_t structure. These methods allocate, delete, and release request-specific memory. This memory persists during the entire processing of a single agent request and is local to each server process such as authentication and authorization daemons. There is no limit as to the number of times memory can be allocated and released by a module. Once a request is processed, memory is released automatically.

Function Declarations

In structure Sm_Api_Context_t, the functions fLog, fTrace, and fError are declared in SmApi.h as follows:

fLog

/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_LogFunc) (const char* lpszBuffer);

fTrace

/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_TraceFunc)
   (const char* lpszCheckpoint, const char* lpszBuffer);

fError

/* string to log (null-terminated) */
typedef void (SM_EXTERN *Sm_Api_ErrorFunc) 
   (const char* lpszBuffer);

Sm_Api_RequestContext_t

Contains information about the request being made.

Syntax

typedef struct
{
   char* lpszServer;
   char* lpszResource;
   char* lpszAction;
} Sm_Api_RequestContext_t;

Field	Description
lpszServer	Server part of the user access request. For example, if the user accesses http://www.server.com/index.html, the server is www.server.com.
lpszResource	Resource part of the user access request. For example, if the user accesses http://www.server.com/index.html, the resource is /index.html.
lpszAction	The action as requested by the user. For example, the typical action when accessing Web resources is a GET.

Sm_Api_TunnelContext_t

Holds information passed from the Tunnel Agent.

Syntax

typedef struct
{
   char* lpszClientIp;
   char* lpszTransactionId;
   char* lpszParameter;
} Sm_Api_TunnelContext_t;

Field	Description
lpszClientIP	The IP Address of the Tunnel Agent making the tunnel calls.
lpszTransactionId	(Optional) The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID.
lpszParameter	Arbitrary string parameter passed from the Tunnel Agent. On the Tunnel Agent side, this information is passed in lpszParameter in Sm_AgentApi_TunnelServiceRequest_t.

Sm_Api_UserContext_t

Contains information about the user.

Syntax

typedef struct
{
   unsigned char  bIsUserContext;
   char* lpszUserName;
   char* lpszUserPath;
   char* lpszDirPath;
   void* lpReserved1;
   char* lpszDirServer;
   char* lpszDirNamespace;
   char* lpszSessionId;
   Sm_Api_GetDnProp fGetDnProp;
   Sm_Api_SetDnProp fSetDnProp;
   void* lpParam;
   Sm_Api_GetUserProp fGetProp;
   Sm_Api_SetUserProp fSetProp;
   Sm_Api_AuthenticateUser fAuthenticate;
} Sm_Api_UserContext_t;

Field	Description
bIsUserContext	Flag indicating that SiteMinder has established the user’s identity and that the user context is available. When this flag is set, the fGetProp, fSetProp, fGetDnProp, and fSetDnProp user attribute functions are available.
lpszUserName	Full distinguished name of the user.
lpszUserPath	User path in the following format: directory-namespace + server + / + user-DN For example: ldap://server.company.com/ uid=user1,ou=people,o=company.com
lpszDirPath	Directory path of the SiteMinder user directory where the user context was established, in the following format: directory-namespace + server For example: ldap://server.company.com
lpReserved1	Reserved for internal use.
lpszDirServer	Directory server of a SiteMinder user directory where user’s context was established.
lpszDirNamespace	Directory namespace such as LDAP:, AD:, WinNT:, or ODBC:.
lpszSessionId	Session ID that has been or will be assigned to the user’s session, depending on whether or not the session has been established.
fGetDnProp	Function that returns an attribute of a directory entry. If the user context flag bIsUserContext is set, developers can call this function to retrieve a well-known attribute of any DN that the user is related to in the context of a directory (for example, user is a member of a group). The calling syntax for this function is: if (lpUserContext->bIsUserContext) { char lpszDN[]="cn=group,ou=org unit,o=org"; char lpszCommonName[100]; int nBytes = lpUserContext->fGetDnProp( lpUserContext->lpParam, lpszDN, "accesslevel", sizeof (lpszCommonName), lpszCommonName); } If no error occurs, the function places the value of the requested attribute in the null-terminated output buffer and returns its length. Otherwise, the function returns –1. The attribute returned from this function should not be larger than the maximum buffer size specified in the nBytesValueBuf argument. Larger attributes are truncated to nBytesValueBuf.
fSetDnProp	Function that sets an attribute of a directory entry. If the user context flag bIsUserContext is set, developers can call this function to set a well-known attribute of any DN that the user is related to in the context of a directory (for example: user is a member of a group). At this time only attributes of type ‘string’ are supported. The calling syntax for this function is: if (lpUserContext->bIsUserContext) { char lpszDN[]="cn=group,ou=org unit,o=org"; char lpszTimestamp[] = "<timestamp>"; int nErr = lpUserContext->fSetDnProp ( lpUserContext->lpParam, lpszDN, "lastaccess", sizeof (lpszTimestamp), lpszTimestamp); }
lpParam	Pointer to the parameters to be passed to fGetProp, fSetProp, fGetDnProp, and, fSetDnProp functions.
fGetProp	Function that returns user attributes. If the user context flag bIsUserContext is set, developers can call this function to retrieve a well-known user attribute. The calling syntax for this function is: if (lpUserContext->bIsUserContext) { char lpszCommonName[100]; int nBytes = lpUserContext->fGetProp ( lpUserContext->lpParam, "cn", sizeof (lpszCommonName), lpszCommonName); } If no error occurs, the function places the value of the requested attribute in the null-terminated output buffer and returns its length. Otherwise, the function returns -1. The attribute returned from this function should not be larger than the maximum buffer size specified in the nBytesValueBuf argument. Larger attributes are truncated to nBytesValueBuf.
fSetProp	Function that sets a user attribute. If the user context flag bIsUserContext is set, developers can call this function to set a well-known user attribute. At this time, only attributes of type “string” are supported. The calling syntax for this function is: if (lpUserContext->bIsUserContext) { char lpszCommonName[] = "John Smith"; int nErr = lpUserContext->fSetProp ( lpUserContext->lpParam, "cn", sizeof (lpszCommonName), lpszCommonName); } If no error occurs, the function returns 0. Otherwise, the function returns -1.

Function Declarations

In structure Sm_Api_UserContext_t, the functions fGetDnProp, fSetDnProp, fGetProp, fSetProp, and fAuthenticate are declared in SmApi.h as follows:

fGetDnProp

typedef int (SM_EXTERN *Sm_Api_GetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf /* Output buffer to hold the user property */
);

fSetDnProp

typedef int (SM_EXTERN *Sm_Api_SetDnProp)
(
const void* lpParam,        /* The function parameter */
const char* lpDn,           /* The DN of a directory object */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);

fGetProp

typedef int (SM_EXTERN *Sm_Api_GetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Max size of user property buffer */
char* lpszValueBuf   /* Output buffer to hold the user property */
);

fSetProp

typedef int (SM_EXTERN *Sm_Api_SetUserProp)
(
const void* lpParam,        /* The function parameter */
const char* lpszPropName,   /* User property name (null-term) */
const int nBytesValueBuf,   /* Size of user property buffer */
const char* lpszValueBuf    /* The user property buffer */
);

fAuthenticate

typedef int (SM_EXTERN *Sm_Api_AuthenticateUser)
(
const void* lpParam,        /* The function parameter */
const char* lpszPassword,   /* User password (null-terminated) */
const int nBytesUserMsg,    /* Max size of user message buffer */
char* lpszUserMsg,   /* Output buffer to hold the user message */
const int nBytesErrMsg,    /* Maximum size of the error buffer */
char* lpszErrMsg    /* Output buffer to hold the error message */
);

More Information:

Multi-Valued Attributes in LDAP

When setting or retrieving multi-valued attributes in an LDAP user store, the values are presented in a single string, delimited by a carat character ( ^ ).

For example, you might set three different telephone numbers as follows:

char lpszTemp[] = "111-1234^111-5678^111-0000";

int getResult = lpUserContext->fSetProp (lpUserContext->lpParam,
                                         "telephonenumber",
                                         strlen(lpszTemp),
                                         lpszTemp);

Custom code that sets or retrieves multi-valued attributes must support the expected multi-valued string format.

Note: ODBC user stores do not support multi-valued attribute settings.

Policy Server Version Support

With a 4.61 or later Policy Server, the telephone numbers in the example above are put into the user’s telephone number attribute in the LDAP user store as follows:

111-1234
111-5678
111-0000

Prior to the 4.61 Policy Server, the above code would set the telephone number attribute as follows:

111-1234^111-5678^111-0000

Sm_AuthApi_UserCredentials_t

Contains information about user credentials.

SiteMinder specifies as much information as it has available. Typically, the username and password fields are specified. Each authentication scheme expects a subset of possible credentials.

Fields in this structure are filled in on the basis of requested credentials.

Syntax

typedef struct
{
   char* lpszUsername;
   char* lpszPassword;
   int   nBytesChapPassword;
   char* lpszChapPassword;
   int   nBytesChapChallenge;
   char* lpszChapChallenge;
   char* lpReserved1;
   char* lpszCertUserDN;
   char* lpszCertIssuerDN;
   int   nCertBinLen;
   void* lpCertBinary;
   char* lpszDirPath;
   char* lpszDirServer;
   char* lpszDirNamespace;
   char* lpszNewPassword;
   char* lpszPasswordToken;
} Sm_AuthApi_UserCredentials_t;

Field	Description
lpszUsername	User’s DN as disambiguated by SiteMinder from the username specified by the user.
lpszPassword	User password as specified by the user.
nBytesChapPassword	Length of the CHAP password.
lpszChapPassword	CHAP password.
nBytesChapChallenge	Length of the CHAP challenge.
lpszChapChallenge	CHAP challenge.
lpReserved1	Reserved for internal use.
lpszCertUserDN	User DN part of the X.509 user’s Certificate.
lpszCertIssuerDN	Issuer DN part of the X.509 user’s Certificate.
nCertBinLen	Length of the user’s binary X.509 Certificate.
lpCertBinary	User’s binary X.509 Certificate.
lpszDirPath	Directory path in the SiteMinder notation of a SiteMinder user directory where user’s context was established.
lpszDirServer	Directory server in the SiteMinder user directory where user’s context was established.
lpszDirNamespace	Directory namespace in the SiteMinder user directory where user’s context was established.
lpszNewPassword	The user’s new password.
lpszPasswordToken	The password token from Password Services.