/*
* 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 <tt>extendedOperation()</tt> 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
* <tt>SSLSocketFactory.getSupportedCipherSuites()</tt> 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 <tt>negotiate()</tt>
* after the TLS handshake has completed and the default hostname
* verification has failed.
* <tt>setHostnameVerifier()</tt> must be called before
* <tt>negotiate()</tt> is invoked for it to have effect.
* If called after
* <tt>negotiate()</tt>, 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 <tt>negotiate(null)</tt>.
*
* @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 <tt>setEnabledCipherSuites</tt>
* 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
* <tt>setHostnameVerifier</tt> then the negotiation fails.
* If this verification fails and a callback has been set via
* <tt>setHostnameVerifier</tt>, 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;
}