KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)StartTlsRequest.java 1.16 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.util.Iterator JavaDoc;
11 import java.security.AccessController JavaDoc;
12 import java.security.PrivilegedAction JavaDoc;
13 import javax.naming.ConfigurationException JavaDoc;
14 import javax.naming.NamingException JavaDoc;
15 import com.sun.naming.internal.VersionHelper;
16 import sun.misc.Service;
17
18 /**
19  * This class implements the LDAPv3 Extended Request for StartTLS as
20  * defined in
21  * <a HREF="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory
22  * Access Protocol (v3): Extension for Transport Layer Security</a>
23  *
24  * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
25  * and no extended request value is defined.
26  *<p>
27  * <tt>StartTlsRequest</tt>/<tt>StartTlsResponse</tt> are used to establish
28  * a TLS connection over the existing LDAP connection associated with
29  * the JNDI context on which <tt>extendedOperation()</tt> is invoked.
30  * Typically, a JNDI program uses these classes as follows.
31  * <blockquote><pre>
32  * import javax.naming.ldap.*;
33  *
34  * // Open an LDAP association
35  * LdapContext ctx = new InitialLdapContext();
36  *
37  * // Perform a StartTLS extended operation
38  * StartTlsResponse tls =
39  * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());
40  *
41  * // Open a TLS connection (over the existing LDAP association) and get details
42  * // of the negotiated TLS session: cipher suite, peer certificate, etc.
43  * SSLSession session = tls.negotiate();
44  *
45  * // ... use ctx to perform protected LDAP operations
46  *
47  * // Close the TLS connection (revert back to the underlying LDAP association)
48  * tls.close();
49  *
50  * // ... use ctx to perform unprotected LDAP operations
51  *
52  * // Close the LDAP association
53  * ctx.close;
54  * </pre></blockquote>
55  *
56  * @since 1.4
57  * @see StartTlsResponse
58  * @author Vincent Ryan
59  */
60 public class StartTlsRequest implements ExtendedRequest JavaDoc {
61
62     // Constant
63
64     /**
65      * The StartTLS extended request's assigned object identifier
66      * is 1.3.6.1.4.1.1466.20037.
67      */
68     public static final String JavaDoc OID = "1.3.6.1.4.1.1466.20037";
69
70
71     // Constructors
72
73     /**
74      * Constructs a StartTLS extended request.
75      */
76     public StartTlsRequest() {
77     }
78
79
80     // ExtendedRequest methods
81
82     /**
83      * Retrieves the StartTLS request'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 request's ASN.1 BER encoded value.
93      * Since the request 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     /**
103      * Creates an extended response object that corresponds to the
104      * LDAP StartTLS extended request.
105      * <p>
106      * The result must be a concrete subclass of StartTlsResponse
107      * and must have a public zero-argument constructor.
108      * <p>
109      * This method locates the implementation class by locating
110      * configuration files that have the name:
111      * <blockquote><tt>
112      * META-INF/services/javax.naming.ldap.StartTlsResponse
113      * </tt></blockquote>
114      * The configuration files and their corresponding implementation classes must
115      * be accessible to the calling thread's context class loader.
116      * <p>
117      * Each configuration file should contain a list of fully-qualified class
118      * names, one per line. Space and tab characters surrounding each name, as
119      * well as blank lines, are ignored. The comment character is <tt>'#'</tt>
120      * (<tt>0x23</tt>); on each line all characters following the first comment
121      * character are ignored. The file must be encoded in UTF-8.
122      * <p>
123      * This method will return an instance of the first implementation
124      * class that it is able to load and instantiate successfully from
125      * the list of class names collected from the configuration files.
126      * This method uses the calling thread's context classloader to find the
127      * configuration files and to load the implementation class.
128      * <p>
129      * If no class can be found in this way, this method will use
130      * an implementation-specific way to locate an implementation.
131      * If none is found, a NamingException is thrown.
132      *
133      * @param id The object identifier of the extended response.
134      * Its value must be "1.3.6.1.4.1.1466.20037" or null.
135      * Both values are equivalent.
136      * @param berValue The possibly null ASN.1 BER encoded value of the
137      * extended response. This is the raw BER bytes
138      * including the tag and length of the response value.
139      * It does not include the response OID.
140      * Its value is ignored because a Start TLS response
141      * is not expected to contain any response value.
142      * @param offset The starting position in berValue of the bytes to use.
143      * Its value is ignored because a Start TLS response
144      * is not expected to contain any response value.
145      * @param length The number of bytes in berValue to use.
146      * Its value is ignored because a Start TLS response
147      * is not expected to contain any response value.
148      * @return The StartTLS extended response object.
149      * @exception NamingException If a naming exception was encountered
150      * while creating the StartTLS extended response object.
151      */
152     public ExtendedResponse JavaDoc createExtendedResponse(String JavaDoc id, byte[] berValue,
153     int offset, int length) throws NamingException JavaDoc {
154
155     // Confirm that the object identifier is correct
156 if ((id != null) && (!id.equals(OID))) {
157         throw new ConfigurationException JavaDoc(
158         "Start TLS received the following response instead of " +
159         OID + ": " + id);
160     }
161
162     StartTlsResponse JavaDoc resp = null;
163
164     Iterator JavaDoc ps = Service.providers(StartTlsResponse JavaDoc.class,
165         getContextClassLoader());
166
167     while (resp == null && privilegedHasNext(ps)) {
168         resp = (StartTlsResponse JavaDoc)ps.next();
169     }
170
171     if (resp != null) {
172         return resp;
173     }
174
175         try {
176         VersionHelper helper = VersionHelper.getVersionHelper();
177         Class JavaDoc clas = helper.loadClass(
178         "com.sun.jndi.ldap.ext.StartTlsResponseImpl");
179
180         resp = (StartTlsResponse JavaDoc) clas.newInstance();
181
182         } catch (IllegalAccessException JavaDoc e) {
183         throw wrapException(e);
184
185         } catch (InstantiationException JavaDoc e) {
186         throw wrapException(e);
187
188         } catch (ClassNotFoundException JavaDoc e) {
189         throw wrapException(e);
190         }
191
192     return resp;
193     }
194
195     /*
196      * Wrap an exception, thrown while attempting to load the StartTlsResponse
197      * class, in a configuration exception.
198      */
199     private ConfigurationException JavaDoc wrapException(Exception JavaDoc e) {
200     ConfigurationException JavaDoc ce = new ConfigurationException JavaDoc(
201         "Cannot load implementation of javax.naming.ldap.StartTlsResponse");
202
203     ce.setRootCause(e);
204     return ce;
205     }
206
207     /*
208      * Acquire the class loader associated with this thread.
209      */
210     private final ClassLoader JavaDoc getContextClassLoader() {
211     return (ClassLoader JavaDoc) AccessController.doPrivileged(
212         new PrivilegedAction JavaDoc() {
213         public Object JavaDoc run() {
214             return Thread.currentThread().getContextClassLoader();
215         }
216         }
217     );
218     }
219
220     private final static boolean privilegedHasNext(final Iterator JavaDoc iter) {
221     Boolean JavaDoc answer = (Boolean JavaDoc) AccessController.doPrivileged(
222         new PrivilegedAction JavaDoc() {
223         public Object JavaDoc run() {
224         return new Boolean JavaDoc(iter.hasNext());
225         }
226     });
227     return answer.booleanValue();
228     }
229
230     private static final long serialVersionUID = 4441679576360753397L;
231 }
232
Popular Tags