Kerberos authentication for AIX Version 5.3 Network File System Version 4

Obtaining credentials and writing custom APIs

Find out how to use application programming interfaces (APIs) when writing your own custom Kerberos-based authentication applications. Network File System Version 4 (NFS V4), the up and coming enterprise file system, uses the Kerberos security mechanism to address privacy, authentication, and integrity requirements. In this article, you'll examine different Kerberos credential cache name formats that AIX® NFS V4 supports and are required for authentication purposes. You'll also look at different methods of obtaining the Kerberos credential.

Share:

Brian McCorkle (brianmc1@us.ibm.com), Senior Software Engineer, IBM

Brian McCorkle is a Senior Software Engineer for IBM. He has worked for IBM for the past seven years, focusing on AIX core features, AIX Linux compatibility, and AIX NFS development. He is currently implementing RAS features in AIX NFS. Brian holds a Bachelor of Arts in computer science from the University of Texas in Austin, Texas. You can contact him at brianmc1@us.ibm.com.



Sandeep Patil (rsandeep@in.ibm.com), Staff Software Engineer, EMC

Sandeep Patil photoSandeep Ramesh Patil works as an Advisory Software Engineer for the IBM India Software Labs. He has worked for IBM for the past six years, focusing on distributed technology including DCE, SARPC, and security products, such as the IBM Network Authentication Service (IBM Kerberos). He is currently developing new features and implementing security-related RFC for the IBM Network Authentication Service, along with its product support. Sandeep holds a Bachelor of Engineering degree in computer science from the University of Pune, India. You can contact him at rsandeep@in.ibm.com.


developerWorks Master author
        level

05 December 2006

Introduction

Network File System Version 4 (NFS V4) is clearly being considered as the next-generation distributed file system. Legacy distributed file systems, such as IBM Distributed File System™ (DFS™) and Andrew File System (AFS), are coming to an end of life, and NFS V4 is emerging as the upcoming enterprise file system. Administrators have already started migrating to NFS V4. IBM released its implementation of NFS V4 with the AIX 5L™ Version 5.3.

Security in NFS V4 is one of the most important enhancements from earlier versions. AIX® NFS V4 currently uses the Kerberos security mechanism to address the security-related requirements of privacy, authentication, and integrity.

This article discusses different Kerberos credential cache name formats that are supported by AIX NFS V4 and are required for authentication purposes. We'll cover the various methods that can be used by administrators or NFS V4 users to obtain the Kerberos ticket in the credential cache format supported by AIX NFS V4. We'll also describe some of the important IBM Network Authentication Service (IBM NAS) and AIX application programming interfaces (APIs) that developers need to consider when developing custom authentication applications for AIX NFS V4.


AIX 5L Version 5.3, NFS V4, and Kerberos authentication credentials

AIX NFS V4 currently uses the Kerberos security mechanism as one of its prime authentication protocols. It makes use of IBM NAS for the required Kerberos services. IBM NAS for AIX is IBM's offering for Kerberos shipped with the AIX 5L Version 5.3 Expansion Pack CD, and it is one of the prerequisite installation modules for AIX NFS V4 with Kerberos authentication. Along with IBM NAS, the Cryptographic Library fileset (modcrypt package) shipped with the AIX 5L V5.3 Expansion Pack CD is also a prerequisite installation component. For details about AIX NFS V4 authentication and other security features, refer to the IBM Redbook Securing NFS in AIX: An Introduction to NFS Version 4 in AIX 5L Version 5.3 (see Resources).

There are various ways to obtain the Kerberos credentials for AIX NFS V4 authentication. Some of the methods are:

  • Using the kinit Kerberos commands that are available with IBM NAS.
  • Configuring AIX Integrated Login for Kerberos.
  • Writing a custom made Kerberos authentication program using the Kerberos APIs exported by IBM NAS and the system API's provided by AIX.

We'll discuss all of these approaches in this article, but first we'll briefly review AIX NFS V4 and its supported Kerberos credentials cache formats.

The AIX NFS V4 file system supports two types of Kerberos credential cache name formats. It is important to understand these two types of formats, especially if you plan to have your own custom authentication applications for your solutions.

