This README file provides information about the IBM
JavaTM
Generic Security Services Application Programming Interface (JGSS) 1.0
·
Configuration And Policy
Files
·
Examples
·Packaging
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.
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).
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 Security Mechanism
Programmer's Guide: for information on
the development of a security mechanism to be plugged under the IBM JGSS
framework
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
IBM JGSS ships as a compressed archive containing
the following components:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:
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.
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.
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.
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
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
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.
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%.
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.
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.
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.
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.