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 2011-2014 ForgeRock AS
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031import java.util.Map;
032
033import javax.security.auth.Subject;
034
035import org.forgerock.i18n.LocalizedIllegalArgumentException;
036import org.forgerock.opendj.ldap.DecodeException;
037import org.forgerock.opendj.ldap.DecodeOptions;
038import org.forgerock.opendj.ldap.LdapException;
039import org.forgerock.opendj.ldap.controls.Control;
040import org.forgerock.opendj.ldap.controls.ControlDecoder;
041
042/**
043 * The GSSAPI SASL bind request as defined in RFC 2831. This SASL mechanism
044 * allows a client to use the Generic Security Service Application Program
045 * Interface (GSS-API) Kerberos V5 to authenticate to the server. This mechanism
046 * can be used to negotiate integrity and/or privacy protection for the
047 * underlying connection.
048 * <p>
049 * The optional authorization identity is specified using an authorization ID,
050 * or {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
051 *
052 * @see <a href="http://tools.ietf.org/html/rfc4752">RFC 4752 - The Kerberos V5
053 *      ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism
054 *      </a>
055 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
056 *      SASL Authorization Identities (authzId) </a>
057 */
058public interface GSSAPISASLBindRequest extends SASLBindRequest {
059
060    /**
061     * Indicates that the client will accept authentication only. More
062     * specifically, the underlying connection will not be protected using
063     * integrity protection or encryption, unless previously established using
064     * SSL/TLS. This is the default if no QOP option is present in the bind
065     * request.
066     */
067    String QOP_AUTH = "auth";
068
069    /**
070     * Indicates that the client will accept authentication with connection
071     * integrity protection and encryption.
072     */
073    String QOP_AUTH_CONF = "auth-conf";
074
075    /**
076     * Indicates that the client will accept authentication with connection
077     * integrity protection. More specifically, the underlying connection will
078     * not be encrypted, unless previously established using SSL/TLS.
079     */
080    String QOP_AUTH_INT = "auth-int";
081
082    /**
083     * The name of the SASL mechanism based on GSS-API authentication.
084     */
085    String SASL_MECHANISM_NAME = "GSSAPI";
086
087    /**
088     * Adds the provided additional authentication parameter to the list of
089     * parameters to be passed to the underlying mechanism implementation. This
090     * method is provided in order to allow for future extensions.
091     *
092     * @param name
093     *            The name of the additional authentication parameter.
094     * @param value
095     *            The value of the additional authentication parameter.
096     * @return This bind request.
097     * @throws UnsupportedOperationException
098     *             If this bind request does not permit additional
099     *             authentication parameters to be added.
100     * @throws NullPointerException
101     *             If {@code name} or {@code value} was {@code null}.
102     */
103    GSSAPISASLBindRequest addAdditionalAuthParam(String name, String value);
104
105    @Override
106    GSSAPISASLBindRequest addControl(Control control);
107
108    /**
109     * Adds the provided quality of protection (QOP) values to the ordered list
110     * of QOP values that the client is willing to accept. The order of the list
111     * specifies the preference order, high to low. Authentication will fail if
112     * no QOP values are recognized or accepted by the server.
113     * <p>
114     * By default the client will accept {@link #QOP_AUTH AUTH}.
115     *
116     * @param qopValues
117     *            The quality of protection values that the client is willing to
118     *            accept.
119     * @return This bind request.
120     * @throws UnsupportedOperationException
121     *             If this bind request does not permit QOP values to be added.
122     * @throws NullPointerException
123     *             If {@code qopValues} was {@code null}.
124     * @see #QOP_AUTH
125     * @see #QOP_AUTH_INT
126     * @see #QOP_AUTH_CONF
127     */
128    GSSAPISASLBindRequest addQOP(String... qopValues);
129
130    @Override
131    BindClient createBindClient(String serverName) throws LdapException;
132
133    /**
134     * Returns a map containing the provided additional authentication
135     * parameters to be passed to the underlying mechanism implementation. This
136     * method is provided in order to allow for future extensions.
137     *
138     * @return A map containing the provided additional authentication
139     *         parameters to be passed to the underlying mechanism
140     *         implementation.
141     */
142    Map<String, String> getAdditionalAuthParams();
143
144    /**
145     * Returns the authentication ID of the user, which should be the user's
146     * Kerberos principal. The authentication ID usually has the form "dn:"
147     * immediately followed by the distinguished name of the user, or "u:"
148     * followed by a user ID string, but other forms are permitted.
149     * <p>
150     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
151     *
152     * @return The authentication ID of the user.
153     */
154    String getAuthenticationID();
155
156    /**
157     * Returns the authentication mechanism identifier for this SASL bind
158     * request as defined by the LDAP protocol, which is always {@code 0xA3}.
159     *
160     * @return The authentication mechanism identifier.
161     */
162    @Override
163    byte getAuthenticationType();
164
165    /**
166     * Returns the optional authorization ID of the user which represents an
167     * alternate authorization identity which should be used for subsequent
168     * operations performed on the connection. The authorization ID usually has
169     * the form "dn:" immediately followed by the distinguished name of the
170     * user, or "u:" followed by a user ID string, but other forms are
171     * permitted.
172     *
173     * @return The authorization ID of the user, which may be {@code null}.
174     */
175    String getAuthorizationID();
176
177    @Override
178    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
179            throws DecodeException;
180
181    @Override
182    List<Control> getControls();
183
184    /**
185     * Returns the optional address of the Kerberos KDC (Key Distribution
186     * Center).
187     * <p>
188     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
189     *
190     * @return The address of the Kerberos KDC (Key Distribution Center), which
191     *         may be {@code null}.
192     */
193    String getKDCAddress();
194
195    /**
196     * Returns the maximum size of the receive buffer in bytes. The actual
197     * maximum number of bytes will be the minimum of this number and the peer's
198     * maximum send buffer size. The default size is 65536.
199     *
200     * @return The maximum size of the receive buffer in bytes.
201     */
202    int getMaxReceiveBufferSize();
203
204    /**
205     * Returns the maximum size of the send buffer in bytes. The actual maximum
206     * number of bytes will be the minimum of this number and the peer's maximum
207     * receive buffer size. The default size is 65536.
208     *
209     * @return The maximum size of the send buffer in bytes.
210     */
211    int getMaxSendBufferSize();
212
213    /**
214     * Returns the name of the Directory object that the client wishes to bind
215     * as, which is always the empty string for SASL authentication.
216     *
217     * @return The name of the Directory object that the client wishes to bind
218     *         as.
219     */
220    @Override
221    String getName();
222
223    /**
224     * Returns the password of the user that the client wishes to bind as.
225     * <p>
226     * Unless otherwise indicated, implementations will store a reference to the
227     * returned password byte array, allowing applications to overwrite the
228     * password after it has been used.
229     * <p>
230     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
231     *
232     * @return The password of the user that the client wishes to bind as.
233     */
234    byte[] getPassword();
235
236    /**
237     * Returns the ordered list of quality of protection (QOP) values that the
238     * client is willing to accept. The order of the list specifies the
239     * preference order, high to low. Authentication will fail if no QOP values
240     * are recognized or accepted by the server.
241     * <p>
242     * By default the client will accept {@link #QOP_AUTH AUTH}.
243     *
244     * @return The list of quality of protection values that the client is
245     *         willing to accept. The returned list may be empty indicating that
246     *         the default QOP will be accepted.
247     */
248    List<String> getQOPs();
249
250    /**
251     * Returns the optional realm containing the user's account.
252     * <p>
253     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
254     *
255     * @return The name of the realm containing the user's account, which may be
256     *         {@code null}.
257     */
258    String getRealm();
259
260    @Override
261    String getSASLMechanism();
262
263    /**
264     * Returns the Kerberos subject of the user to be authenticated.
265     * <p>
266     * <b>NOTE</b>: if a {@code Subject} is specified then the authentication
267     * ID, KDC address, password, and realm, will be ignored.
268     *
269     * @return The Kerberos subject of the user to be authenticated.
270     */
271    Subject getSubject();
272
273    /**
274     * Returns {@code true} if the server must authenticate to the client. The
275     * default is {@code false}.
276     *
277     * @return {@code true} if the server must authenticate to the client.
278     */
279    boolean isServerAuth();
280
281    /**
282     * Sets the authentication ID of the user, which should be the user's
283     * Kerberos principal. The authentication ID usually has the form "dn:"
284     * immediately followed by the distinguished name of the user, or "u:"
285     * followed by a user ID string, but other forms are permitted.
286     * <p>
287     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
288     *
289     * @param authenticationID
290     *            The authentication ID of the user.
291     * @return This bind request.
292     * @throws LocalizedIllegalArgumentException
293     *             If {@code authenticationID} was non-empty and did not contain
294     *             a valid authorization ID type.
295     * @throws NullPointerException
296     *             If {@code authenticationID} was {@code null}.
297     */
298    GSSAPISASLBindRequest setAuthenticationID(String authenticationID);
299
300    /**
301     * Sets the optional authorization ID of the user which represents an
302     * alternate authorization identity which should be used for subsequent
303     * operations performed on the connection. The authorization ID usually has
304     * the form "dn:" immediately followed by the distinguished name of the
305     * user, or "u:" followed by a user ID string, but other forms are
306     * permitted.
307     *
308     * @param authorizationID
309     *            The authorization ID of the user, which may be {@code null}.
310     * @return This bind request.
311     * @throws LocalizedIllegalArgumentException
312     *             If {@code authorizationID} was non-empty and did not contain
313     *             a valid authorization ID type.
314     */
315    GSSAPISASLBindRequest setAuthorizationID(String authorizationID);
316
317    /**
318     * Sets the optional address of the Kerberos KDC (Key Distribution Center).
319     * <p>
320     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
321     *
322     * @param address
323     *            The address of the Kerberos KDC (Key Distribution Center),
324     *            which may be {@code null}.
325     * @return This bind request.
326     * @throws UnsupportedOperationException
327     *             If this bind request does not permit the KDC address to be
328     *             set.
329     * @throws NullPointerException
330     *             If {@code address} was {@code null}.
331     */
332    GSSAPISASLBindRequest setKDCAddress(String address);
333
334    /**
335     * Sets the maximum size of the receive buffer in bytes. The actual maximum
336     * number of bytes will be the minimum of this number and the peer's maximum
337     * send buffer size. The default size is 65536.
338     *
339     * @param size
340     *            The maximum size of the receive buffer in bytes.
341     * @return This bind request.
342     * @throws UnsupportedOperationException
343     *             If this bind request does not permit the buffer size to be
344     *             set.
345     */
346    GSSAPISASLBindRequest setMaxReceiveBufferSize(int size);
347
348    /**
349     * Sets the maximum size of the send buffer in bytes. The actual maximum
350     * number of bytes will be the minimum of this number and the peer's maximum
351     * receive buffer size. The default size is 65536.
352     *
353     * @param size
354     *            The maximum size of the send buffer in bytes.
355     * @return This bind request.
356     * @throws UnsupportedOperationException
357     *             If this bind request does not permit the buffer size to be
358     *             set.
359     */
360    GSSAPISASLBindRequest setMaxSendBufferSize(int size);
361
362    /**
363     * Sets the password of the user that the client wishes to bind as.
364     * <p>
365     * Unless otherwise indicated, implementations will store a reference to the
366     * provided password byte array, allowing applications to overwrite the
367     * password after it has been used.
368     * <p>
369     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
370     *
371     * @param password
372     *            The password of the user that the client wishes to bind as,
373     *            which may be empty.
374     * @return This bind request.
375     * @throws UnsupportedOperationException
376     *             If this bind request does not permit the password to be set.
377     * @throws NullPointerException
378     *             If {@code password} was {@code null}.
379     */
380    GSSAPISASLBindRequest setPassword(byte[] password);
381
382    /**
383     * Sets the password of the user that the client wishes to bind as. The
384     * password will be converted to a UTF-8 octet string.
385     * <p>
386     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
387     *
388     * @param password
389     *            The password of the user that the client wishes to bind as.
390     * @return This bind request.
391     * @throws UnsupportedOperationException
392     *             If this bind request does not permit the password to be set.
393     * @throws NullPointerException
394     *             If {@code password} was {@code null}.
395     */
396    GSSAPISASLBindRequest setPassword(char[] password);
397
398    /**
399     * Sets the optional realm containing the user's account.
400     * <p>
401     * <b>NOTE</b>: this will not be used if a {@code Subject} is specified.
402     *
403     * @param realm
404     *            The name of the realm containing the user's account, which may
405     *            be {@code null}.
406     * @return This bind request.
407     * @throws UnsupportedOperationException
408     *             If this bind request does not permit the realm to be set.
409     * @throws NullPointerException
410     *             If {@code realm} was {@code null}.
411     */
412    GSSAPISASLBindRequest setRealm(String realm);
413
414    /**
415     * Specifies whether or not the server must authenticate to the client. The
416     * default is {@code false}.
417     *
418     * @param serverAuth
419     *            {@code true} if the server must authenticate to the client or
420     *            {@code false} otherwise.
421     * @return This bind request.
422     * @throws UnsupportedOperationException
423     *             If this bind request does not permit server auth to be set.
424     */
425    GSSAPISASLBindRequest setServerAuth(boolean serverAuth);
426
427    /**
428     * Sets the Kerberos subject of the user to be authenticated.
429     * <p>
430     * <b>NOTE</b>: if a {@code Subject} is specified then the authentication
431     * ID, KDC address, password, and realm, will be ignored.
432     *
433     * @param subject
434     *            The Kerberos subject of the user to be authenticated.
435     * @return This bind request.
436     * @throws UnsupportedOperationException
437     *             If this bind request does not permit the Kerberos subject to
438     *             be set.
439     * @throws NullPointerException
440     *             If {@code subject} was {@code null}.
441     */
442    GSSAPISASLBindRequest setSubject(Subject subject);
443}