IBM Java^TM Generic Security Service API (JGSS) 5.0

User's Guide

Contents

1. IBM JavaTM Generic Security Service API (JGSS) 5.0
2. User's Guide
   1. Contents
   2. Copyright information
   3. Introduction
   4. Concepts
      1. Principals and Credentials
      2. Context Establishment
      3. Message Protection and Exchange
      4. Cleanup
   5. JCE Provider
   6. Supported Encryption Types
   7. Supported Checksum Types
   8. Kerberos Credentials Acquisition and Management
   9. JAAS Login
      1. 1. Option Name
         2. Value
         3. Default
         4. Explanation
   10. JAAS Authorization Checks
       1. JVM Permissions
   11. Configuration and Policy Files
       1. Kerberos Configuration File
       2. JAAS Configuration File
       3. JAAS Authorization Policy File
   12. Credential Caches
       1. User Credentials Cache
       2. Server Key Table
   13. Debugging
   14. Some JGSS Used Java Properties
   15. Some JGSS Used Files
   16. Packages
   17. Notices
       1. Trademarks

Copyright information

Note: Before using this information and the product it supports, be sure to read the general information under Notices.

This edition of the User Guide applies to the IBM 32-bit SDK, Java 2 Technology Edition, Version 5.0, and to all subsequent releases and modifications until otherwise indicated in new editions.

(c) Copyright Sun Microsystems, Inc. 1998, 2004, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.

(c) Copyright International Business Machines Corporation, 1998, 2005. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Introduction

IBM JGSS 5.0 is a Java Generic Security Service Application Programming Interface (GSSAPI) framework with Kerberos V5 as the underlying default security mechanism. GSSAPI is a standardized abstract interface under which can be plugged different security mechanisms based on private-key, public-key and other security technologies. GSSAPI shields secure applications from the complexities and peculiarities of the different underlying security mechanisms. GSSAPI provides identity and message origin authentication, message integrity and message confidentiality.

Leveraging the Java Cryptographic Provider Architecture, IBM JGSS offers seamless pluggability of different security systems. IBM JGSS 5.0 also features optional Java Authentication and Authorization Service (JAAS) Kerberos login interface and authorization checks. JAAS augments the access control features of Java, 2 which is based on CodeSource with access controls based on authenticated principal identities.

JGSS is now integrated into Java 5.0.

Concepts

The operational paradigm of the GSSAPI consists of four distinct phases: gathering of credentials for principals, creation and establishment of security context between the communicating peer principals, secure message exchange between the peers and, when it's all over, cleanup and release of resources. This section provides a high-level description of these important traditional GSSAPI concepts. The JAAS features are also described in this section.

Principals and Credentials

The identity under which an application engages in JGSS secure communication with a peer is called principal. A principal can be a real user or an unattended service. A principal acquires security mechanism-specific credentials as proof of identity under that mechanism. For example, when using the Kerberos mechanism, a principal's credential is in the form of a ticket granting ticket (TGT) issued by a Kerberos key distribution center (KDC). In a multi-mechanism environment, a GSSAPI credential can contain multiple credential elements, with each element representing an underlying mechanism credential.

The GSSAPI standard does not prescribe how a principal acquires credentials, and GSSAPI implementations typically do not provide a means for credentials acquisition. A principal obtains credentials before using GSSAPI; GSSAPI merely queries the security mechanism for credentials on behalf of the principal.

IBM JGSS provides Java versions of the traditional Kerberos credential management tools kinit, ktab and klist. Moreover, using JAAS, IBM JGSS enhances standard, traditional GSSAPI with an optional Kerberos login interface. This interface is one of the JAAS Features provided by IBM JGSS.

Context Establishment

Having acquired security credentials, the two communicating peers establish a security context using their credentials. Conceptually, a single, joint context is established, but each peer maintains a local copy of the context in its JGSS runtime. Context establishment involves the initiating peer authenticating itself to the accepting peer. The initiator can optionally request mutual authentication, in which case the acceptor in turn authenticates itself to the initiator.

When context establishment is complete, the established context embodies state information such as shared cryptographic keys that enable subsequent secure message exchange between the two peers.

Message Protection and Exchange