Process Authentication Group (PAG)-based Kerberos credential cache name
For PAG-based credentials, the Kerberos credentials cache file name is of the format /var/krb5/security/creds/krb5cc_x[PAG], where [PAG] is a 64-bit unique hexadecimal number generated from the operating system service. This is generally used when you want to have the credentials cache file that is unique to a process.

PAGs are data items that associate user-authentication data with processes. A PAG can be described as a numeric token that represents an external extended attribute for the credential. The PAG mechanism has its origins in the AFS and DFS file system technologies, and it is now adopted in AIX NFS V4. AIX provides a set of user- and kernel-level services to manipulate and access PAG information. It provides a list of PAG commands and APIs that assist you when developing custom AIX NFS V4 authentication applications. IBM NAS also provides commands that generate Kerberos credentials that are PAG-based. More on this later.

User ID- (UID) based Kerberos credential cache name
For UID-based credentials, the Kerberos credentials cache file name is of the format /var/krb5/security/creds/krb5cc_[UID], where [UID] is the local user ID number of the user. AIX provides APIs that allow an application to retrieve the UID of the users. IBM NAS also provides commands that generate UID-based Kerberos credentials. Creating UID-based credentials is the default behavior of these commands. The rest of this article provides more information on ways to obtain a ticket with credential cache based on UID.

In the current version of AIX 5L Version 5.3 NFS V4, if the PAG value is set for the "krb5" PAG name, then the file system looks first for the PAG-based Kerberos credential cache file name. Then it looks for the UID-based credential cache file name in the /var/krb5/security/creds directory.

AIX 5L Version 5.3 NFS V4 only identifies the Kerberos credentials cache files stored in the /var/krb5/security/creds directory. For your AIX NFS V4-based solution, make sure you follow one of the two naming conventions discussed above if you intend to create your own Kerberos credential cache file, and make sure you store the credential cache file in /var/krb5/security/creds directory.


Kerberos authentication using IBM NAS command

IBM NAS ships with the standard Kerberos command kinit, which is basically used to obtain or renew a ticket-granting ticket. The default behavior of the IBM NAS kinit command for the AIX operating system is to create a UID-based credential cache stored under the /var/krb5/security/creds directory. From IBM NAS Version 1.4 onwards, the kinit command is enhanced to generate PAG-based credential cache. kinit now supports the new flag, -u, which specifies that kinit will create a credentials cache file that is unique to a process. This credentials cache file name includes a unique number (PAG), which on AIX 5L Version 5.3 and later is generated from an operating system service. For detailed information on kinit, see the IBM NAS 1.4 Administrator's and User's Guide shipped with the IBM NAS 1.4 product on the AIX 5L Version 5.3 Expansion Pack CD.

Listing 1 below shows how to obtain the UID as well as PAG-based credentials using the IBM NAS Version 1.4 kinit command on AIX.

Listing 1. Obtaining UID and PAG-based credentials
# oslevel
5.3.0.0
# /usr/krb5/bin/kinit admin/admin
Password for admin/admin@TEST:
# /usr/krb5/bin/klist
Ticket cache:  FILE:/var/krb5/security/creds/krb5cc_0
Default principal:  admin/admin@TEST

Valid starting     Expires            Service principal
10/03/06 19:39:03  10/04/06 19:38:58  krbtgt/TEST@TEST
#
# /usr/krb5/bin/kdestroy
#
# /usr/krb5/bin/kinit -u admin/admin
Password for admin/admin@TEST:
[root@fsaix11 / ]# klist
Ticket cache:  FILE:/var/krb5/security/creds/krb5cc_x0000000000000001
Default principal:  admin/admin@TEST

Valid starting     Expires            Service principal
10/03/06 19:39:42  10/04/06 19:39:39  krbtgt/TEST@TEST
#

Kerberos authentication using AIX 5L Version 5.3 integrated login

IBM AIX 5L Version 5.3 provides Kerberos integrated login, wherein once the users log in to the system they automatically acquire the Kerberos credentials, which they can use to access AIX NFS V4 space. The AIX 5L Version 5.3 Kerberos Integrated Login currently creates a PAG-based credential cache.

