IBM JavaTM Generic Security Service API (JGSS) 1.0.1

User's Guide


Contents

·         Introduction

·         Concepts

·         JCE Provider

·         JAAS Login

·         JAAS Authorization Checks

·         Configuration And Policy Files

·         Credential Caches

·         Debugging

·         Some Notable Java™ Properties

·         Some Notable Files

·         Packages


Introduction

IBM JGSS 1.0.1 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 1.0.1 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 1.4.

 

Concepts

The operational paradigm of 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 may 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, 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 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 may 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.

Security Mechanisms

GSSAPI consists of an abstract framework over one or more underlying security mechanisms. How the framework is coupled to the various mechanisms it supports is implementation specific. At one extreme is a monolithic implementation in which the framework is tightly bound to a single mechanism and precludes the use of other mechanisms or even different implementations of the same mechanism. At the other end of the spectrum is a highly modular implementation offering seamless and near-effortless pluggability of different security mechanisms and their implementations.

 

IBM JGSS falls into the latter category. It leverages the provider framework defined by the Java™ Cryptographic Architecture (JCA), treating an underlying mechanism as a (JCA) provider. A JGSS provider supplies a concrete implementation of a JGSS security mechanism. Multiple mechanisms can be instantiated and used in a single invocation of a JGSS application.

 

A provider advertises its support for a mechanism by defining a mapping from the mechanism to a factory class for that mechanism. A provider can support multiple mechanisms. See the IBM JGSS Mechanism Provider's Guide for further details.

 

JGSS makes it easy to use different security mechanisms. However, it does not provide a means for two communicating peers to choose a mechanism when multiple mechanisms are available. One way to choose a mechanism is to start with the Simple And Protected GSSAPI Negotiating Mechanism (SPNEGO), a pseudo-mechanism that negotiates an actual mechanism between the two peers.

 

 

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 draft-ietf-krb-wg-crypto-01.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.

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-md4 – Repesents DES in CBC mode with MD4 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 draft-ietf-krb-wg-crypto-01.txt. It also supports the checksum algorithm hmac-md5 defined in draft-brezak-win2k-krb-rc4-hmac-04.txt 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:

·        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) may be obtained using the Java™ Kinit tool provided by JGSS. And 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 enables a tool to be invoked without entering its full package name on the command line.

Alternatively, Kerberos TGTs and secret keys may 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

The JGSS credential type

debug

true|false

false

Turn 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 default credential cache

useDefaultKeytab

true|false

false

Retrieve secret key from the specified key table

useFirstPass

true|false

false

Use password saved in shared state

useKeytab

<URL>

Don’t use key table

Retrieve secret key from the specified key table

 

 

The principal, debug and moduleBanner options may 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

 

All parts of a multi-part principal name must be specified. For example, “secure/sesame.com@SESAME.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 may be construed as delimiters to be quoted.

 

Krb5LoginModule may prompt for principal name, password or both. Or it may 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 may 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 may 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 delegating its TGT must have been granted a DelegationPermission specifying 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 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 specifying superSecureServer and the TGS. The file-based policy for foo will be like the one below.

 

grant codeBase “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:

 

1.      The file referenced by the Java™ property java.security.krb5.conf

2.      <java.home>/lib/security/krb5.conf

3.      c:\winnt\krb5.ini on Microsoft Windows™ platforms

4.      /etc/krb5/krb5.conf on Unix™ platforms

JAAS Configuration File

The use of the JAAS login feature requires a JAAS configuration file. This file may 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 may 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 may 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.<n>: URLs of CodeSource-based and principal-based policy files. To use the sample policy file, include an entry such as

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

·        login.configuration.provider: JAAS login configuration handler class, for example

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

·        login.config.url.<n>: URLs for JAAS login configuration files. To use the sample configuration file, include an entry similar to

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

 

 

Credential Caches

A user principal keeps its Kerberos credentials in a credentials cache and a service pricipal keeps its secret key in a key table. How IBM JGSS locates these caches at runtime is described below.

User Credentials Cache

The user credentials cache is located in the following order:

 

1.      The file referenced by the Java™ property KRB5CCNAME

2.      <user.home>/krb5cc_<user.name>

3.      <user.home>/krb5cc (if <user.name> cannot be obtained)

 

Server Key Table

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

 

1.      The value of the Java™ property KRB5_KTNAME

2.      default_keytab_name entry in the libdefaults stanza of the Kerberos configuration file

3.      <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 Notable 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, etc

com.ibm.security.jgss.debug

JGSS debug control

 

 

Some Notable Files

           

File
Notes

ibmjgssprovider.jar

IBM JGSS product jar file

jaas.conf

JAAS configuration file

java.policy

Global permissions may be specified here

java.security

IBMJCE must be listed here. JAAS config and policy files may 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 may also use APIs from the javax.security.auth.kerberos package. This will ensure optimum portability for their applications.