Following context establishment, the two peers are ready to engage in secure message exchanges. The originator of the message calls on its local GSSAPI runtime to apply data origin authentication and integrity, and optionally, confidentiality protection to the message. The application then transports the resulting token to the peer whose local GSSAPI runtime uses information from the established context to verify the integrity of the message, and to decipher the message if the message was encrypted.

Cleanup

When no longer needed, a context is deleted to free up resources. Although a deleted context is accessible in the JGSS runtime, any attempt to use it for message exchanges will result in an exception.

JCE Provider

IBM JGSS uses cryptographic and other security services provided by the IBM JCE Provider. com.ibm.crypto.provider.IBMJCE must be listed as a security provider in the java.security file which is typically located in the <jdk>/jre/lib/security directory of Java JDK installations.

Supported Encryption Types

Kerberos uses a number of encryption systems for data protection. These are based on the Data Encryption Standard (DES) in Cipher Block Chaining (CBC) mode with a checksum for integrity. A DES key is 8 bytes long with 1 parity bit from each byte making an effective key length of 56 bits. DES in CBC mode requires an initialization vector. Kerberos uses an 8-byte zero initialization vector.

Kerberos also uses the Triple-DES encryption system in Outer-CBC mode with a Secure Hash Algorithm (HMAC SHA-1) checksum. A Triple-DES key is a concatenation of three DES keys and is therefore 168 bits long.

IBM JGSS supports the use of DES and Triple-DES encryption systems as defined in Kerberos RFC-1510 and rfc3961.txt. IBM JGSS also supports the RC4 HMAC encryption system used in Microsoft Windows and Active Directory products. RC4 HMAC is defined in draft-brezak-win2k-krb-rc4-hmac-04.txt (Expired).

A client specifies a list of desired encryption systems as the value of the default_tkt_enctypes and default_tgs_enctypes fields in their Kerberos configuration file. The possible values and their meanings are as follows:

• des3-cbc-sha1 - Represents Triple-DES in CBC mode with SHA1 checksum. This encryption system uses key derivation, that is, different keys are derived from a base key for specific uses.
• des-cbc-md5 - Represents DES in CBC mode with MD5 checksum.
• des-cbc-crc - Represents DES in CBC mode with a 4-byte CRC-32 checksum.
• rc4-hmac - Represents Rivest Cipher 4 (RC4) encryption with an MD5 HMAC checksum; uses key derivation with key usage numbers that sometimes differ from those used in the des3-cbc-sha1 encryption system.
• rc4-hmac-exp - Identical to rc4-hmac with a reduced key length.

Supported Checksum Types

IBM JGSS supports the checksum algorithms defined in RFC-1510 and rfc3961.txt. It also supports the checksum algorithm hmac-md5 defined in draft-brezak-win2k-krb-rc4-hmac-04.txt (Expired)  for use with the rc4-hmac and rc4-hmac-exp encryption systems. A client specifies a desired checksum algorithm as the value of the default_checksum field in their Kerberos configuration file. Here are the possible values with brief descriptions:

• hmac-sha1-des3 - The checksum used with the des3-cbc-hmac-sha1 encryption system. A key is derived from a base key using the defined usage number for checksum. The derived key is then used to compute an HMAC SHA1 hash over the data to be checksumed. The result is a 20-byte checksum.
• rsa-md5-des - Combines the RSA MD5 checksum algorithm with DES CBC encryption to generate a 24-byte keyed checksum which is believed to be tamper-proof and collision-proof. It is used with the des-cbc-md5, des-cbc-md4 and des-cbc-crc encryption systems.
• des-mac - Uses DES in CBC mode to generate a 16-byte checksum 64 bits of which are redundant. The checksum is believed to be both collision-proof and tamper-proof. Associated encryption systems are des-cbc-md5, des-cbc-md4 and des-cbc-crc.
• hmac-md5 - The checksum used with the rc4-hmac and rc4-hmac-exp encryption systems. It is essentially an HMAC hash over the ASCII string "signaturekey" (including the terminating null), a usage number and the data to be checksumed.

The following checksum types are supported but not recommended for use as stated below:

