/***********************************************************************
*
* 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_s_authtoken
*
***********************************************************************/
INTRODUCTION
libcasa_s_authtoken provides an API for the validation of CASA Authentication Tokens.
The API provides a means for obtaining identity information about authenticated
entities.
Applications should avoid calling directly into this library's APIs. Instead, applications
should code to the PAM API to validate authentication credentials or allow an external
module to perform the credential validation. To facilitate this, CASA Authentication
provides PAM, Apache, and JAAS modules that can be used to validate credentials containing
CASA Authentication tokens,
libcasa_s_authtoken relies on the CasaAuthtokenValidateD service in order to perform its
functions. To learn more about CasaAuthtokenValidateD see the Svc folder.
CONFIGURING ADDITIONAL IDENTITY TOKEN PROVIDER MODULES
CASA Authentication Tokens contain Identity Tokens. The Identity Tokens contain the identity
information about the entity being authenticated. Identity Tokens can be of different types,
the type utilized for use with a particular service is configured at the time that the service
is configured for CASA Authentication. The default identity token type is CasaIdentityToken.
libcasa_s_authtoken supports different identity token types through an API that allows for the
configuration of different Identity Token Provider plug-ins. An Identity Token Provider plug-in
is configured by placing a configuration file for the plug-ins in the
/etc/CASA/authtoken/modules folder. The name of the plug-in configuration file is related
to the identity token type in the following manner: IdentityTokenTypeName.conf.
Identity Token Provider plug-in configuration files must must contain a directive indicating the
path to the library implementing the Identity Token Provider plug-in (See the configuration file
for the CasaIdentityToken plug-in for an example).
SERVER APPLICATION PROGRAMMING NOTES
The Validate CASA Authentication Token API is defined in casa_s_authtoken.h.
The API consists of a call to validate authentication tokens. The caller must supply a service
name which must match the service name provided by the client when requesting the authentication
token. Successful calls to the validate authentication token API will return a handle to a principal
interface object. The principal interface object handle can be used to obtain identity information
about the authenticated entity as well as information about the authentication realm. The principal
interface object must be released after it is no longer needed. The amount and type of identity
information associated with the principal interface is dependent on what is configured at the
time that the service is enabled for CASA Authentication.
For examples of code which uses the Validate CASA Authentication Token API look at the implementations
of the CASA Authentication PAM module and the CASA Authentication Provider Apache module.
IDENTITY TOKEN PROVIDER PROGRAMMING NOTES
The Identity Token Provider API is defined in iden_token_provider.h.
For an example see the implementation of the CASA Identity Token Provider.
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.
Under Linux, the Validate CASA Authentication Token libraries validate tokens
by invoking a service (casa_atvd, also knon as CasaAuthtokenValidateD). The security of the
communications that happen between the library and the service is dependent on the properties
of the stack providing Unix Domain Sockets communications and the file system rights setup
on the folder where the domain sockets are created.
The SuSE rpm package for this component only allows processes executing as casaatvd
to setup a listener on the /var/lib/CASA/authtoken/validate/ folder but it allows any
process to connect to it. This setup may allow a rogue process to easily launch a
denial of service attack on casa_atvd. If this is not acceptable then change the
rigths on the folder to only allow selected users to connect to it.
