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}