• des-mac-k - Uses DES in CBC mode to create an 8-byte checksum. Although the resulting checksum is both tamper-proof and collision-proof, this algorithm is the obsolete way of computing des-mac checksum and its use is no longer recommended.
• rsa-md5 - Uses the RSA MD5 checksum algorithm to generate a 16-byte digest over the data to be checksumed. It is believed to be collision-proof, but is not keyed and its use is not recommended.
• crc32 - Generates a 4-byte cyclic redundancy check (CRC-32) checksum. The checksum is neither keyed nor collision-proof and its use is not recommended.

Kerberos Credentials Acquisition and Management

A Kerberos ticket-granting ticket (TGT) can be obtained using the Java Kinit tool provided by JGSS. A server may create a secret key using the supplied Java™ Ktab tool. In addition, the supplied Java Klist tool can be used to view credential caches and key tables. These tools use command-line interfaces and provide options similar to those offered by traditional versions. For ease of use, each tool comes in the IBM SDK with a corresponding executable in the SDK's bin directory. This SDK enables a tool to be invoked without entering its full package name on the command line.

Alternatively, Kerberos TGTs and secret keys can be obtained through the JAAS Login interface described below.

JAAS Login

IBM JGSS features a JAAS Kerberos login interface. This feature is optional and may be disabled by setting the Java property javax.security.auth. useSubjectCredsOnly to false.

The login interface requires a JAAS configuration file that specifies com.ibm.security.auth.module.Krb5LoginModule as the login module to be used. The options are listed in the table below.

Option Name	Value	Default	Explanation
credsType	initiator|acceptor|both	initiator	JGSS credential type
debug	true|false	false	Turns debug on/off in login module
forwardable	true|false	false	Whether to acquire a forwardable TGT
moduleBanner	true|false	false	Display login module banner
noAddress	true|false	false	Don't include address in ticket granting ticket
principal	<string>	No default	Kerberos principal name
proxiable	true|false	false	Whether to acquire a proxiable TGT
tryFirstPass	true|false	false	Try password saved in shared state
useCcache	<URL>	Don't use cred cache	Retrieve TGT from the specified credential cache
useDefaultCcache	true|false	false	Retrieve TGT from the default credential cache
useDefaultKeytab	true|false	false	Retrieve the secret key from the specified key table
useFirstPass	true|false	false	Use the password saved in shared state
useKeytab	<URL>	Don't use key table	Retrieve the secret key from the specified key table

The principal, debug and moduleBanner options can be specified in combination with any other option. If not specified, the principal name will prompted for depending on the values of other options that are specified. Some of the remaining options are incompatible with each other and cannot be specified together. The cells marked X in the table below show which two options are incompatible with each other. The cells marked N show inapplicable combinations.

	credsType			forward	proxy	useCcache	useKeytab	useDefaultCcache	useDefaultKeytab
	init	accept	both
credsType=initiator		N	N				X		X
credsType=acceptor	N		N	X	X	X		X
credsType=both	N	N
forwardable		X				X	X	X	X
proxiable		X				X	X	X	X
useCcache		X		X	X		X	X	X
useKeytab	X			X	X	X		X	X
useDefaultCcache		X		X	X	X	X		X
useDefaultKeytab	X			X	X	X	X	X
noAddress		X				X	X	X	X
useFirstPass						X	X	X	X
renewTGT	X					X	X	X	X

All parts of a multi-part principal name must be specified. For example, "secure/ibm.com@IBM.COM". If omitted, the realm name is obtained from the Kerberos configuration file.

JAAS requires strings containing characters such as '_' (underscore), ':' (colon), '/' (forward slash), and '\' (back slash) that might be construed as delimiters to be quoted.

Krb5LoginModule might prompt for a principal name, password or both. Or it might not prompt for any input whatsoever. Whether or not the login is interactive depends on the options specified in the JAAS configuration file. For example, the login proceeds non-interactively when the credential type is initiator and a Kerberos TGT is to be retrieved from a credentials cache file. On the other hand, a user is prompted for a password (and, perhaps, a principal name) when a TGT is to be obtained from a Kerberos KDC. When the login is interactive, the application must specify com.ibm.security.auth.callback.Krb5CallbackHandler as the callback handler when creating the login context. The callback handler is responsible for prompting for input.

