· Concepts
· Configuration And Policy Files
· Some Notable Java™ Properties
· Packages
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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"
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
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.
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
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.
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)
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
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.
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 |
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 |
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.