To learn more about AIX Kerberos Integrated Login and its configuration, refer to the AIX white paper Configuring AIX 5L for Kerberos Based Authentication Using Network Authentication Service (see Resources).


Kerberos authentication using IBM NAS and AIX APIs

Customer-driven requirements and customer-specific solutions often give rise to scenarios where it is desirable to have custom made Kerberos authentication applications. For developing such applications, which potentially can be integrated in solutions comprising AIX NFS V4, it is important to understand the Kerberos credential cache name format supported by AIX NFS V4 and the Kerberos and AIX APIs that help in implementation.

Depending on the requirement, you can either choose to use the UID-based credentials cache, which is common to all processes for a given user, or a PAG-based credential cache unique to a process. Likewise, either you'll need to make use of the UID-based AIX APIs or the PAG-based AIX APIs to form the credential cache file that store the Kerberos credentials. The next section lists a few of the APIs that you might find handy.

IBM NAS APIs

IBM NAS 1.4 exports a set of krb5_xxx() APIs that you can use for writing kerberized applications. For Kerberos authentication and storing the credentials in the credential cache file that is understandable by AIX 5L Version 5.3 NFS V4, you can use the following important Kerberos APIs.

krb5_error_code krb5_cc_resolve ( krb5_context context, const char * name, krb5_ccache * 
   ccache)

The krb5_cc_resolve subroutine resolves a credentials cache name and returns a handle that can be used to access and populate the cache. This API is required to resolve the credential cache name in which you need to store the acquired Kerberos credentials. It is important to understand that in order for the credential cache to be recognized by AIX 5L Version 5.3 NFS V4, the second input parameter for the krb5_cc_resolve subroutine that is the credential cache name should resemble one of the following formats:

  • FILE:/var/krb5/security/creds/krb5cc_x[PAG]
  • FILE:/var/krb5/security/creds/krb5cc_[UID]
krb5_error_code krb5_id_to_ccache_np( krb5_context context, uint64_t id, 
krb5_context_id_type type, krb5_principal principal, krb5_ccache *ccache)

The krb5_id_to_ccache_np subroutine converts an ID (a UID or a PAG) to a krb5_ccache structure. Implementation with the krb5_cc_resolve subroutine is more generic but, if you prefer to be very specific, you can choose to use the new krb5_id_to_ccache_np Kerberos API exported by IBM NAS 1.4. Given a UID or PAG, this API converts to an appropriate krb5_ccache structure that is understandable by AIX 5L Version 5.3 NFS V4, and it can be used to store the acquired credentials.

