1 /*

     2  * Copyright (c) 1999, 2017, 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  * Contains class and interfaces for supporting SASL.

    28  *

    29  * This package defines classes and interfaces for SASL mechanisms.

    30  * It is used by developers to add authentication support for

    31  * connection-based protocols that use SASL.

    32  *

    33  * <h3>SASL Overview</h3>

    34  *

    35  * Simple Authentication and Security Layer (SASL) specifies a

    36  * challenge-response protocol in which data is exchanged between the

    37  * client and the server for the purposes of

    38  * authentication and (optional) establishment of a security layer on

    39  * which to carry on subsequent communications.  It is used with

    40  * connection-based protocols such as LDAPv3 or IMAPv4.  SASL is

    41  * described in

    42  * <A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>.

    43  *

    44  *

    45  * There are various <em>mechanisms</em> defined for SASL.

    46  * Each mechanism defines the data that must be exchanged between the

    47  * client and server in order for the authentication to succeed.

    48  * This data exchange required for a particular mechanism is referred to

    49  * to as its <em>protocol profile</em>.

    50  * The following are some examples of mechanisms that have been defined by

    51  * the Internet standards community.

    52  * <ul>

    53  * <li>DIGEST-MD5 (<A HREF="http://www.ietf.org/rfc/rfc2831.txt">RFC 2831</a>).

    54  * This mechanism defines how HTTP Digest Authentication can be used as a SASL

    55  * mechanism.

    56  * <li>Anonymous (<A HREF="http://www.ietf.org/rfc/rfc2245.txt">RFC 2245</a>).

    57  * This mechanism is anonymous authentication in which no credentials are

    58  * necessary.

    59  * <li>External (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).

    60  * This mechanism obtains authentication information

    61  * from an external source (such as TLS or IPsec).

    62  * <li>S/Key (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).

    63  * This mechanism uses the MD4 digest algorithm to exchange data based on

    64  * a shared secret.

    65  * <li>GSSAPI (<A HREF="http://www.ietf.org/rfc/rfc2222.txt">RFC 2222</A>).

    66  * This mechanism uses the

    67  * <A HREF="http://www.ietf.org/rfc/rfc2078.txt">GSSAPI</A>

    68  * for obtaining authentication information.

    69  * </ul>

    70  *

    71  * Some of these mechanisms provide both authentication and establishment

    72  * of a security layer, others only authentication.  Anonymous and

    73  * S/Key do not provide for any security layers.  GSSAPI and DIGEST-MD5

    74  * allow negotiation of the security layer.  For External, the

    75  * security layer is determined by the external protocol.

    76  *

    77  * <h3>Usage</h3>

    78  *

    79  * Users of this API are typically developers who produce

    80  * client library implementations for connection-based protocols,

    81  * such as LDAPv3 and IMAPv4,

    82  * and developers who write servers (such as LDAP servers and IMAP servers).

    83  * Developers who write client libraries use the

    84  * {@code SaslClient} and {@code SaslClientFactory} interfaces.

    85  * Developers who write servers use the

    86  * {@code SaslServer} and {@code SaslServerFactory} interfaces.

    87  *

    88  * Among these two groups of users, each can be further divided into two groups:

    89  * those who <em>produce</em> the SASL mechanisms and those

    90  * who <em>use</em> the SASL mechanisms.

    91  * The producers of SASL mechanisms need to provide implementations

    92  * for these interfaces, while users of the SASL mechanisms use

    93  * the APIs in this package to access those implementations.

    94  *

    95  * <h2>Related Documentation</h2>

    96  *

    97  * Please refer to the

    98  * {@extLink security_guide_sasl Java SASL Programming Guide}

    99  * for information on how to use this API.

   100  *

   101  * @since 1.5

   102  */

   103 package javax.security.sasl;