IBM JavaTM Generic Security Service API (JGSS) 1.0.1

Sample README

This README file provides information about the IBM JavaTM Generic Security Services Application Programming Interface (JGSS) 1.0


Contents

·         Introduction

·         Product Documentation

·         Sample Programs

·         Configuration And Policy Files

·         Running The Sample Programs

·         Examples

·Packaging

·Installation

·Prerequisites

·Notices

·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 for AIX, Java 2 Technology Edition, Version 1.4.2, 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, 2004. 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 1.0 is IBM’s implementation of Java™ GSSAPI. This document provides information on running the sample applications that accompany the product.The JavaTM Generic Security Services API (JGSS) is standardized by the Internet Engineering Task Force (IETF) and the  and provides a generic authentication and secure messaging interface under which can be plugged actual security mechanisms. Such a mechanism may be based on secret-key or public-key or other security technologies.

By abstracting the complexity and peculiarities of the many underlying security mechanisms to a simple, standardized interface, JGSS provides a huge benefit to the development of secure networking applications: develop the application to the single abstract interface and use it over different security mechanisms without modification.

IBM JGSS comprises a GSSAPI framework together with a Kerberos V5 mechanism as the default underlying security system. It also features a JavaTM Authentication And Authorization Service (JAAS) LoginModule for creating and using Kerberos credentials. In addition, it performs JAAS authorization checks on the use of those credentials. These JAAS features are optional and may be turned off by setting the JavaTM property javax.security.authn.useSubjectCredsOnly to false in the JavaTM Virtual Machine (JVM).

 

 

 

Product Documentation

            The The following documents are provided in the product package and may be consulted for additional information on product installation, etc::

1.      IBM JGSS Application Developer's Guide: for information on secure application development using IBM JGSS

1.      IBM JGSS Readme

1.      IBM JGSS Security Mechanism Programmer's Guide: for information on the development of a security mechanism to be plugged under the IBM JGSS framework

2.      IBM JGSS User's Guide

3.      IBM JGSS Application Developer's Guide: for help on running IBM JGSS applications.

Consult the documentation accompanying the sample programs for information on how to run the samples.

For Java™ GSSAPI specification, consult the Internet Engineering Task Force (IETF) RFC 2743 Generic Security Services Application Programming Interface Version2, Update 1 and RFC 2853 Generic Security Service API Version 2: Java Bindings

Packaging

IBM JGSS ships as a compressed archive containing the following components:

Jar\ibmjgssprovider.jar

The product’s class files

docs\api\

The Java™ docs for the APIs

docs\

This readme file, and user and programming guides

sample\jar\ibmjgsssample.jar

The class files that make up the sample programs

sample\config\

Sample configuration files for Kerberos and JAAS

sample\

Readme file, etc

Sample Programs

 

There is a client program and a server program each of which has a JAAS-enabled version, making a total of four sample programs. The JAAS-enabled versions are fully interoperable with their non-JAAS counterparts, that is, a JAAS-enabled client may be run against a non-JAAS server and vice-versa. Each program takes a number of input arguments. Consult the sample documentation and source code for additional information:

1.      Sample Java™ Documentation

2.      Sample Client Program

3.      Sample Server Program

4.      Sample JAAS-Enabled Client Program

5.      Sample JAAS-Enabled Server Program

The JAAS features of JGSS may be turned off by setting the Java™ property javax.security.auth.useSubjectCredsOnly to false. The property is true, that is, JAAS is enabled, by default. The non-JAAS client and server programs set the property to false if the property has not  been set explicitly.

 

Configuration And Policy Files

A number of configuration files are provided in the sample\config directory. These include a Kerberos configuration file, a JAAS configuration file and a JAAS policy file. Modify the configuration files to suit your particular environment. Consult the product user's guideproduct Readme for placement and use of the modified configuration files.

 

Running The Sample Programs