When credential type both is required, Krb5LoginModule obtains both a TGT (for initiating contexts) and a secret key (for accepting contexts). There must be sufficient information in the JAAS configuration file for the two types of credentials to be acquired. Recall that only principal name and password can be prompted for.

For credential types accept and both, the login module assumes a service principal.

JAAS Authorization Checks

IBM JGSS performs runtime authorization checks on the use of credentials and access to services. Just like the login feature, this JAAS feature is optional and can be disabled by setting the Java™ property javax.security.auth.useSubjectCredsOnly to false. Moreover, the application must be running with a security manager for the authorization checks to be performed.

Authorization checks are made against the authorization policy that is in effect for the current access control context. When using the default policy implementation, JAAS permissions are accorded entities by recording such permissions in a policy file. The specific checks performed by JGSS are javax.security.auth.kerberos.DelegationPermission and javax.security.auth.kerberos.ServicePermission checks.

The DelegationPermission checks restrict the use of delegated credentials. In particular, a principal that is delegating its TGT must have been granted a DelegationPermission that specifies the receiving service and the backend service with which the receiver will be communicating using the delegated TGT. For example, in order for the principal foo@SECURITYCENTRAL.TIVOLI.COM to delegate its TGT for use by the principal superSecureServer/securityCentral.tivoli.com@SECURITYCENTRAL.TIVOLI.COM">superSecureServer/securityCentral.tivoli.com@SECURITYCENTRAL.TIVOLI.COM and for it to acquire a service ticket from the Ticket-Granting Service (TGS) on behalf of foo, the JAAS policy applicable to foo must grant foo a DelegationPermission that specifies superSecureServer and the TGS. The file-based policy for foo will be like the one below.

 grantcodeBase "file:./fooJgssClient.jar", 

 Principal javax.security.auth.kerberos.KerberosPrincipal "foo@SECURITYCENTRAL.TIVOLI.COM" {

 // 1. Authorize foo to delegate its TGT to superSecureServer

 permission javax.security.auth.kerberos.DelegationPermission

 "\"superSecureServer/securityCentral.tivoli.com@SECURITYCENTRAL.TIVOLI.COM\"

 \"krbtgt/SECURITYCENTRAL.TIVOLI.COM@SECURITYCENTRAL.TIVOLI.COM\"";

 // 2. Authorize foo to acquire a TGT from its KDC

 permission javax.security.auth.kerberos.ServicePermission

 "krbtgt/SECURITYCENTRAL.TIVOLI.COM@SECURITYCENTRAL.TIVOLI.COM", "initiate";

 // 3. Grant foo permission to initiate context with superSecureServer

 permission javax.security.auth.kerberos.ServicePermission

 "superSecureServer/securityCentral.tivoli.com@SECURITYCENTRAL.TIVOLI.COM", "initiate";

 };

The ServicePermission checks restrict the use of credentials for context initiation and acceptance. A context initiator must have permission to initiate a context. Likewise, a context acceptor must have permission to accept a context. See foo's configuration file (above) for examples.

JVM Permissions

In addition to the access control checks performed by JGSS, the Java Virtual Machine (JVM) performs authorization checks on access to numerous resources including files, Java™ properties, packages, Subject and sockets. Some of the permissions required when using the JAAS features of JGSS and or running with a Security Manager are listed below:

• javax.security.auth.AuthPermission "modifyPrincipals"
• javax.security.auth.AuthPermission "modifyPrivateCredentials"
• javax.security.auth.AuthPermission "getSubject"
• javax.security.auth.PrivateCredentialPermission "javax.security.auth.kerberos.KerberosKey javax.security.auth.kerberos.KerberosPrincipal \"*\"", "read"
• javax.security.auth.PrivateCredentialPermission "javax.security.auth.kerberos.KerberosTicket javax.security.auth.kerberos.KerberosPrincipal \"*\"", "read"
• java.util.PropertyPermission "com.ibm.security.jgss.debug", "read"
• java.util.PropertyPermission "DEBUG", "read"
• java.util.PropertyPermission "java.home", "read"
• java.util.PropertyPermission "java.security.krb5.conf", "read"
• java.util.PropertyPermission "java.security.krb5.kdc", "read"
• java.util.PropertyPermission "java.security.krb5.realm", "read"
• java.util.PropertyPermission "javax.security.auth.useSubjectCredsOnly","read"
• java.util.PropertyPermission "user.dir", "read"
• java.util.PropertyPermission "user.home", "read"
• java.lang.RuntimePermission "accessClassInPackage.sun.security.action"
• java.security.SecurityPermission "putProviderProperty.IBMJGSSProvider"

