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-2015 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.Collection;
031import java.util.List;
032
033import javax.net.ssl.SSLContext;
034
035import org.forgerock.opendj.ldap.ByteString;
036import org.forgerock.opendj.ldap.DecodeException;
037import org.forgerock.opendj.ldap.DecodeOptions;
038import org.forgerock.opendj.ldap.controls.Control;
039import org.forgerock.opendj.ldap.controls.ControlDecoder;
040import org.forgerock.opendj.ldap.responses.ExtendedResult;
041import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
042
043/**
044 * The start TLS extended request as defined in RFC 4511. The Start Transport
045 * Layer Security (StartTLS) operation's purpose is to initiate installation of
046 * a TLS layer.
047 * <p>
048 * Use an {@link org.forgerock.opendj.ldap.SSLContextBuilder SSLContextBuilder}
049 * when setting up LDAP options needed to use StartTLS.
050 * {@link org.forgerock.opendj.ldap.TrustManagers TrustManagers} has methods you
051 * can use to set the trust manager for the SSL context builder.
052 *
053 * <pre>
054 * LDAPOptions options = new LDAPOptions();
055 * SSLContext sslContext =
056 *         new SSLContextBuilder().setTrustManager(...).getSSLContext();
057 * options.setSSLContext(sslContext);
058 * options.setUseStartTLS(true);
059 *
060 * String host = ...;
061 * int port = ...;
062 * LDAPConnectionFactory factory = new LDAPConnectionFactory(host, port, options);
063 * Connection connection = factory.getConnection();
064 * // Connection uses StartTLS...
065 * </pre>
066 *
067 * @see <a href="http://tools.ietf.org/html/rfc4511">RFC 4511 - Lightweight
068 *      Directory Access Protocol (LDAP): The Protocol </a>
069 */
070public interface StartTLSExtendedRequest extends ExtendedRequest<ExtendedResult> {
071
072    /**
073     * A decoder which can be used to decode start TLS extended operation
074     * requests.
075     */
076    ExtendedRequestDecoder<StartTLSExtendedRequest, ExtendedResult> DECODER =
077            new StartTLSExtendedRequestImpl.RequestDecoder();
078
079    /**
080     * The OID for the start TLS extended operation request.
081     */
082    String OID = "1.3.6.1.4.1.1466.20037";
083
084    @Override
085    StartTLSExtendedRequest addControl(Control control);
086
087    /**
088     * Adds the cipher suites enabled for secure connections with the Directory
089     * Server. The suites must be supported by the SSLContext specified in
090     * {@link #setSSLContext(SSLContext)}. Following a successful call to this
091     * method, only the suites listed in the protocols parameter are enabled for
092     * use.
093     *
094     * @param suites
095     *            Names of all the suites to enable.
096     * @return A reference to this LDAP connection options.
097     * @throws UnsupportedOperationException
098     *             If this start TLS extended request does not permit the
099     *             enabled cipher suites to be set.
100     */
101    StartTLSExtendedRequest addEnabledCipherSuite(String... suites);
102
103    /**
104     * Adds the cipher suites enabled for secure connections with the Directory
105     * Server. The suites must be supported by the SSLContext specified in
106     * {@link #setSSLContext(SSLContext)}. Following a successful call to this
107     * method, only the suites listed in the protocols parameter are enabled for
108     * use.
109     *
110     * @param suites
111     *            Names of all the suites to enable.
112     * @return A reference to this LDAP connection options.
113     * @throws UnsupportedOperationException
114     *             If this start TLS extended request does not permit the
115     *             enabled cipher suites to be set.
116     */
117    StartTLSExtendedRequest addEnabledCipherSuite(Collection<String> suites);
118
119    /**
120     * Adds the protocol versions enabled for secure connections with the
121     * Directory Server. The protocols must be supported by the SSLContext
122     * specified in {@link #setSSLContext(SSLContext)}. Following a successful
123     * call to this method, only the protocols listed in the protocols parameter
124     * are enabled for use.
125     *
126     * @param protocols
127     *            Names of all the protocols to enable.
128     * @return A reference to this LDAP connection options.
129     * @throws UnsupportedOperationException
130     *             If this start TLS extended request does not permit the
131     *             enabled protocols to be set.
132     */
133    StartTLSExtendedRequest addEnabledProtocol(String... protocols);
134
135    /**
136     * Adds the protocol versions enabled for secure connections with the
137     * Directory Server. The protocols must be supported by the SSLContext
138     * specified in {@link #setSSLContext(SSLContext)}. Following a successful
139     * call to this method, only the protocols listed in the protocols parameter
140     * are enabled for use.
141     *
142     * @param protocols
143     *            Names of all the protocols to enable.
144     * @return A reference to this LDAP connection options.
145     * @throws UnsupportedOperationException
146     *             If this start TLS extended request does not permit the
147     *             enabled protocols to be set.
148     */
149    StartTLSExtendedRequest addEnabledProtocol(Collection<String> protocols);
150
151    @Override
152    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
153            throws DecodeException;
154
155    @Override
156    List<Control> getControls();
157
158    /**
159     * Returns the names of the protocol versions which are currently enabled
160     * for secure connections with the Directory Server.
161     *
162     * @return an array of protocols or empty set if the default protocols are
163     *         to be used.
164     */
165    List<String> getEnabledCipherSuites();
166
167    /**
168     * Returns the names of the protocol versions which are currently enabled
169     * for secure connections with the Directory Server.
170     *
171     * @return an array of protocols or empty set if the default protocols are
172     *         to be used.
173     */
174    List<String> getEnabledProtocols();
175
176    @Override
177    String getOID();
178
179    @Override
180    ExtendedResultDecoder<ExtendedResult> getResultDecoder();
181
182    /**
183     * Returns the SSLContext that should be used when installing the TLS layer.
184     *
185     * @return The SSLContext that should be used when installing the TLS layer.
186     */
187    SSLContext getSSLContext();
188
189    @Override
190    ByteString getValue();
191
192    @Override
193    boolean hasValue();
194
195    /**
196     * Sets the SSLContext that should be used when installing the TLS layer.
197     *
198     * @param sslContext
199     *            The SSLContext that should be used when installing the TLS
200     *            layer.
201     * @return This startTLS request.
202     */
203    StartTLSExtendedRequest setSSLContext(SSLContext sslContext);
204}