001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2010 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031
032import javax.net.ssl.SSLContext;
033
034import org.forgerock.opendj.ldap.ByteString;
035import org.forgerock.opendj.ldap.DecodeException;
036import org.forgerock.opendj.ldap.DecodeOptions;
037import org.forgerock.opendj.ldap.controls.Control;
038import org.forgerock.opendj.ldap.controls.ControlDecoder;
039import org.forgerock.opendj.ldap.responses.ExtendedResult;
040import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
041
042/**
043 * The start TLS extended request as defined in RFC 4511. The Start Transport
044 * Layer Security (StartTLS) operation's purpose is to initiate installation of
045 * a TLS layer.
046 * <p>
047 * Use an {@link org.forgerock.opendj.ldap.SSLContextBuilder SSLContextBuilder}
048 * when setting up LDAP options needed to use StartTLS.
049 * {@link org.forgerock.opendj.ldap.TrustManagers TrustManagers} has methods you
050 * can use to set the trust manager for the SSL context builder.
051 *
052 * <pre>
053 * LDAPOptions options = new LDAPOptions();
054 * SSLContext sslContext =
055 *         new SSLContextBuilder().setTrustManager(...).getSSLContext();
056 * options.setSSLContext(sslContext);
057 * options.setUseStartTLS(true);
058 *
059 * String host = ...;
060 * int port = ...;
061 * LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port, options);
062 * Connection connection = factory.getConnection();
063 * // Connection uses StartTLS...
064 * </pre>
065 *
066 * @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
067 *      Directory Access Protocol (LDAP): The Protocol </a>
068 */
069public interface StartTLSExtendedRequest extends ExtendedRequest<ExtendedResult> {
070
071    /**
072     * A decoder which can be used to decode start TLS extended operation
073     * requests.
074     */
075    ExtendedRequestDecoder<StartTLSExtendedRequest, ExtendedResult> DECODER =
076            new StartTLSExtendedRequestImpl.RequestDecoder();
077
078    /**
079     * The OID for the start TLS extended operation request.
080     */
081    String OID = "1.3.6.1.4.1.1466.20037";
082
083    @Override
084    StartTLSExtendedRequest addControl(Control control);
085
086    /**
087     * Adds the cipher suites enabled for secure connections with the Directory
088     * Server. The suites must be supported by the SSLContext specified in
089     * {@link #setSSLContext(SSLContext)}. Following a successful call to this
090     * method, only the suites listed in the protocols parameter are enabled for
091     * use.
092     *
093     * @param suites
094     *            Names of all the suites to enable.
095     * @return A reference to this LDAP connection options.
096     * @throws UnsupportedOperationException
097     *             If this start TLS extended request does not permit the
098     *             enabled cipher suites to be set.
099     */
100    StartTLSExtendedRequest addEnabledCipherSuite(String... suites);
101
102    /**
103     * Adds the protocol versions enabled for secure connections with the
104     * Directory Server. The protocols must be supported by the SSLContext
105     * specified in {@link #setSSLContext(SSLContext)}. Following a successful
106     * call to this method, only the protocols listed in the protocols parameter
107     * are enabled for use.
108     *
109     * @param protocols
110     *            Names of all the protocols to enable.
111     * @return A reference to this LDAP connection options.
112     * @throws UnsupportedOperationException
113     *             If this start TLS extended request does not permit the
114     *             enabled protocols to be set.
115     */
116    StartTLSExtendedRequest addEnabledProtocol(String... protocols);
117
118    @Override
119    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
120            throws DecodeException;
121
122    @Override
123    List<Control> getControls();
124
125    /**
126     * Returns the names of the protocol versions which are currently enabled
127     * for secure connections with the Directory Server.
128     *
129     * @return an array of protocols or empty set if the default protocols are
130     *         to be used.
131     */
132    List<String> getEnabledCipherSuites();
133
134    /**
135     * Returns the names of the protocol versions which are currently enabled
136     * for secure connections with the Directory Server.
137     *
138     * @return an array of protocols or empty set if the default protocols are
139     *         to be used.
140     */
141    List<String> getEnabledProtocols();
142
143    @Override
144    String getOID();
145
146    @Override
147    ExtendedResultDecoder<ExtendedResult> getResultDecoder();
148
149    /**
150     * Returns the SSLContext that should be used when installing the TLS layer.
151     *
152     * @return The SSLContext that should be used when installing the TLS layer.
153     */
154    SSLContext getSSLContext();
155
156    @Override
157    ByteString getValue();
158
159    @Override
160    boolean hasValue();
161
162    /**
163     * Sets the SSLContext that should be used when installing the TLS layer.
164     *
165     * @param sslContext
166     *            The SSLContext that should be used when installing the TLS
167     *            layer.
168     * @return This startTLS request.
169     */
170    StartTLSExtendedRequest setSSLContext(SSLContext sslContext);
171}