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-2014 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.i18n.LocalizedIllegalArgumentException;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.LdapException;
026import org.forgerock.opendj.ldap.controls.Control;
027import org.forgerock.opendj.ldap.controls.ControlDecoder;
028
029/**
030 * The CRAM-MD5 SASL bind request as defined in draft-ietf-sasl-crammd5. This
031 * SASL mechanism allows a client to perform a simple challenge-response
032 * authentication method, using a keyed MD5 digest. This mechanism does not
033 * provide a security layer.
034 * <p>
035 * The CRAM-MD5 mechanism is intended to have limited use on the Internet. The
036 * mechanism offers inadequate protection against common attacks against
037 * application-level protocols and is prone to interoperability problems.
038 * <p>
039 * The authentication identity is specified using an authorization ID, or
040 * {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
041 *
042 * @see <a
043 *      href="http://tools.ietf.org/html/draft-ietf-sasl-crammd5">draft-ietf-sasl-crammd5
044 *      - The CRAM-MD5 SASL Mechanism </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 CRAMMD5SASLBindRequest extends SASLBindRequest {
049
050    /**
051     * The name of the SASL mechanism based on CRAM-MD5 authentication.
052     */
053    String SASL_MECHANISM_NAME = "CRAM-MD5";
054
055    @Override
056    CRAMMD5SASLBindRequest addControl(Control control);
057
058    @Override
059    BindClient createBindClient(String serverName) throws LdapException;
060
061    /**
062     * Returns the authentication ID of the user. The authentication ID usually
063     * has the form "dn:" immediately followed by the distinguished name of the
064     * user, or "u:" followed by a user ID string, but other forms are
065     * permitted.
066     *
067     * @return The authentication ID of the user.
068     */
069    String getAuthenticationID();
070
071    /**
072     * Returns the authentication mechanism identifier for this SASL bind
073     * request as defined by the LDAP protocol, which is always {@code 0xA3}.
074     *
075     * @return The authentication mechanism identifier.
076     */
077    @Override
078    byte getAuthenticationType();
079
080    @Override
081    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
082            throws DecodeException;
083
084    @Override
085    List<Control> getControls();
086
087    /**
088     * Returns the name of the Directory object that the client wishes to bind
089     * as, which is always the empty string for SASL authentication.
090     *
091     * @return The name of the Directory object that the client wishes to bind
092     *         as.
093     */
094    @Override
095    String getName();
096
097    /**
098     * Returns the password of the user that the client wishes to bind as.
099     * <p>
100     * Unless otherwise indicated, implementations will store a reference to the
101     * returned password byte array, allowing applications to overwrite the
102     * password after it has been used.
103     *
104     * @return The password of the user that the client wishes to bind as.
105     */
106    byte[] getPassword();
107
108    @Override
109    String getSASLMechanism();
110
111    /**
112     * Sets the authentication ID of the user. The authentication ID usually has
113     * the form "dn:" immediately followed by the distinguished name of the
114     * user, or "u:" followed by a user ID string, but other forms are
115     * permitted.
116     *
117     * @param authenticationID
118     *            The authentication ID of the user.
119     * @return This bind request
120     * @throws UnsupportedOperationException
121     *             If this bind request does not permit the authentication ID to
122     *             be set..
123     * @throws LocalizedIllegalArgumentException
124     *             If {@code authenticationID} was non-empty and did not contain
125     *             a valid authorization ID type.
126     * @throws NullPointerException
127     *             If {@code authenticationID} was {@code null}.
128     */
129    CRAMMD5SASLBindRequest setAuthenticationID(String authenticationID);
130
131    /**
132     * Sets the password of the user that the client wishes to bind as.
133     * <p>
134     * Unless otherwise indicated, implementations will store a reference to the
135     * provided password byte array, allowing applications to overwrite the
136     * password after it has been used.
137     *
138     * @param password
139     *            The password of the user that the client wishes to bind as,
140     *            which may be empty.
141     * @return This bind request.
142     * @throws UnsupportedOperationException
143     *             If this bind request does not permit the password to be set.
144     * @throws NullPointerException
145     *             If {@code password} was {@code null}.
146     */
147    CRAMMD5SASLBindRequest setPassword(byte[] password);
148
149    /**
150     * Sets the password of the user that the client wishes to bind as. The
151     * password will be converted to a UTF-8 octet string.
152     *
153     * @param password
154     *            The password of the user that the client wishes to bind as.
155     * @return This bind request.
156     * @throws UnsupportedOperationException
157     *             If this bind request does not permit the password to be set.
158     * @throws NullPointerException
159     *             If {@code password} was {@code null}.
160     */
161    CRAMMD5SASLBindRequest setPassword(char[] password);
162
163}