| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <!-- |
| 5 | Copyright 2000-2006 Sun Microsystems, Inc. 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. Sun designates this |
| 11 | particular file as subject to the "Classpath" exception as provided |
| 12 | by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 25 | CA 95054 USA or visit www.sun.com if you need additional information or |
| 26 | have any 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 mechnanism can later |
| 90 | utilize. However, applications have the ability to relax this |
| 91 | restiction 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> |