KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > naming > ldap > StartTlsResponse


1 /*
2  * @(#)StartTlsResponse.java 1.21 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.naming.ldap;
9
10 import java.io.IOException JavaDoc;
11 import javax.net.ssl.SSLSession;
12 import javax.net.ssl.SSLSocketFactory;
13 import javax.net.ssl.HostnameVerifier;
14
15 /**
16  * This class implements the LDAPv3 Extended Response for StartTLS as
17  * defined in
18  * <a HREF="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory
19  * Access Protocol (v3): Extension for Transport Layer Security</a>
20  *
21  * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
22  * and no extended response value is defined.
23  *
24  *<p>
25  * The Start TLS extended request and response are used to establish
26  * a TLS connection over the existing LDAP connection associated with
27  * the JNDI context on which <tt>extendedOperation()</tt> is invoked.
28  * Typically, a JNDI program uses the StartTLS extended request and response
29  * classes as follows.
30  * <blockquote><pre>
31  * import javax.naming.ldap.*;
32  *
33  * // Open an LDAP association
34  * LdapContext ctx = new InitialLdapContext();
35  *
36  * // Perform a StartTLS extended operation
37  * StartTlsResponse tls =
38  * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());
39  *
40  * // Open a TLS connection (over the existing LDAP association) and get details
41  * // of the negotiated TLS session: cipher suite, peer certificate, ...
42  * SSLSession session = tls.negotiate();
43  *
44  * // ... use ctx to perform protected LDAP operations
45  *
46  * // Close the TLS connection (revert back to the underlying LDAP association)
47  * tls.close();
48  *
49  * // ... use ctx to perform unprotected LDAP operations
50  *
51  * // Close the LDAP association
52  * ctx.close;
53  * </pre></blockquote>
54  *
55  * @since 1.4
56  * @see StartTlsRequest
57  * @author Vincent Ryan
58  */
59 public abstract class StartTlsResponse implements ExtendedResponse JavaDoc {
60
61     // Constant
62
63     /**
64      * The StartTLS extended response's assigned object identifier
65      * is 1.3.6.1.4.1.1466.20037.
66      */
67     public static final String JavaDoc OID = "1.3.6.1.4.1.1466.20037";
68
69
70     // Called by subclass
71
72     /**
73      * Constructs a StartTLS extended response.
74      * A concrete subclass must have a public no-arg constructor.
75      */
76     protected StartTlsResponse() {
77     }
78
79
80     // ExtendedResponse methods
81
82     /**
83      * Retrieves the StartTLS response's object identifier string.
84      *
85      * @return The object identifier string, "1.3.6.1.4.1.1466.20037".
86      */
87     public String JavaDoc getID() {
88     return OID;
89     }
90
91     /**
92      * Retrieves the StartTLS response's ASN.1 BER encoded value.
93      * Since the response has no defined value, null is always
94      * returned.
95      *
96      * @return The null value.
97      */
98     public byte[] getEncodedValue() {
99     return null;
100     }
101
102     // StartTls-specific methods
103
104     /**
105      * Overrides the default list of cipher suites enabled for use on the
106      * TLS connection. The cipher suites must have already been listed by
107      * <tt>SSLSocketFactory.getSupportedCipherSuites()</tt> as being supported.
108      * Even if a suite has been enabled, it still might not be used because
109      * the peer does not support it, or because the requisite certificates
110      * (and private keys) are not available.
111      *
112      * @param suites The non-null list of names of all the cipher suites to
113      * enable.
114      * @see #negotiate
115      */
116     public abstract void setEnabledCipherSuites(String JavaDoc[] suites);
117
118     /**
119      * Sets the hostname verifier used by <tt>negotiate()</tt>
120      * after the TLS handshake has completed and the default hostname
121      * verification has failed.
122      * <tt>setHostnameVerifier()</tt> must be called before
123      * <tt>negotiate()</tt> is invoked for it to have effect.
124      * If called after
125      * <tt>negotiate()</tt>, this method does not do anything.
126      *
127      * @param verifier The non-null hostname verifier callback.
128      * @see #negotiate
129      */
130     public abstract void setHostnameVerifier(HostnameVerifier verifier);
131
132     /**
133      * Negotiates a TLS session using the default SSL socket factory.
134      * <p>
135      * This method is equivalent to <tt>negotiate(null)</tt>.
136      *
137      * @return The negotiated SSL session
138      * @throws IOException If an IO error was encountered while establishing
139      * the TLS session.
140      * @see #setEnabledCipherSuites
141      * @see #setHostnameVerifier
142      */
143     public abstract SSLSession negotiate() throws IOException JavaDoc;
144
145     /**
146      * Negotiates a TLS session using an SSL socket factory.
147      * <p>
148      * Creates an SSL socket using the supplied SSL socket factory and
149      * attaches it to the existing connection. Performs the TLS handshake
150      * and returns the negotiated session information.
151      * <p>
152      * If cipher suites have been set via <tt>setEnabledCipherSuites</tt>
153      * then they are enabled before the TLS handshake begins.
154      * <p>
155      * Hostname verification is performed after the TLS handshake completes.
156      * The default hostname verification performs a match of the server's
157      * hostname against the hostname information found in the server's certificate.
158      * If this verification fails and no callback has been set via
159      * <tt>setHostnameVerifier</tt> then the negotiation fails.
160      * If this verification fails and a callback has been set via
161      * <tt>setHostnameVerifier</tt>, then the callback is used to determine whether
162      * the negotiation succeeds.
163      * <p>
164      * If an error occurs then the SSL socket is closed and an IOException
165      * is thrown. The underlying connection remains intact.
166      *
167      * @param factory The possibly null SSL socket factory to use.
168      * If null, the default SSL socket factory is used.
169      * @return The negotiated SSL session
170      * @throws IOException If an IO error was encountered while establishing
171      * the TLS session.
172      * @see #setEnabledCipherSuites
173      * @see #setHostnameVerifier
174      */
175     public abstract SSLSession negotiate(SSLSocketFactory factory)
176     throws IOException JavaDoc;
177
178     /**
179      * Closes the TLS connection gracefully and reverts back to the underlying
180      * connection.
181      *
182      * @throws IOException If an IO error was encountered while closing the
183      * TLS connection
184      */
185     public abstract void close() throws IOException JavaDoc;
186
187     private static final long serialVersionUID = 8372842182579276418L;
188 }
189
Popular Tags