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