/***********************************************************************
 * 
 *  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>
 *
 ***********************************************************************/
/***********************************************************************
 *
 *  README for libcasa_c_authtoken
 *
 ***********************************************************************/

INTRODUCTION

libcasa_c_authtoken is the client auth_token engine. It is responsible for
interacting with ATSs, invoking the authentication mechanism plug-ins, and
managing the authentication token cache. libcasa_c_authtoken also provides
the Get Authentication Token API.

CONFIGURING ADDITIONAL AUTHENTICATION MECHANISM MODULES

libcasa_c_authtoken utilizes mechanism plug-ins for authenticating to ATSs.
The client auth_token package installs mechanisms for the support of Kerberos5
and Username/Password authentication. To configure additional authentication mechanism
plug-ins, place their configuration file in the folder for CASA Authentication Token module
configuration. The path to this folder under linux is /etc/CASA/authtoken.d/client.d/mechanisms.d/.
The path to this folder under Windows is \Program Files\novell\CASA\Etc\Auth\Mechanisms\. The name of
the plug-in configuration file is related to the authentication mechanism type in the following
manner: AuthenticationMechanismTypeName.conf.

Authentication Mechanism plug-in configuration files must must contain a directive indicating the
path to the library implementing the Authentication Mechanism (See the configuration file
for the Kr5Authenticate plug-in for an example).

CLIENT APPLICATION PROGRAMMING NOTES

The Get CASA Authentication Token API is defined in casa_c_authtoken.h.

The API consists of a call to obtain authentication tokens. The caller must supply the name of the
service to which it wants to authenticate along with the name of the host where it resides. The
returned authentication token is a Base64 encoded string.

Applications utilizing CASA Authentication Tokens as passwords in protocols that require the
transfer of user name and password credentials should verify or remove any password length limits
as the length of CASA Authentication Tokens may be over 1K bytes. The size of the CASA Authentication
Tokens is directly dependent on the amount of identity information configured as required by the
consuming service. These applications should also set the user name to "CasaPrincipal".

For examples of code which uses the Get CASA Authentication Token API look at the test application
under the test folder.

AUTHENTICATION MECHANISM PROGRAMMING NOTES

The Authentication Mechanism API is defined in mech_if.h.

For example implementations see the code for the krb5 and the pwd mechanisms.

SECURITY CONSIDERATIONS

CASA Authentication Tokens when compromised can be used to either impersonate
a user or to obtain identity information about the user. Because of this it is
important that the tokens be secured by applications making use of them. It is
recommended that the tokens be transmitted using SSL.