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