VgwAuthenticateFnc


Use the VgwAuthenticateFnc function to authenticate credentials. The Verity engine calls your VgwAuthenticateFnc function whenever authentication is requested.


Syntax

VdkError VgwAuthenticateFnc(
   VSecCredential     vsecCred,
   VSecCertificate*   pvsecCert,
   VSecArg            vsecArg)


Arguments

 


vsecCred

VSecCredential   A pointer to a VSecCredentialRec structure that contains the credential set to be authenticated.

pvsecCert

VSecCertificate*   Upon successful authentication, a pointer to a valid VSecCertificateRec structure that contains the certificate; otherwise, NULL.

vsecArg

VSecArg   A pointer to the security module’s context.


Member Descriptions

 

Table 6-1    VSecCredentialRec Members


Member

Type/Description

cr_nitems

int   The number of credentials.

cr_items

credentialComponent*   A pointer to an array of credentialComponent structures.


 

Table 6-2    credentialComponent Members


Member

Type/Description

key_type

CredKeyType   Type of credential. Valid values are:

FLAG_KEY Certificate flags

USERNAME_KEY User name

PASSWD_KEY Password

DOMAIN_KEY Domain name

REPOSITORY_KEY A VDK repository structure

ADDR_KEY IP Address

PORT_KEY Port number

HOST_KEY Host name

CERTIFICATE_KEY Certificate

PEERNAME_KEY Peer service or object

LICENSE_KEY License information

MBNMS_KEY List of mailboxes

SRVNMS_KEY List of servers

EXTENSION_KEY Application-specific information

PREAUTH_KEY Flag indicating whether DN_KEY and GROUPS_KEY contain valid information

DN_KEY Distinguished Name when using pre-authenticated user with LDAP

GROUPS_KEY Group Membership List when using pre-authenticated user with LDAP

USER_PARAMS Application- or user-specific data in the form of “name=value” pairs

MAX_CRED_KEY Number of credential types (not an actual type)

key

keyobj   The credential data, which is the union of ikey, skey, and pkey.

key.ikey

unsigned int   An unsigned integer that contains credential data.

key.skey

char*   A pointer to a string that contains credential data.

key.pkey

void*   A pointer to credential data.

exnm

char*   Name of the extension for EXTENSION_KEY key types.

min_exsz

int   Minimum buffer size for extensions.


 

Table 6-3    VSecCertificateRec Members


Member

Type/Description

useCount

VdkUint2   The usage count for this certificate object.

secModuleId

VdkUint2   An ID that identifies the security module for the gateway. A value of 0 indicates a public repository not requiring authentication, i.e. no security.

repositoryId

VdkUint4   The gateway’s repository ID. The ID must be consistent and valid across collections and document sources for all documents that come from the same gateway’s repository.

prState

VdkUint4   The certificate’s state. The following flags are ORed together to specify the state:

TicketEmpty certificate has not been authenticated

TicketValid certificate is valid

TicketDefault certificate has process context

TicketSysHigh certificate has admin context

TicketSysLow certificate has anonymous context

TicketRefresh certificate has been persisted and needs update

TicketInvalid certificate is not valid

TicketDescriptor certificate is a connection or socket handle of some sort persisted for gateway use

TicketToken certificate is a remote ticket of some sort

TicketSticky certificate is owned by caller and has not been allocated by the security module

TicketCredential certificate is a cached credential set

TicketReserved1 certificate has an application-specific context

TicketReserved2 certificate has an application-specific context;

prSize

VdkUint4   The size, in bytes, of the prData. A value of 0 means that the contents of prData is “in line,” which means prData contains an actual value, not a pointer to a value.

prData

VdkVoidp   A pointer to a gateway-defined structure or data set specific to a certificate’s user context; for example, a user’s group and ID.


 

Table 6-4    VSecArg Members


Member

Type/Description

msgCB

VdkMessageCBFnc   Message callback function.

msgData

VdkCBArg   Data to be passed to the message callback function.

activity

VdkServiceType   Activity that caused the message. Valid values are any combination of the following flags:

VdkServiceType_Unknown No activity

VdkServiceType_Search Retrieval

VdkServiceType_Insert Inserting or updating documents

VdkServiceType_Optimize Optimizing collection

VdkServiceType_Assist Building an assist

VdkServiceType_DBA Database administration

VdkServiceType_Delete Deleting documents

VdkServiceType_Backup Performing backup

VdkServiceType_Repair Repairing collection

VdkServiceType_Purge Purging

Composite activities include the following:

