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