VgwSecurityGetInfoFnc


Use the VgwSecurityGetInfoFnc function to specify the list of credential types needed by your gateway driver’s VgwAuthenticateFnc function. The Verity engine calls your VgwSecurityGetInfoFnc function before calling your gateway driver’s VgwAuthenticateFnc function.


Syntax

VdkError VgwSecurityGetInfoFnc(
   VSecModuleInfo   vsecInfo)

Arguments

 


vsecInfo

VSecModuleInfo   A pointer to a ModuleRq structure.


Member Descriptions

 

Table 6-5    ModuleRq Members


Member

Type/Description

rq

ModInfoType   A ModInfoType enumerator of which the only valid value is CredentialKeyInfo.

i_params

void*   A pointer to a VSecArg structure that specifies the input parameters.

o_params

void*   A pointer to a ModuleCredKeys structure that will identify the required credential types.


 

Table 6-6    ModuleCredKeys Members


Member

Type/Description

nrqrd

int   The number of elements in the rqrd static array of credential component structures.

rqrd

credentialComponent*   A pointer to a static array of credential component structures for required components.

nopt

int   The number of elements in the opts static array of credential component structures.

opts

credentialComponent*   A pointer to a static array of credential component structures for optional components.


For a description of the credentialComponent structure, see credentialComponent Members under the VgwAuthenticateFnc function.


Returns

This function must return one of the following error codes:

VdkSuccess for success

 

VdkError_* for a standard Verity Developer Kit API error as described in the Verity Developer’s Kit Programming Reference

 

VdkFail for a non-specific error

 


Discussion

Your VgwSecurityGetInfoFnc function must return the credential types to be checked during authentication. When the Verity engine calls your VgwSecurityGetInfoFnc function, the vsecInfo argument points to a ModuleRq structure, whose members specify the module request type (rq member), input parameter (i_params member), and output parameter (o_params member).

The module request type should be CredentialKeyInfo for a credential-based security module; other modules need not be supported. The input parameter points to a VSecArgRec structure, which you can use to provide logging from this function. (For a description of the VSecArg structure, see VSecArg Members under the VgwAuthenticateFnc function.)

The output parameter points to a ModuleCredKeys structure, in which you provide the keys of the credentials to check. You can divide the credentials into those that are required and those that are optional.

You must allocate global static memory to hold the credentials specified by your VgwSecurityGetInfoFnc function; there is no way to free this memory.


Example

static VdkError
VDK_CALLBACK VgwSecurityGetInfo(VSecModuleInfo pInfo)
{
/******************************************************
* define gateway driver required credential keys here
* this must be a static global memory allocation
******************************************************/

static credentialComponent rkeys[] = {
{REPOSITORY_KEY, 0, NULL, 0},
{USERNAME_KEY, 0, NULL, 0}, {PASSWD_KEY, 0, NULL, 0}
};

/************************************************************
* define gateway driver returned credential key struct here
* this must be a static global memory allocation
************************************************************/

static ModuleCredKeys authkeys = {
3, rkeys, 0, NULL
};

if (!pInfo)
return VdkError_InvalidArgs;

switch (pInfo->rq) {

case CredentialKeyInfo:
pInfo->o_params = (void*)&authkeys;
break;

default:
return VdkError_Unsupported;
}
return VdkSuccess;
}