1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2 <html>
3 <head>
4 <!--
5 Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
6 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7
8 This code is free software; you can redistribute it and/or modify it
9 under the terms of the GNU General Public License version 2 only, as
10 published by the Free Software Foundation. Oracle designates this
11 particular file as subject to the "Classpath" exception as provided
12 by Oracle in the LICENSE file that accompanied this code.
13
14 This code is distributed in the hope that it will be useful, but WITHOUT
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 version 2 for more details (a copy is included in the LICENSE file that
18 accompanied this code).
19
20 You should have received a copy of the GNU General Public License version
21 2 along with this work; if not, write to the Free Software Foundation,
22 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
23
24 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
25 or visit www.oracle.com if you need additional information or have any
26 questions.
27 -->
28
29 </head>
30 <body bgcolor="white">
31
32 This package presents a framework that allows application developers to
33 make use of security services like authentication, data integrity and
34 data confidentiality from a variety of underlying security mechanisms
35 like Kerberos, using a unified API. The security mechanisms that an
36 application can
37 chose to use are identified with unique object identifiers. One example
38 of such a mechanism is the Kerberos v5 GSS-API mechanism (object
39 identifier 1.2.840.113554.1.2.2). This mechanism is available through
40 the default instance of the GSSManager class.<p>
41
42 The GSS-API is defined in a language independent way in
43 <a href=http://www.ietf.org/rfc/rfc2743.txt>RFC 2743</a>. The Java
44 language bindings are defined in
45 <a href=http://www.ietf.org/rfc/rfc2853.txt>RFC 2853</a><p>
46
47 An application starts out by instantiating a <code>GSSManager</code>
48 which then serves as a factory for a security context. An application
49 can use specific principal names and credentials that are also created
50 using the GSSManager; or it can instantiate a
51 context with system defaults. It then goes through a context
52 establishment loop. Once a context is established with the
53 peer, authentication is complete. Data protection such as integrity
54 and confidentiality can then be obtained from this context.<p>
55
56 The GSS-API does not perform any communication with the peer. It merely
57 produces tokens that the application must somehow transport to the
58 other end.<p>
59
60 <h3>Credential Acquisition</h3>
61 <a name=useSubjectCredsOnly>
62 The GSS-API itself does not dictate how an underlying mechanism
63 obtains the credentials that are needed for authentication. It is
64 assumed that prior to calling the GSS-API, these credentials are
65 obtained and stored in a location that the mechanism provider is
66 aware of. However, the default model in the Java platform will be
67 that mechanism providers must obtain credentials only from the private
68 or public credential sets associated with the
69 {@link javax.security.auth.Subject Subject} in the
70 current access control context. The Kerberos v5
71 mechanism will search for the required INITIATE and ACCEPT credentials
72 ({@link javax.security.auth.kerberos.KerberosTicket KerberosTicket} and
73 {@link javax.security.auth.kerberos.KerberosKey KerberosKey}) in
74 the private credential set where as some other mechanism might look
75 in the public set or in both. If the desired credential is not
76 present in the appropriate sets of the current Subject, the GSS-API
77 call must fail.<p>
78
79 This model has the advantage that credential management
80 is simple and predictable from the applications point of view. An
81 application, given the right permissions, can purge the credentials in
82 the Subject or renew them using standard Java API's. If it purged
83 the credentials, it would be sure that the JGSS mechanism would fail,
84 or if it renewed a time based credential it would be sure that a JGSS
85 mechanism would succeed.<p>
86
87 This model does require that a {@link
88 javax.security.auth.login JAAS login} be performed in order to
89 authenticate and populate a Subject that the JGSS mechanism can later
90 utilize. However, applications have the ability to relax this
91 restriction by means of a system property:
92 <code>javax.security.auth.useSubjectCredsOnly</code>. By default
93 this system property will be assumed to be <code>true</code> (even when
94 it is unset) indicating that providers must only use the credentials
95 that are present in the current Subject. However, if this property is
96 explicitly set to false by the application, then it indicates that
97 the provider is free to use any credentials cache of its choice. Such
98 a credential cache might be a disk cache, an in-memory cache, or even
99 just the current Subject itself.
100 </a>
101
102 <h2>Related Documentation</h2>
103 <p>
104 For an online tutorial on using Java GSS-API, please see
105 <a href="../../../../technotes/guides/security/jgss/tutorials/index.html">Introduction to JAAS and Java GSS-API</a>.
106 </p>
107
108 <!--
109 <h2>Package Specification</h2>
110
111 ##### FILL IN ANY SPECS NEEDED BY JAVA COMPATIBILITY KIT #####
112 <ul>
113 <li><a href="">##### REFER TO ANY FRAMEMAKER SPECIFICATION HERE #####</a>
114 </ul>
115
116 <h2>Related Documentation</h2>
117
118 For overviews, tutorials, examples, guides, and tool documentation, please see:
119 <ul>
120 <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
121 </ul>
122
123 -->
124
125 @since 1.4
126 </body>
127 </html>