112 lines
5.3 KiB
Plaintext
112 lines
5.3 KiB
Plaintext
/***********************************************************************
|
|
*
|
|
* 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|