/*********************************************************************** * * 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 * ***********************************************************************/ /*********************************************************************** * * 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.