The samples can be run in either a one-server or a two-server configuration. The two-server configuration consists of a primary and a secondary server. The primary server acts as an initiator, that is, a client, to the secondary server. This configuration is used when a client will be delegating its credentials to the primary server for use on behalf of the client. Upon receiving the delegated credentials from the client, the primary server uses the delegated credentials to initiate context with and exchange secure messages with the secondary server. The two-server configuration should also be used when the primary server will be acting as a client on its own behalf, using its own credentials to initiate context with and exchanging messages with the secondary server.

A client is usually run against the primary server, and any number of clients may be run simultaneously against the primary server. It is also possible to run a client directly against the secondary server. However, a server designated as a secondary server will be unable to use delegated credentials or run as an initiator using its own credentials.

 

Sample Program Invocation

A sample program is invoked as

            java [-Dproperty1=value1 –DpropertyN=valueN] com.ibm.security.jgss.test.<program> [options]

where <program> is Client, Server, JAASClient or JAASServer.

As stated in the product User's Guide, some of the Java™ properties that may be set on the command-line include name of Kerberos configuration file, JGG debug options, Security Manager and JAAS configuration and policy file name.

A server program must be started and ready to receive connections befores its client program is started. A server is ready when it displays the message “listening on port <server_port>”. The displayed port number should be noted and specified as input to the client program.

            Each program outputs a list of supported options when the h option is used:

                        java com.ibm.security.jgss.test.<program> -h

 

Examples

To start a non-JAAS server to run on port 4444 as principal “superSecureServer” with “backupServer” as the secondary server and to collect application and credentials JGSS debug information, enter

            java –Dcom.ibm.security.jgss.debug=”app, cred” com.ibm.security.jgss.test.Server –p 4444 –n superSecureServer –s backupServer

 

To run JAAS-enabled client “foo” against the primary server on the host “securityCentral” using the default Security Manager and the JAAS configuration and policy file from the sample\config directory, type

java –Djava.security.manager –Djava.security.auth.login.conf=..\config\jaas.conf

       -Djava.security.policy=..\config\sample.policy

       com.ibm.security.jgss.test.JAASClient –n foo –s superSecureServer h securityCentral:4444

 

 

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:

·                IBM Director of Licensing
IBM Corporation
North Castle Drive, Armonk
NY 10504-1758 U.S.A.

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

·                IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

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:

·                JIMMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) 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.

   

Installation

  Place the product jar file ibmjgssprovider.jar in a directory of you choice and set your classpath to include the jar file. For example, if you placed the jar file in the directory c:\ibmjgss\jar, then your classpath will be c:\ibmjgss\jar\ibmjgssprovider.jar;%classpath%.

Security Provider

IBM JGSS uses cryptographic and security services not included in the ibmjgssprovider.jar file. These services are provided by the IBM JCE Provider jar files supplied in the IBM JGSS product package. Place these jar files in your Java™ extensions (%jdk%\jre\lib\ext) directory. Also, sun.security.provider.Sun and com.ibm.crypto.provider.IBMJCE must be listed respectively as the number one and two security providers in the java.security file which is typically located in the %jdk%\jre\lib\security directory of your Java™ JDK installation.

Prerequisites

IBM JGSS requires Java™ Development Toolkit (JDK) 1.3 or later. Java™ Authentication And Authorization Service (JAAS) 1.0 is also required for running applications that leverage JGSS runtime JAAS features. Furthermore, JAAS 1.0 is required for JGSS application development regardless of whether the application will use the JAAS features of JGSS.

Notices

This edition applies to Java Generic Security Services Application Programming Interface (JGSS) and to all subsequent releases and modifications until otherwise indicated in new editions.

Copyright International Business Machines Corporation 2001. All rights reserved.

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

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 users 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:

IBM Director of Licensing IBM Corporation
North Castle Drive Armonk, NY 10504-1758 U.S.A.

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

IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

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:

JTCMAIL@uk.ibm.com
[Hursley Java Technology Center (JTC) 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 of International Business Machines Corporation in the U.S., or other countries, or both.

Java is a trademark of Sun Microsystems, Inc. in the U.S. and other countries. The Java technology is owned and exclusively licensed by Sun Microsystems, Inc.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

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

THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY PATENTS OR COPYRIGHTS.

(c) Copyright IBM Corporation, 2000. All rights reserved.

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