jdk/src/share/classes/org/ietf/jgss/package.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

This code is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 only, as
published by the Free Software Foundation.  Oracle designates this
particular file as subject to the "Classpath" exception as provided
by Oracle in the LICENSE file that accompanied this code.

This code is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
version 2 for more details (a copy is included in the LICENSE file that
accompanied this code).

You should have received a copy of the GNU General Public License version
2 along with this work; if not, write to the Free Software Foundation,
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
or visit www.oracle.com if you need additional information or have any
questions.
-->

</head>
<body bgcolor="white">

    This package presents a framework that allows application developers to
    make use of security services like authentication, data integrity and
    data confidentiality from a variety of underlying security mechanisms
    like Kerberos, using a unified API. The security mechanisms that an
    application can
    chose to use are identified with unique object identifiers. One example 
    of such a mechanism is the Kerberos v5 GSS-API mechanism (object
    identifier 1.2.840.113554.1.2.2). This mechanism is available through
    the default instance of the GSSManager class.<p>

    The GSS-API is defined in a language independent way in 
    <a href=http://www.ietf.org/rfc/rfc2743.txt>RFC 2743</a>. The Java
    language bindings are defined in 
    <a href=http://www.ietf.org/rfc/rfc2853.txt>RFC 2853</a><p>

    An application starts out by instantiating a <code>GSSManager</code>
    which then serves as a factory for a security context. An application
    can use specific principal names and credentials that are also created
    using the GSSManager; or it can instantiate a
    context with system defaults. It then goes through a context
    establishment loop. Once a context is established with the
    peer, authentication is complete. Data protection such as integrity
    and confidentiality can then be obtained from this context.<p>

    The GSS-API does not perform any communication with the peer. It merely 
    produces tokens that the application must somehow transport to the
    other end.<p>

<h3>Credential Acquisition</h3>
<a name=useSubjectCredsOnly>
    The GSS-API itself does not dictate how an underlying mechanism
    obtains the credentials that are needed for authentication. It is
    assumed that prior to calling the GSS-API, these credentials are
    obtained and stored in a location that the mechanism provider is
    aware of. However, the default model in the Java platform will be
    that mechanism providers must obtain credentials only from the private
    or public credential sets associated with the
    {@link javax.security.auth.Subject Subject} in the
    current access control context.  The Kerberos v5  
    mechanism will search for the required INITIATE and ACCEPT credentials 
    ({@link javax.security.auth.kerberos.KerberosTicket KerberosTicket} and
     {@link javax.security.auth.kerberos.KerberosKey KerberosKey}) in
    the private credential set where as some other mechanism might look
    in the public set or in both.  If the desired credential is not
    present in the appropriate sets of the current Subject, the GSS-API
    call must fail.<p>

    This model has the advantage that credential management
    is simple and predictable from the applications point of view.  An
    application, given the right permissions, can purge the credentials in
    the Subject or renew them using standard Java API's.  If it purged
    the credentials, it would be sure that the JGSS mechanism would fail,
    or if it renewed a time based credential it would be sure that a JGSS
    mechanism would succeed.<p>

    This model does require that a {@link
    javax.security.auth.login JAAS login} be performed in order to
    authenticate and populate a Subject that the JGSS mechanism can later 
    utilize. However, applications have the ability to relax this
    restriction by means of a system property:
    <code>javax.security.auth.useSubjectCredsOnly</code>. By default
    this system property will be assumed to be <code>true</code> (even when
    it is unset) indicating that providers must only use the credentials
    that are present in the current Subject. However, if this property is
    explicitly set to false by the application, then it indicates that
    the provider is free to use any credentials cache of its choice. Such
    a credential cache might be a disk cache, an in-memory cache, or even
    just the current Subject itself.
</a>

<h2>Related Documentation</h2>
<p>
For an online tutorial on using Java GSS-API, please see
<a href="../../../../technotes/guides/security/jgss/tutorials/index.html">Introduction to JAAS and Java GSS-API</a>.
</p>

<!--
<h2>Package Specification</h2>

##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
<ul>
  <li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
</ul>

<h2>Related Documentation</h2>

For overviews, tutorials, examples, guides, and tool documentation, please see:
<ul>
  <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
</ul>

-->

@since 1.4
</body>
</html>