/***********************************************************************
*
* 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 pam_casaauthtok
*
***********************************************************************/
INTRODUCTION
pam_casaauthtok is a PAM authentication module which can be configured
to validate credentials consisting of CASA Authentication Tokens.
CONFIGURATION
To use pam_casaauthtok as a PAM authentication module for your service,
add the following line to the service's PAM configuration file:
auth required pam_casaauthtok.so
pam_casaauthtok supports the following input parameters:
U - This parameter tells pam_casaauthtok that it must verify that
the username is set to "CasaPrincipal". If the parameter is not
specified then pam_casaauthtok does not check the username.
CLIENT PROGRAMMING NOTES
Clients must specify the same service name when requesting Authentication
Tokens from the CASA Client as the service name specified by the server
when opening a PAM handle.
SERVER PROGRAMMING NOTES
Server applications validating credentials containing CASA Authentication
tokens can obtain the following information about the authenticated identity:
username - This is obtained by querying PAM using the pam_get_item() call with
the item type set to PAM_USER. This can also be obtained by querying PAM
using the pam_getenv() call with the variable name set to "IdentityId". The
username is the user's unique id within the authentication realm. When the
authentication realm is an LDAP database, the username consists of the user's fdn.
Note that PAM applications using pam_casaauthtok need to set username to
"CasaPrincipal" when opening a PAM handle and then the variable is updated by
pam_casaauthtok during the authentication process with the identity information
of the authenticated entity.
Name of the source of identity data (Authentication Realm) - This is obtained
by querying PAM using the pam_getenv() call with the variable name set to
"IdentityDataSourceName".
URL to the source of identity data - This is obtained
by querying PAM using the pam_getenv() call with the variable name set to
"IdentityDataSourceUrl".
Attributes of the authenticated identity - The attributes are set as environment
variables associated with the PAM handle. The environment variable names match
the names of the attributes. The attributes associated with the authenticated
identity and expressed as environment variables are configured at the time that
the service is enabled for CASA Authentication.
EXAMPLE SERVER APPLICATION
See test/test.c for an example application using PAM to authenticate credentials
consisting of CASA Authentication Tokens.
SECURITY CONSIDERATIONS
CASA Authenticatication 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.
