26 package javax.naming.ldap;
27
28 import java.util.Iterator;
29 import java.security.AccessController;
30 import java.security.PrivilegedAction;
31 import javax.naming.ConfigurationException;
32 import javax.naming.NamingException;
33 import com.sun.naming.internal.VersionHelper;
34 import java.util.ServiceLoader;
35 import java.util.ServiceConfigurationError;
36
37 /**
38 * This class implements the LDAPv3 Extended Request for StartTLS as
39 * defined in
40 * <a href="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory
41 * Access Protocol (v3): Extension for Transport Layer Security</a>
42 *
43 * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
44 * and no extended request value is defined.
45 *<p>
46 * <tt>StartTlsRequest</tt>/<tt>StartTlsResponse</tt> are used to establish
47 * a TLS connection over the existing LDAP connection associated with
48 * the JNDI context on which <tt>extendedOperation()</tt> is invoked.
49 * Typically, a JNDI program uses these classes as follows.
50 * <blockquote><pre>
51 * import javax.naming.ldap.*;
52 *
53 * // Open an LDAP association
54 * LdapContext ctx = new InitialLdapContext();
55 *
56 * // Perform a StartTLS extended operation
57 * StartTlsResponse tls =
58 * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());
59 *
60 * // Open a TLS connection (over the existing LDAP association) and get details
61 * // of the negotiated TLS session: cipher suite, peer certificate, etc.
62 * SSLSession session = tls.negotiate();
63 *
64 * // ... use ctx to perform protected LDAP operations
65 *
66 * // Close the TLS connection (revert back to the underlying LDAP association)
67 * tls.close();
68 *
110 /**
111 * Retrieves the StartTLS request's ASN.1 BER encoded value.
112 * Since the request has no defined value, null is always
113 * returned.
114 *
115 * @return The null value.
116 */
117 public byte[] getEncodedValue() {
118 return null;
119 }
120
121 /**
122 * Creates an extended response object that corresponds to the
123 * LDAP StartTLS extended request.
124 * <p>
125 * The result must be a concrete subclass of StartTlsResponse
126 * and must have a public zero-argument constructor.
127 * <p>
128 * This method locates the implementation class by locating
129 * configuration files that have the name:
130 * <blockquote><tt>
131 * META-INF/services/javax.naming.ldap.StartTlsResponse
132 * </tt></blockquote>
133 * The configuration files and their corresponding implementation classes must
134 * be accessible to the calling thread's context class loader.
135 * <p>
136 * Each configuration file should contain a list of fully-qualified class
137 * names, one per line. Space and tab characters surrounding each name, as
138 * well as blank lines, are ignored. The comment character is <tt>'#'</tt>
139 * (<tt>0x23</tt>); on each line all characters following the first comment
140 * character are ignored. The file must be encoded in UTF-8.
141 * <p>
142 * This method will return an instance of the first implementation
143 * class that it is able to load and instantiate successfully from
144 * the list of class names collected from the configuration files.
145 * This method uses the calling thread's context classloader to find the
146 * configuration files and to load the implementation class.
147 * <p>
148 * If no class can be found in this way, this method will use
149 * an implementation-specific way to locate an implementation.
150 * If none is found, a NamingException is thrown.
151 *
152 * @param id The object identifier of the extended response.
153 * Its value must be "1.3.6.1.4.1.1466.20037" or null.
154 * Both values are equivalent.
155 * @param berValue The possibly null ASN.1 BER encoded value of the
156 * extended response. This is the raw BER bytes
157 * including the tag and length of the response value.
158 * It does not include the response OID.
159 * Its value is ignored because a Start TLS response
|
26 package javax.naming.ldap;
27
28 import java.util.Iterator;
29 import java.security.AccessController;
30 import java.security.PrivilegedAction;
31 import javax.naming.ConfigurationException;
32 import javax.naming.NamingException;
33 import com.sun.naming.internal.VersionHelper;
34 import java.util.ServiceLoader;
35 import java.util.ServiceConfigurationError;
36
37 /**
38 * This class implements the LDAPv3 Extended Request for StartTLS as
39 * defined in
40 * <a href="http://www.ietf.org/rfc/rfc2830.txt">Lightweight Directory
41 * Access Protocol (v3): Extension for Transport Layer Security</a>
42 *
43 * The object identifier for StartTLS is 1.3.6.1.4.1.1466.20037
44 * and no extended request value is defined.
45 *<p>
46 * {@code StartTlsRequest}/{@code StartTlsResponse} are used to establish
47 * a TLS connection over the existing LDAP connection associated with
48 * the JNDI context on which {@code extendedOperation()} is invoked.
49 * Typically, a JNDI program uses these classes as follows.
50 * <blockquote><pre>
51 * import javax.naming.ldap.*;
52 *
53 * // Open an LDAP association
54 * LdapContext ctx = new InitialLdapContext();
55 *
56 * // Perform a StartTLS extended operation
57 * StartTlsResponse tls =
58 * (StartTlsResponse) ctx.extendedOperation(new StartTlsRequest());
59 *
60 * // Open a TLS connection (over the existing LDAP association) and get details
61 * // of the negotiated TLS session: cipher suite, peer certificate, etc.
62 * SSLSession session = tls.negotiate();
63 *
64 * // ... use ctx to perform protected LDAP operations
65 *
66 * // Close the TLS connection (revert back to the underlying LDAP association)
67 * tls.close();
68 *
110 /**
111 * Retrieves the StartTLS request's ASN.1 BER encoded value.
112 * Since the request has no defined value, null is always
113 * returned.
114 *
115 * @return The null value.
116 */
117 public byte[] getEncodedValue() {
118 return null;
119 }
120
121 /**
122 * Creates an extended response object that corresponds to the
123 * LDAP StartTLS extended request.
124 * <p>
125 * The result must be a concrete subclass of StartTlsResponse
126 * and must have a public zero-argument constructor.
127 * <p>
128 * This method locates the implementation class by locating
129 * configuration files that have the name:
130 * <blockquote>{@code
131 * META-INF/services/javax.naming.ldap.StartTlsResponse
132 * }</blockquote>
133 * The configuration files and their corresponding implementation classes must
134 * be accessible to the calling thread's context class loader.
135 * <p>
136 * Each configuration file should contain a list of fully-qualified class
137 * names, one per line. Space and tab characters surrounding each name, as
138 * well as blank lines, are ignored. The comment character is {@code '#'}
139 * ({@code 0x23}); on each line all characters following the first comment
140 * character are ignored. The file must be encoded in UTF-8.
141 * <p>
142 * This method will return an instance of the first implementation
143 * class that it is able to load and instantiate successfully from
144 * the list of class names collected from the configuration files.
145 * This method uses the calling thread's context classloader to find the
146 * configuration files and to load the implementation class.
147 * <p>
148 * If no class can be found in this way, this method will use
149 * an implementation-specific way to locate an implementation.
150 * If none is found, a NamingException is thrown.
151 *
152 * @param id The object identifier of the extended response.
153 * Its value must be "1.3.6.1.4.1.1466.20037" or null.
154 * Both values are equivalent.
155 * @param berValue The possibly null ASN.1 BER encoded value of the
156 * extended response. This is the raw BER bytes
157 * including the tag and length of the response value.
158 * It does not include the response OID.
159 * Its value is ignored because a Start TLS response
|