Configuration and Policy Files

Kerberos Configuration File

IBM JGSS requires a Kerberos configuration file. The default name and location of the Kerberos configuration file depends on the operating system being used. The default configuration file is searched for in the following order:

• The file referenced by the Java property java.security.krb5.conf
• <java.home>/lib/security/krb5.conf
• c:\winnt\krb5.ini on Microsoft Windows™ platforms
• /etc/krb5/krb5.conf on Unix platforms
• /etc/krb5.conf on Linux platforms

JAAS Configuration File

The use of the JAAS login feature requires a JAAS configuration file. This file can be specified either as the value of the Java™ property java.security.auth.login.config or as the value of the property login.config.url.<n> in the <jdk>/jre/lib/security/java.security file. Consult your JAAS documentation for further details.

JAAS Authorization Policy File

When using the default policy implementation, JAAS permissions are granted to entities by recording the permissions in a policy file. The policy file can be specified either as the value of the Java™ property java.security.policy or as the value of the property policy.url.<n> in the <jdk>/lib/security/java.security file. See your JAAS documentation for further details.

• Java Master Security Properties File

Many important security properties used in a Java Virtual Machine (JVM) are set in the java.security file usually located in the <jdk>/jre/lib/security directory. Some of the relevant properties that can be set in this master security properties file are:

• security.provider.<n>: for statically registering cryptographic provider classes. The security list must include com.ibm.crypto.provider.IBMJCE
• policy.provider: CodeSource-based authorization policy object class, for example

 policy.provider=sun.security.provider.PolicyFile

 policy.url.1=file:c:/ibmjgss/sample/jgss/config/java.policy

 login.configuration.provider=com.ibm.security.auth.login.ConfigFile

 login.config.url.1=file:c:/ibmjgss/sample/jgss/config/jaas.conf

Credential Caches

User Credentials Cache

The user credentials cache is located in the following order:

• The file referenced by the Java property KRB5CCNAME
• <user.home>/krb5cc_<user.name>
• <user.home>/krb5cc (if <user.name> cannot be obtained)

Server Key Table

The server key table file is searched for in following order:

• The value of the Java™ property KRB5_KTNAME
• default_keytab_name entry in the libdefaults stanza of the Kerberos configuration file
• <user.home>/krb5_keytab

Debugging

IBM JGSS has debug capability that can be turned on to obtain debug information. The information is categorized and desired categories can be turned on by setting the Java™ property com.ibm.security.jgss.debug to the appropriate values. See the Java™ documentation of the com.ibm.security.jgss.Debug for details.

Some JGSS Used Java Properties

Property	Notes
java.security.krb5.conf	Kerberos configuration file
javax.security.auth.useSubjectCredsOnly	True by default. Set to false to turn off JGSS JAAS
java.security.auth.login.conf	JAAS login configuration file
java.security.policy	JAAS authorization policy file
java.security.manager	Security Manager to be used for authorization checks, and so on
com.ibm.security.jgss.debug	JGSS debug control

Some JGSS Used Files

File	Notes
ibmjgssprovider.jar	IBM JGSS product JAR file.
jaas.conf	JAAS configuration file.
java.policy	Global permissions can be specified here.
java.security	IBMJCE must be listed here. JAAS config and policy files can also be listed here.
krb5.conf or krb5.ini	Kerberos configuration file.

Packages

Package	Notes
org.ietf.jgss	Top-level Java GSSAPI interfaces and classes.
javax.security.auth.kerberos	JAAS Kerberos login and authorization classes.
com.ibm.security.krb5.internal.tools	Kerberos command-line tools.

Application developers are advised to use APIs from the org.ietf.jgss package only. JAAS-enabled applications can also use APIs from the javax.security.auth.kerberos package. This use will ensure optimum portability for their applications.

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

Trademarks

IBM is a trademark or registered trademark of International Business Machines Corporation in the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.