Java tutorial
/* * Copyright (c) 2000, 2001, 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. */ package javax.naming.ldap; import java.io.IOException; import javax.net.ssl.SSLSession; import javax.net.ssl.SSLSocketFactory; import javax.net.ssl.HostnameVerifier; /** * This class implements the LDAPv3 Extended Response for StartTLS as * defined in * <a href="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory * Access Protocol (v3): Extension for Transport Layer Security</a> * * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037 * and no extended response value is defined. * *<p> * The Start TLS extended request and response are used to establish * a TLS connection over the existing LDAP connection associated with * the JNDI context on which {@code extendedOperation()} is invoked. * Typically, a JNDI program uses the StartTLS extended request and response * classes as follows. * <blockquote><pre> * import javax.naming.ldap.*; * * // Open an LDAP association * LdapContext ctx = new InitialLdapContext(); * * // Perform a StartTLS extended operation * StartTlsResponse tls = * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest()); * * // Open a TLS connection (over the existing LDAP association) and get details * // of the negotiated TLS session: cipher suite, peer certificate, ... * SSLSession session = tls.negotiate(); * * // ... use ctx to perform protected LDAP operations * * // Close the TLS connection (revert back to the underlying LDAP association) * tls.close(); * * // ... use ctx to perform unprotected LDAP operations * * // Close the LDAP association * ctx.close; * </pre></blockquote> * * @since 1.4 * @see StartTlsRequest * @author Vincent Ryan */ public abstract class StartTlsResponse implements ExtendedResponse { // Constant /** * The StartTLS extended response's assigned object identifier * is 1.3.6.1.4.1.1466.20037. */ public static final String OID = "1.3.6.1.4.1.1466.20037"; // Called by subclass /** * Constructs a StartTLS extended response. * A concrete subclass must have a public no-arg constructor. */ protected StartTlsResponse() { } // ExtendedResponse methods /** * Retrieves the StartTLS response's object identifier string. * * @return The object identifier string, "1.3.6.1.4.1.1466.20037". */ public String getID() { return OID; } /** * Retrieves the StartTLS response's ASN.1 BER encoded value. * Since the response has no defined value, null is always * returned. * * @return The null value. */ public byte[] getEncodedValue() { return null; } // StartTls-specific methods /** * Overrides the default list of cipher suites enabled for use on the * TLS connection. The cipher suites must have already been listed by * {@code SSLSocketFactory.getSupportedCipherSuites()} as being supported. * Even if a suite has been enabled, it still might not be used because * the peer does not support it, or because the requisite certificates * (and private keys) are not available. * * @param suites The non-null list of names of all the cipher suites to * enable. * @see #negotiate */ public abstract void setEnabledCipherSuites(String[] suites); /** * Sets the hostname verifier used by {@code negotiate()} * after the TLS handshake has completed and the default hostname * verification has failed. * {@code setHostnameVerifier()} must be called before * {@code negotiate()} is invoked for it to have effect. * If called after * {@code negotiate()}, this method does not do anything. * * @param verifier The non-null hostname verifier callback. * @see #negotiate */ public abstract void setHostnameVerifier(HostnameVerifier verifier); /** * Negotiates a TLS session using the default SSL socket factory. * <p> * This method is equivalent to {@code negotiate(null)}. * * @return The negotiated SSL session * @throws IOException If an IO error was encountered while establishing * the TLS session. * @see #setEnabledCipherSuites * @see #setHostnameVerifier */ public abstract SSLSession negotiate() throws IOException; /** * Negotiates a TLS session using an SSL socket factory. * <p> * Creates an SSL socket using the supplied SSL socket factory and * attaches it to the existing connection. Performs the TLS handshake * and returns the negotiated session information. * <p> * If cipher suites have been set via {@code setEnabledCipherSuites} * then they are enabled before the TLS handshake begins. * <p> * Hostname verification is performed after the TLS handshake completes. * The default hostname verification performs a match of the server's * hostname against the hostname information found in the server's certificate. * If this verification fails and no callback has been set via * {@code setHostnameVerifier} then the negotiation fails. * If this verification fails and a callback has been set via * {@code setHostnameVerifier}, then the callback is used to determine whether * the negotiation succeeds. * <p> * If an error occurs then the SSL socket is closed and an IOException * is thrown. The underlying connection remains intact. * * @param factory The possibly null SSL socket factory to use. * If null, the default SSL socket factory is used. * @return The negotiated SSL session * @throws IOException If an IO error was encountered while establishing * the TLS session. * @see #setEnabledCipherSuites * @see #setHostnameVerifier */ public abstract SSLSession negotiate(SSLSocketFactory factory) throws IOException; /** * Closes the TLS connection gracefully and reverts back to the underlying * connection. * * @throws IOException If an IO error was encountered while closing the * TLS connection */ public abstract void close() throws IOException; private static final long serialVersionUID = 8372842182579276418L; }