001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.naming.ldap;
027
028 import java.io.IOException;
029 import javax.net.ssl.SSLSession;
030 import javax.net.ssl.SSLSocketFactory;
031 import javax.net.ssl.HostnameVerifier;
032
033 /**
034 * This class implements the LDAPv3 Extended Response for StartTLS as
035 * defined in
036 * <a href="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory
037 * Access Protocol (v3): Extension for Transport Layer Security</a>
038 *
039 * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
040 * and no extended response value is defined.
041 *
042 *<p>
043 * The Start TLS extended request and response are used to establish
044 * a TLS connection over the existing LDAP connection associated with
045 * the JNDI context on which <tt>extendedOperation()</tt> is invoked.
046 * Typically, a JNDI program uses the StartTLS extended request and response
047 * classes as follows.
048 * <blockquote><pre>
049 * import javax.naming.ldap.*;
050 *
051 * // Open an LDAP association
052 * LdapContext ctx = new InitialLdapContext();
053 *
054 * // Perform a StartTLS extended operation
055 * StartTlsResponse tls =
056 * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());
057 *
058 * // Open a TLS connection (over the existing LDAP association) and get details
059 * // of the negotiated TLS session: cipher suite, peer certificate, ...
060 * SSLSession session = tls.negotiate();
061 *
062 * // ... use ctx to perform protected LDAP operations
063 *
064 * // Close the TLS connection (revert back to the underlying LDAP association)
065 * tls.close();
066 *
067 * // ... use ctx to perform unprotected LDAP operations
068 *
069 * // Close the LDAP association
070 * ctx.close;
071 * </pre></blockquote>
072 *
073 * @since 1.4
074 * @see StartTlsRequest
075 * @author Vincent Ryan
076 */
077 public abstract class StartTlsResponse implements ExtendedResponse {
078
079 // Constant
080
081 /**
082 * The StartTLS extended response's assigned object identifier
083 * is 1.3.6.1.4.1.1466.20037.
084 */
085 public static final String OID = "1.3.6.1.4.1.1466.20037";
086
087 // Called by subclass
088
089 /**
090 * Constructs a StartTLS extended response.
091 * A concrete subclass must have a public no-arg constructor.
092 */
093 protected StartTlsResponse() {
094 }
095
096 // ExtendedResponse methods
097
098 /**
099 * Retrieves the StartTLS response's object identifier string.
100 *
101 * @return The object identifier string, "1.3.6.1.4.1.1466.20037".
102 */
103 public String getID() {
104 return OID;
105 }
106
107 /**
108 * Retrieves the StartTLS response's ASN.1 BER encoded value.
109 * Since the response has no defined value, null is always
110 * returned.
111 *
112 * @return The null value.
113 */
114 public byte[] getEncodedValue() {
115 return null;
116 }
117
118 // StartTls-specific methods
119
120 /**
121 * Overrides the default list of cipher suites enabled for use on the
122 * TLS connection. The cipher suites must have already been listed by
123 * <tt>SSLSocketFactory.getSupportedCipherSuites()</tt> as being supported.
124 * Even if a suite has been enabled, it still might not be used because
125 * the peer does not support it, or because the requisite certificates
126 * (and private keys) are not available.
127 *
128 * @param suites The non-null list of names of all the cipher suites to
129 * enable.
130 * @see #negotiate
131 */
132 public abstract void setEnabledCipherSuites(String[] suites);
133
134 /**
135 * Sets the hostname verifier used by <tt>negotiate()</tt>
136 * after the TLS handshake has completed and the default hostname
137 * verification has failed.
138 * <tt>setHostnameVerifier()</tt> must be called before
139 * <tt>negotiate()</tt> is invoked for it to have effect.
140 * If called after
141 * <tt>negotiate()</tt>, this method does not do anything.
142 *
143 * @param verifier The non-null hostname verifier callback.
144 * @see #negotiate
145 */
146 public abstract void setHostnameVerifier(HostnameVerifier verifier);
147
148 /**
149 * Negotiates a TLS session using the default SSL socket factory.
150 * <p>
151 * This method is equivalent to <tt>negotiate(null)</tt>.
152 *
153 * @return The negotiated SSL session
154 * @throws IOException If an IO error was encountered while establishing
155 * the TLS session.
156 * @see #setEnabledCipherSuites
157 * @see #setHostnameVerifier
158 */
159 public abstract SSLSession negotiate() throws IOException;
160
161 /**
162 * Negotiates a TLS session using an SSL socket factory.
163 * <p>
164 * Creates an SSL socket using the supplied SSL socket factory and
165 * attaches it to the existing connection. Performs the TLS handshake
166 * and returns the negotiated session information.
167 * <p>
168 * If cipher suites have been set via <tt>setEnabledCipherSuites</tt>
169 * then they are enabled before the TLS handshake begins.
170 * <p>
171 * Hostname verification is performed after the TLS handshake completes.
172 * The default hostname verification performs a match of the server's
173 * hostname against the hostname information found in the server's certificate.
174 * If this verification fails and no callback has been set via
175 * <tt>setHostnameVerifier</tt> then the negotiation fails.
176 * If this verification fails and a callback has been set via
177 * <tt>setHostnameVerifier</tt>, then the callback is used to determine whether
178 * the negotiation succeeds.
179 * <p>
180 * If an error occurs then the SSL socket is closed and an IOException
181 * is thrown. The underlying connection remains intact.
182 *
183 * @param factory The possibly null SSL socket factory to use.
184 * If null, the default SSL socket factory is used.
185 * @return The negotiated SSL session
186 * @throws IOException If an IO error was encountered while establishing
187 * the TLS session.
188 * @see #setEnabledCipherSuites
189 * @see #setHostnameVerifier
190 */
191 public abstract SSLSession negotiate(SSLSocketFactory factory)
192 throws IOException;
193
194 /**
195 * Closes the TLS connection gracefully and reverts back to the underlying
196 * connection.
197 *
198 * @throws IOException If an IO error was encountered while closing the
199 * TLS connection
200 */
201 public abstract void close() throws IOException;
202
203 private static final long serialVersionUID = 8372842182579276418L;
204 }
|