krb5_error_code krb5_get_init_creds_password( krb5_context context, krb5_creds * creds, 
krb5_principal client, char * password, krb5_prompter_fct prompter, void * prompter_data, 
krb5_deltat start_time, char * in_tkt_service, krb5_get_init_creds_opt * options

This code obtains an initial ticket using a text password, and it allows changing an expired password. You can choose to use the krb5_get_init_creds_password subroutine to acquire an initial ticket using a text password, which then can be used to obtain the service ticket for the AIX 5L Version 5.3 NFS V4 server.

For details on these IBM NAS APIs and a list of other Kerberos APIs exported by IBM NAS, refer to the IBM Network Authentication Service Version 1.4 Application Development Reference guide shipped on the AIX 5L Version 5.3 Expansion Pack CD.

AIX UID-related API

If you choose to create a UID-based Kerberos credential cache (/var/krb5/security/creds/krb5cc_[UID]), then you can use the following AIX base operating system exported API to get the real user ID that is required while constructing the UID-based Kerberos credential cache file name.

uid_t getuid(void)

The getuid subroutine returns the real user ID of the current process.

For details on the UID-related APIs exported by AIX, refer to AIX Technical Reference: Base Operating System and Extensions, Volume 2 (see Resources).

AIX PAG-related APIs

If you choose to have a Kerberos credential cache file unique to a process (for example, to have a PAG-based credential cache file with the format /var/krb5/security/creds/krb5cc_x[PAG] ), then you need to be aware of the PAG-related APIs exported by the AIX base operating system that are listed below.

AIX supports 32-bit and 64-bit PAGs, and the PAG spaces are different for each of them. AIX NFS V4 makes use of only 64-bit PAGs, hence you have to use only 64-bit PAGs while programming for AIX NFS V4. Another key point is that "krb5" is the PAG name that is associated with Kerberos on AIX, which AIX NFS V4 makes use of. krb5 is the PAG registered in the AIX system when IBM NAS 1.4 is successfully configured.

int  genpagvalue(pag_name, pag_value,pag_flags);
char *       pag_name;
uint64_t *   pag_value;
int           pag_flags;

The genpagvalue subroutine generates a new PAG value for a given PAG name. For this function to succeed, the PAG name must be registered with the operating system before calling the genpagvalue subroutine. krb5 is the PAG name that you need to use for AIX NFS V4.

int setpagvalue ( name, value )
char * name;
int  value;
					
uint64_t setpagvalue64( name, value );
char * name;
uint64  value;

The setpagvalue or setpagvalue64 subroutines set the PAG value for a given PAG name. For these functions to succeed, the PAG name must be registered with the operating system before these subroutines are called. krb5 is the PAG name that you need to use for AIX NFS V4.

int getpagvalue ( name )
char * name;
					
uint64_t getpagvalue64( name );
char * name;

The getpagvalue or getpagvalue64 subroutines retrieve the PAG value for a given PAG name. For these functions to succeed, the PAG name must be registered with the operating system before these subroutines are called. krb5 is the PAG name that you need to use for AIX NFS V4.

For detail information about these subroutines, refer to AIX Technical Reference: Base Operating System and Extensions, Volume 2, (see Resources).

You typically need to follow the functional flow in Listing 2 below in order to obtain the Kerberos ticket in the PAG-based credential cache file so that it can be used for AIX 5L Version 5.3 NFS V4 access. More importantly, note the sequence of the AIX PAG-based APIs.

Listing 2. Functional flow
{
...
...

genpagvalue(...)     /* generate a unique PAG value for "krb5" PAG name*/

...
...

krb5_cc_resolve(...) /* Use the PAG value obtained above and form the PAG based 
                     * credential cache file name of the format 
                     * /var/krb5/security/creds/krb5cc_x[PAG]
                     * and resolve the credential cache name for further use. 
                       */
OR

krb5_id_to_ccache_np(...) /* Directly create PAG based credential cache name using the 
                           * PAG value obtained above for further use
                           */
...
...

krb5_get_init_creds_password(...)  /* Obtain the initial ticket using the plain 
                           *password
                            */

...
...

krb5_cc_initialize(...)  /* Initialize the above resolved PAG based credential cache */
...
krb5_cc_store_cred(...)  /* Store the credentials obtained in the PAG based credential 
                                 *cache
                                  */

...
...

setpagvalue64(...)  /* If all of the above was successful, set the PAG value for 'krb5' 
                             * PAG name
                               */

...
...
}

It is recommended that, on successfully obtaining the Kerberos credential, you set the KRB5CCNAME environment variable to point to the credential cache file name. You need to set the environment variable to either FILE:/var/krb5/security/creds/krb5cc_x[PAG] or FILE:/var/krb5/security/creds/krb5cc_[UID], depending on what format you've chosen.

The code snippet in Listing 2 does not mention the entire required sequence of Kerberos API calls. To learn more on the Kerberos APIs, refer to the IBM Network Authentication Service Version 1.4 Application Development Reference guide shipped on the AIX 5L Version 5.3 Expansion Pack CD and the sample Kerberos example programs bundled with the IBM NAS product.


Summary

In this article, you learned how AIX 5L Version 5.3 NFS V4 deals with Kerberos credential cache. We discussed various methods of obtaining the Kerberos credential and reviewed the list of APIs that you need to understand if you intend to write your own custom Kerberos-based authentication applications for AIX 5L Version 5.3 NFS V4.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into AIX and Unix on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=AIX and UNIX
ArticleID=181833
ArticleTitle=Kerberos authentication for AIX Version 5.3 Network File System Version 4
publish-date=12052006