CASA/CASA-auth-token/non-java/client/mech_if.h

/***********************************************************************
 * 
 *  Copyright (C) 2006 Novell, Inc. All Rights Reserved.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, Novell, Inc.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 *  Author: Juan Carlos Luciani <jluciani@novell.com>
 *
 ***********************************************************************/


#ifndef _MECH_IF_H_
#define _MECH_IF_H_


//===[ Include files ]=====================================================

//===[ Type definitions ]==================================================

//===[ Function prototypes ]===============================================

//===[ Global variables ]==================================================

/**************************************************************************
***************************************************************************
**                                                                       **
**    Authentication Mechanism Token Interface Definitions               **
**                                                                       **
***************************************************************************
**************************************************************************/


//++=======================================================================
typedef
int       
(SSCS_CALL *PFNAuthTokenIf_AddReference)(
   IN       const void  *pIfInstance);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
// Returns:
//    Interface reference count.
//                           
// Description:
//    Increases interface reference count.
//=======================================================================--


//++=======================================================================
typedef
void       
(SSCS_CALL *PFNAuthTokenIf_ReleaseReference)(
   IN       const void  *pIfInstance);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
// Returns:
//    Nothing.
//                           
// Description:
//    Decreases interface reference count. The interface is deallocated if
//    the reference count becomes zero.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNAuthTokenIf_GetAuthToken)(
   IN       const void        *pIfInstance,
   IN       const char        *pContext,
   IN       const char        *pMechInfo,
   IN       void              *pCredStoreScope,
   INOUT    char              *pTokenBuf,
   INOUT    int               *pTokenBufLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pContext -
//       Pointer to null terminated string containing mechanism specific
//       context information. Another name for context is Authentication
//       Realm.
//
//    pMechInfo -
//       Pointer to null terminated string containing mechanism specific
//       information. This is information is provided by the server to
//       aid the mechanism to generate an authentication token. For
//       example, the mechanism information for a Kerberos mechanism
//       may be the service principal name to which the user will be
//       authenticating.
//               
//    pCredStoreScope -
//       Pointer to CASA structure for scoping credential store access
//       to specific users. This can only be leveraged when running in
//       the context of System under Windows.
//   
//    pTokenBuf -
//       Pointer to buffer that will receive the authentication
//       token. The length of this buffer is specified by the
//       pTokenBufLen parameter. Note that the the authentication
//       token will be in the form of a NULL terminated string.
//
//    pTokenBufLen -
//       Pointer to integer that contains the length of the
//       buffer pointed at by pTokenBuf. Upon return of the
//       function, the integer will contain the actual length
//       of the authentication token if the function successfully
//       completes or the buffer length required if the function
//       fails because the buffer pointed at by pUserNameBuf is
//       not large enough.
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get authentication token to authenticate user to specified service.
//=======================================================================--


//
// AuthMechToken Interface Object
// 
typedef struct _AuthTokenIf
{
   PFNAuthTokenIf_AddReference         addReference;
   PFNAuthTokenIf_ReleaseReference     releaseReference;
   PFNAuthTokenIf_GetAuthToken         getAuthToken;

} AuthTokenIf, *PAuthTokenIf;


//++=======================================================================
typedef
CasaStatus
(SSCS_CALL *PFN_GetAuthTokenIfRtn)(
   IN       const ConfigIf    *pModuleConfigIf,
   INOUT    AuthTokenIf       **ppAuthTokenIf);
//
// Arguments:  
//    pModuleConfigIf -
//       Pointer to configuration interface instance for the module.
//               
//    ppAuthTokenIf -
//       Pointer to variable that will receive pointer to AuthTokenIf
//       instance.
//
// Returns:
//    Casa Status
//                           
// Description:
//    Gets authentication token interface instance.
//=======================================================================--

#define GET_AUTH_TOKEN_INTERFACE_RTN_SYMBOL  "GetAuthTokenInterface"
#define GET_AUTH_TOKEN_INTERFACE_RTN         GetAuthTokenInterface


#endif // #ifndef _MECH_IF_H_