001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2008 Sun Microsystems, Inc.
015 */
016package org.forgerock.opendj.server.config.server;
017
018
019
020import java.net.InetAddress;
021import java.util.SortedSet;
022import org.forgerock.opendj.config.server.ConfigurationChangeListener;
023import org.forgerock.opendj.ldap.DN;
024import org.forgerock.opendj.server.config.meta.LDAPConnectionHandlerCfgDefn.SSLClientAuthPolicy;
025
026
027
028/**
029 * A server-side interface for querying LDAP Connection Handler
030 * settings.
031 * <p>
032 * The LDAP Connection Handler is used to interact with clients using
033 * LDAP.
034 */
035public interface LDAPConnectionHandlerCfg extends ConnectionHandlerCfg {
036
037  /**
038   * Gets the configuration class associated with this LDAP Connection Handler.
039   *
040   * @return Returns the configuration class associated with this LDAP Connection Handler.
041   */
042  Class<? extends LDAPConnectionHandlerCfg> configurationClass();
043
044
045
046  /**
047   * Register to be notified when this LDAP Connection Handler is changed.
048   *
049   * @param listener
050   *          The LDAP Connection Handler configuration change listener.
051   */
052  void addLDAPChangeListener(ConfigurationChangeListener<LDAPConnectionHandlerCfg> listener);
053
054
055
056  /**
057   * Deregister an existing LDAP Connection Handler configuration change listener.
058   *
059   * @param listener
060   *          The LDAP Connection Handler configuration change listener.
061   */
062  void removeLDAPChangeListener(ConfigurationChangeListener<LDAPConnectionHandlerCfg> listener);
063
064
065
066  /**
067   * Gets the "accept-backlog" property.
068   * <p>
069   * Specifies the maximum number of pending connection attempts that
070   * are allowed to queue up in the accept backlog before the server
071   * starts rejecting new connection attempts.
072   * <p>
073   * This is primarily an issue for cases in which a large number of
074   * connections are established to the server in a very short period
075   * of time (for example, a benchmark utility that creates a large
076   * number of client threads that each have their own connection to
077   * the server) and the connection handler is unable to keep up with
078   * the rate at which the new connections are established.
079   *
080   * @return Returns the value of the "accept-backlog" property.
081   */
082  int getAcceptBacklog();
083
084
085
086  /**
087   * Gets the "allow-ldap-v2" property.
088   * <p>
089   * Indicates whether connections from LDAPv2 clients are allowed.
090   * <p>
091   * If LDAPv2 clients are allowed, then only a minimal degree of
092   * special support are provided for them to ensure that
093   * LDAPv3-specific protocol elements (for example, Configuration
094   * Guide 25 controls, extended response messages, intermediate
095   * response messages, referrals) are not sent to an LDAPv2 client.
096   *
097   * @return Returns the value of the "allow-ldap-v2" property.
098   */
099  boolean isAllowLDAPV2();
100
101
102
103  /**
104   * Gets the "allow-start-tls" property.
105   * <p>
106   * Indicates whether clients are allowed to use StartTLS.
107   * <p>
108   * If enabled, the LDAP Connection Handler allows clients to use the
109   * StartTLS extended operation to initiate secure communication over
110   * an otherwise insecure channel. Note that this is only allowed if
111   * the LDAP Connection Handler is not configured to use SSL, and if
112   * the server is configured with a valid key manager provider and a
113   * valid trust manager provider.
114   *
115   * @return Returns the value of the "allow-start-tls" property.
116   */
117  boolean isAllowStartTLS();
118
119
120
121  /**
122   * Gets the "allow-tcp-reuse-address" property.
123   * <p>
124   * Indicates whether the LDAP Connection Handler should reuse socket
125   * descriptors.
126   * <p>
127   * If enabled, the SO_REUSEADDR socket option is used on the server
128   * listen socket to potentially allow the reuse of socket descriptors
129   * for clients in a TIME_WAIT state. This may help the server avoid
130   * temporarily running out of socket descriptors in cases in which a
131   * very large number of short-lived connections have been established
132   * from the same client system.
133   *
134   * @return Returns the value of the "allow-tcp-reuse-address" property.
135   */
136  boolean isAllowTCPReuseAddress();
137
138
139
140  /**
141   * Gets the "buffer-size" property.
142   * <p>
143   * Specifies the size in bytes of the LDAP response message write
144   * buffer.
145   * <p>
146   * This property specifies write buffer size allocated by the server
147   * for each client connection and used to buffer LDAP response
148   * messages data when writing.
149   *
150   * @return Returns the value of the "buffer-size" property.
151   */
152  long getBufferSize();
153
154
155
156  /**
157   * Gets the "java-class" property.
158   * <p>
159   * Specifies the fully-qualified name of the Java class that
160   * provides the LDAP Connection Handler implementation.
161   *
162   * @return Returns the value of the "java-class" property.
163   */
164  String getJavaClass();
165
166
167
168  /**
169   * Gets the "keep-stats" property.
170   * <p>
171   * Indicates whether the LDAP Connection Handler should keep
172   * statistics.
173   * <p>
174   * If enabled, the LDAP Connection Handler maintains statistics
175   * about the number and types of operations requested over LDAP and
176   * the amount of data sent and received.
177   *
178   * @return Returns the value of the "keep-stats" property.
179   */
180  boolean isKeepStats();
181
182
183
184  /**
185   * Gets the "key-manager-provider" property.
186   * <p>
187   * Specifies the name of the key manager that should be used with
188   * this LDAP Connection Handler .
189   *
190   * @return Returns the value of the "key-manager-provider" property.
191   */
192  String getKeyManagerProvider();
193
194
195
196  /**
197   * Gets the "key-manager-provider" property as a DN.
198   * <p>
199   * Specifies the name of the key manager that should be used with
200   * this LDAP Connection Handler .
201   *
202   * @return Returns the DN value of the "key-manager-provider"
203   *         property.
204   */
205  DN getKeyManagerProviderDN();
206
207
208
209  /**
210   * Gets the "listen-address" property.
211   * <p>
212   * Specifies the address or set of addresses on which this LDAP
213   * Connection Handler should listen for connections from LDAP
214   * clients.
215   * <p>
216   * Multiple addresses may be provided as separate values for this
217   * attribute. If no values are provided, then the LDAP Connection
218   * Handler listens on all interfaces.
219   *
220   * @return Returns an unmodifiable set containing the values of the "listen-address" property.
221   */
222  SortedSet<InetAddress> getListenAddress();
223
224
225
226  /**
227   * Gets the "listen-port" property.
228   * <p>
229   * Specifies the port number on which the LDAP Connection Handler
230   * will listen for connections from clients.
231   * <p>
232   * Only a single port number may be provided.
233   *
234   * @return Returns the value of the "listen-port" property.
235   */
236  int getListenPort();
237
238
239
240  /**
241   * Gets the "max-blocked-write-time-limit" property.
242   * <p>
243   * Specifies the maximum length of time that attempts to write data
244   * to LDAP clients should be allowed to block.
245   * <p>
246   * If an attempt to write data to a client takes longer than this
247   * length of time, then the client connection is terminated.
248   *
249   * @return Returns the value of the "max-blocked-write-time-limit" property.
250   */
251  long getMaxBlockedWriteTimeLimit();
252
253
254
255  /**
256   * Gets the "max-request-size" property.
257   * <p>
258   * Specifies the size in bytes of the largest LDAP request message
259   * that will be allowed by this LDAP Connection handler.
260   * <p>
261   * This property is analogous to the maxBERSize configuration
262   * attribute of the Sun Java System Directory Server. This can help
263   * prevent denial-of-service attacks by clients that indicate they
264   * send extremely large requests to the server causing it to attempt
265   * to allocate large amounts of memory.
266   *
267   * @return Returns the value of the "max-request-size" property.
268   */
269  long getMaxRequestSize();
270
271
272
273  /**
274   * Gets the "num-request-handlers" property.
275   * <p>
276   * Specifies the number of request handlers that are used to read
277   * requests from clients.
278   * <p>
279   * The LDAP Connection Handler uses one thread to accept new
280   * connections from clients, but uses one or more additional threads
281   * to read requests from existing client connections. This ensures
282   * that new requests are read efficiently and that the connection
283   * handler itself does not become a bottleneck when the server is
284   * under heavy load from many clients at the same time.
285   *
286   * @return Returns the value of the "num-request-handlers" property.
287   */
288  Integer getNumRequestHandlers();
289
290
291
292  /**
293   * Gets the "send-rejection-notice" property.
294   * <p>
295   * Indicates whether the LDAP Connection Handler should send a
296   * notice of disconnection extended response message to the client if
297   * a new connection is rejected for some reason.
298   * <p>
299   * The extended response message may provide an explanation
300   * indicating the reason that the connection was rejected.
301   *
302   * @return Returns the value of the "send-rejection-notice" property.
303   */
304  boolean isSendRejectionNotice();
305
306
307
308  /**
309   * Gets the "ssl-cert-nickname" property.
310   * <p>
311   * Specifies the nicknames (also called the aliases) of the keys or
312   * key pairs that the LDAP Connection Handler should use when
313   * performing SSL communication. The property can be used multiple
314   * times (referencing different nicknames) when server certificates
315   * with different public key algorithms are used in parallel (for
316   * example, RSA, DSA, and ECC-based algorithms). When a nickname
317   * refers to an asymmetric (public/private) key pair, the nickname
318   * for the public key certificate and associated private key entry
319   * must match exactly. A single nickname is used to retrieve both the
320   * public key and the private key.
321   * <p>
322   * This is only applicable when the LDAP Connection Handler is
323   * configured to use SSL.
324   *
325   * @return Returns an unmodifiable set containing the values of the "ssl-cert-nickname" property.
326   */
327  SortedSet<String> getSSLCertNickname();
328
329
330
331  /**
332   * Gets the "ssl-cipher-suite" property.
333   * <p>
334   * Specifies the names of the SSL cipher suites that are allowed for
335   * use in SSL or StartTLS communication.
336   *
337   * @return Returns an unmodifiable set containing the values of the "ssl-cipher-suite" property.
338   */
339  SortedSet<String> getSSLCipherSuite();
340
341
342
343  /**
344   * Gets the "ssl-client-auth-policy" property.
345   * <p>
346   * Specifies the policy that the LDAP Connection Handler should use
347   * regarding client SSL certificates. Clients can use the SASL
348   * EXTERNAL mechanism only if the policy is set to "optional" or
349   * "required".
350   * <p>
351   * This is only applicable if clients are allowed to use SSL.
352   *
353   * @return Returns the value of the "ssl-client-auth-policy" property.
354   */
355  SSLClientAuthPolicy getSSLClientAuthPolicy();
356
357
358
359  /**
360   * Gets the "ssl-protocol" property.
361   * <p>
362   * Specifies the names of the SSL protocols that are allowed for use
363   * in SSL or StartTLS communication.
364   *
365   * @return Returns an unmodifiable set containing the values of the "ssl-protocol" property.
366   */
367  SortedSet<String> getSSLProtocol();
368
369
370
371  /**
372   * Gets the "trust-manager-provider" property.
373   * <p>
374   * Specifies the name of the trust manager that should be used with
375   * the LDAP Connection Handler .
376   *
377   * @return Returns the value of the "trust-manager-provider" property.
378   */
379  String getTrustManagerProvider();
380
381
382
383  /**
384   * Gets the "trust-manager-provider" property as a DN.
385   * <p>
386   * Specifies the name of the trust manager that should be used with
387   * the LDAP Connection Handler .
388   *
389   * @return Returns the DN value of the "trust-manager-provider"
390   *         property.
391   */
392  DN getTrustManagerProviderDN();
393
394
395
396  /**
397   * Gets the "use-ssl" property.
398   * <p>
399   * Indicates whether the LDAP Connection Handler should use SSL.
400   * <p>
401   * If enabled, the LDAP Connection Handler will use SSL to encrypt
402   * communication with the clients.
403   *
404   * @return Returns the value of the "use-ssl" property.
405   */
406  boolean isUseSSL();
407
408
409
410  /**
411   * Gets the "use-tcp-keep-alive" property.
412   * <p>
413   * Indicates whether the LDAP Connection Handler should use TCP
414   * keep-alive.
415   * <p>
416   * If enabled, the SO_KEEPALIVE socket option is used to indicate
417   * that TCP keepalive messages should periodically be sent to the
418   * client to verify that the associated connection is still valid.
419   * This may also help prevent cases in which intermediate network
420   * hardware could silently drop an otherwise idle client connection,
421   * provided that the keepalive interval configured in the underlying
422   * operating system is smaller than the timeout enforced by the
423   * network hardware.
424   *
425   * @return Returns the value of the "use-tcp-keep-alive" property.
426   */
427  boolean isUseTCPKeepAlive();
428
429
430
431  /**
432   * Gets the "use-tcp-no-delay" property.
433   * <p>
434   * Indicates whether the LDAP Connection Handler should use TCP
435   * no-delay.
436   * <p>
437   * If enabled, the TCP_NODELAY socket option is used to ensure that
438   * response messages to the client are sent immediately rather than
439   * potentially waiting to determine whether additional response
440   * messages can be sent in the same packet. In most cases, using the
441   * TCP_NODELAY socket option provides better performance and lower
442   * response times, but disabling it may help for some cases in which
443   * the server sends a large number of entries to a client in response
444   * to a search request.
445   *
446   * @return Returns the value of the "use-tcp-no-delay" property.
447   */
448  boolean isUseTCPNoDelay();
449
450}