VdkServiceType_Index Inserting, updating or deleting documents

VdkServiceType_DataPrep Retrieval, indexing, optimizing, database administration, or building an assist

appData

VdkVoidp   Reserved for future use.



Returns

This function must return one of the following error codes:

VdkSuccess for success, meaning that the pvsecCert argument points to a valid certificate

 

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 VgwAuthenticateFnc function must determine whether or not the credentials provided by the vsecCred argument are valid. If they are valid, your VgwAuthenticateFnc function fills in a certificate if one has been supplied, or creates a new certificate if not; you must assign the certificate handle to the pvsecCert argument. For information about the structure of a certificate, see VSecCertificateRec Members.

The Verity engine associates the certificate with a user object, which is passed to the following driver callback functions:

VgwDocExist

 

VgwSecurityCheckDocs

 

VgwStreamNew

 

VgwGetSchema

 

VgwDocFieldRead

 

Your implementation of these functions can use the existence of the certificate to allow access to the repository.

Certificates are shared across collections and document sources for the same repository; thus, the Verity engine provides an existing certificate if the user has already been authenticated for a different collection using the same repository.

If authentication fails, your VgwAuthenticateFnc function typically returns VdkError_InvalidUser. Alternatively, you can return VdkSuccess and mark the certificate as invalid. If you return VdkError_Access, the Verity engine calls your VgwAuthenticateFnc function again, which enables the user to present another set of credentials, which is useful in the case where the user inadvertently mistyped a username or password.

You can use the message callback function in the vsecArg argument to log messages related to security. If execution of your VgwAuthenticateFnc function results in an error, you are responsible for freeing any resources used by the objects that you have created before returning from this function.


Example

#define VGW_REPTYPE_NAME "GDK Sample"

static VdkError
VDK_CALLBACK VgwAuthenticate(VSecCredential pCred,
VSecCertificate* ppCert, VSecArg pSecArg)
{
int i = 0;
const char *szUsr = NULL, *szPwd = NULL;
VdkRepository pRep = NULL;
VSecCertificate pCert = NULL;

if( !ppCert || !pCred ||
!pCred->cr_items || (pCred->cr_nitems <= 0) )
return VdkError_InvalidArgs;

/**************************************
* collect user credential information
**************************************/

for( i=0; i<pCred->cr_nitems; i++ ){
switch (pCred->cr_items[i].key_type) {
case USERNAME_KEY:
szUsr = pCred->cr_items[i].key.skey;
break;
case PASSWD_KEY:
szPwd = pCred->cr_items[i].key.skey;
break;
case REPOSITORY_KEY:
pRep = (VdkRepository)pCred->cr_items[i].key.pkey;
break;
}
}
if( !pRep || strcmp(VGW_REPTYPE_NAME,
(const char*)pRep->repository_type_name) ||
!pRep->security_module_id ||
!pRep->repository_name || !pRep->repository_id )
return VdkError_InvalidArgs;

/*****************************************
* create and/or validate VDK certificate
*****************************************/

if (*ppCert) {
if ((*ppCert)->secModuleId != pRep->security_module_id) {
(*ppCert)->secModuleId = pRep->security_module_id;
(*ppCert)->repositoryId = pRep->repository_id;
(*ppCert)->prState |= (TicketSticky | TicketEmpty);
    } else if ((*ppCert)->repositoryId != pRep->repository_id)
(*ppCert)->repositoryId = pRep->repository_id;

} else {
if( !(pCert =
(VSecCertificate)malloc(sizeof(VSecCertificateRec))) )
return VdkError_OutOfMemory;
    memset(pCert, 0, sizeof(VSecCertificate));
    pCert->secModuleId = pRep->security_module_id;
pCert->repositoryId = pRep->repository_id;
pCert->prState |= TicketEmpty;
*ppCert = pCert;
}

/ ****************************************************************
* only allow one user 'abc' with password 'def' to authenticate
****************************************************************/
#define USERID "abc"
#define USERPW "def"

if( !szUsr || strcmp(USERID, szUsr) ||
!szPwd || strcmp(USERPW, szPwd) ){
free(pCert);
return VdkError_InvalidUser;
}

/******************************************************
* store 'abc' user made up uid of some sort to prData
******************************************************/
  #define USERUID ('a'+'b'+'c')

(*ppCert)->prData = (VdkVoidp)USERUID;

(*ppCert)->prState &= ~(TicketInvalid | TicketEmpty);
(*ppCert)->prState |= TicketValid;
return VdkSuccess;
}