001    /*
002     * Copyright 2014-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2014-2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk;
022    
023    
024    
025    import java.io.Serializable;
026    import java.util.ArrayList;
027    import java.util.Arrays;
028    import java.util.Collections;
029    import java.util.List;
030    
031    import com.unboundid.asn1.ASN1OctetString;
032    import com.unboundid.util.Mutable;
033    import com.unboundid.util.StaticUtils;
034    import com.unboundid.util.ThreadSafety;
035    import com.unboundid.util.ThreadSafetyLevel;
036    import com.unboundid.util.Validator;
037    
038    
039    
040    /**
041     * This class provides a data structure that may be used to hold a number of
042     * properties that may be used during processing for a SASL DIGEST-MD5 bind
043     * operation.
044     */
045    @Mutable()
046    @ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
047    public final class DIGESTMD5BindRequestProperties
048           implements Serializable
049    {
050      /**
051       * The serial version UID for this serializable class.
052       */
053      private static final long serialVersionUID = -2000440962628192477L;
054    
055    
056    
057      // The password for the DIGEST-MD5 bind request.
058      private ASN1OctetString password;
059    
060      // The SASL quality of protection value(s) allowed for the DIGEST-MD5 bind
061      // request.
062      private List<SASLQualityOfProtection> allowedQoP;
063    
064      // The authentication ID string for the DIGEST-MD5 bind request.
065      private String authenticationID;
066    
067      // The authorization ID string for the DIGEST-MD5 bind request, if available.
068      private String authorizationID;
069    
070      // The realm for the DIGEST-MD5 bind request, if available.
071      private String realm;
072    
073    
074    
075      /**
076       * Creates a new set of DIGEST-MD5 bind request properties with the provided
077       * information.
078       *
079       * @param  authenticationID  The authentication ID for the DIGEST-MD5 bind
080       *                           request.  It must not be {@code null}.
081       * @param  password          The password for the DIGEST-MD5 bind request.  It
082       *                           may be {@code null} if anonymous authentication
083       *                           is to be performed.
084       */
085      public DIGESTMD5BindRequestProperties(final String authenticationID,
086                                            final String password)
087      {
088        this(authenticationID, new ASN1OctetString(password));
089      }
090    
091    
092    
093      /**
094       * Creates a new set of DIGEST-MD5 bind request properties with the provided
095       * information.
096       *
097       * @param  authenticationID  The authentication ID for the DIGEST-MD5 bind
098       *                           request.  It must not be {@code null}.
099       * @param  password          The password for the DIGEST-MD5 bind request.  It
100       *                           may be {@code null} if anonymous authentication
101       *                           is to be performed.
102       */
103      public DIGESTMD5BindRequestProperties(final String authenticationID,
104                                            final byte[] password)
105      {
106        this(authenticationID, new ASN1OctetString(password));
107      }
108    
109    
110    
111      /**
112       * Creates a new set of DIGEST-MD5 bind request properties with the provided
113       * information.
114       *
115       * @param  authenticationID  The authentication ID for the DIGEST-MD5 bind
116       *                           request.  It must not be {@code null}.
117       * @param  password          The password for the DIGEST-MD5 bind request.  It
118       *                           may be {@code null} if anonymous authentication
119       *                           is to be performed.
120       */
121      public DIGESTMD5BindRequestProperties(final String authenticationID,
122                                            final ASN1OctetString password)
123      {
124        Validator.ensureNotNull(authenticationID);
125    
126        this.authenticationID = authenticationID;
127    
128        if (password == null)
129        {
130          this.password = new ASN1OctetString();
131        }
132        else
133        {
134          this.password = password;
135        }
136    
137        authorizationID = null;
138        realm           = null;
139        allowedQoP      = Collections.unmodifiableList(Arrays.asList(
140             SASLQualityOfProtection.AUTH));
141      }
142    
143    
144    
145      /**
146       * Retrieves the authentication ID for the DIGEST-MD5 bind request.
147       *
148       * @return  The authentication ID for the DIGEST-MD5 bind request.
149       */
150      public String getAuthenticationID()
151      {
152        return authenticationID;
153      }
154    
155    
156    
157      /**
158       * Specifies the authentication ID for the DIGEST-MD5 bind request.  It must
159       * not be {@code null}, and should generally start with "dn:" followed by the
160       * full DN for the target user (or just "dn:" for anonymous), or "u:" followed
161       * by the username for the target user.
162       *
163       * @param  authenticationID  The authentication ID for the DIGEST-MD5 bind
164       *                           request.  It must not be {@code null}.
165       */
166      public void setAuthenticationID(final String authenticationID)
167      {
168        Validator.ensureNotNull(authenticationID);
169        this.authenticationID = authenticationID;
170      }
171    
172    
173    
174      /**
175       * Retrieves the authorization ID for the DIGEST-MD5 bind request.
176       *
177       * @return  The authorization ID for the DIGEST-MD5 bind request, or
178       *          {@code null} if no authorization ID should be included in the
179       *          bind request.
180       */
181      public String getAuthorizationID()
182      {
183        return authorizationID;
184      }
185    
186    
187    
188      /**
189       * Specifies the authorization ID for the DIGEST-MD5 bind request.  It may be
190       * {@code null} if not alternate authorization identity is needed.  If
191       * provided, the authorization ID should generally start with "dn:" followed
192       * by the full DN for the target user (or just "dn:" for anonymous), or "u:"
193       * followed by the username for the target user.
194       *
195       * @param  authorizationID  The authorization ID for the DIGEST-MD5 bind
196       *                          request.
197       */
198      public void setAuthorizationID(final String authorizationID)
199      {
200        this.authorizationID = authorizationID;
201      }
202    
203    
204    
205      /**
206       * Retrieves the password for the DIGEST-MD5 bind request.
207       *
208       * @return  The password for the DIGEST-MD5 bind request.
209       */
210      public ASN1OctetString getPassword()
211      {
212        return password;
213      }
214    
215    
216    
217      /**
218       * Specifies the password for the DIGEST-MD5 bind request.  It may be
219       * {@code null} or empty when authenticating as the anonymous user.
220       *
221       * @param  password  The password for the DIGEST-MD5 bind request.  It may be
222       *                   {@code null} or empty when authenticating as the
223       *                   anonymous user.
224       */
225      public void setPassword(final String password)
226      {
227        setPassword(new ASN1OctetString(password));
228      }
229    
230    
231    
232      /**
233       * Specifies the password for the DIGEST-MD5 bind request.  It may be
234       * {@code null} or empty when authenticating as the anonymous user.
235       *
236       * @param  password  The password for the DIGEST-MD5 bind request.  It may be
237       *                   {@code null} or empty when authenticating as the
238       *                   anonymous user.
239       */
240      public void setPassword(final byte[] password)
241      {
242        setPassword(new ASN1OctetString(password));
243      }
244    
245    
246    
247      /**
248       * Specifies the password for the DIGEST-MD5 bind request.  It may be
249       * {@code null} or empty when authenticating as the anonymous user.
250       *
251       * @param  password  The password for the DIGEST-MD5 bind request.  It may be
252       *                   {@code null} or empty when authenticating as the
253       *                   anonymous user.
254       */
255      public void setPassword(final ASN1OctetString password)
256      {
257        if (password == null)
258        {
259          this.password = new ASN1OctetString();
260        }
261        else
262        {
263          this.password = password;
264        }
265      }
266    
267    
268    
269    
270      /**
271       * Retrieves the realm for the DIGEST-MD5 bind request.
272       *
273       * @return  The realm for the DIGEST-MD5 bind request, or {@code null} if no
274       *          realm should be included in the bind request.
275       */
276      public String getRealm()
277      {
278        return realm;
279      }
280    
281    
282    
283      /**
284       * Specifies the realm for the DIGEST-MD5 bind request.  It may be
285       * {@code null} if no realm should be included in the bind request.
286       *
287       * @param  realm  The realm for the DIGEST-MD5 bind request.  It may be
288       *                {@code null} if no realm should be included in the bind
289       *                request.
290       */
291      public void setRealm(final String realm)
292      {
293        this.realm = realm;
294      }
295    
296    
297    
298      /**
299       * Retrieves the list of allowed qualities of protection that may be used for
300       * communication that occurs on the connection after the authentication has
301       * completed, in order from most preferred to least preferred.
302       *
303       * @return  The list of allowed qualities of protection that may be used for
304       *          communication that occurs on the connection after the
305       *          authentication has completed, in order from most preferred to
306       *          least preferred.
307       */
308      public List<SASLQualityOfProtection> getAllowedQoP()
309      {
310        return allowedQoP;
311      }
312    
313    
314    
315      /**
316       * Specifies the list of allowed qualities of protection that may be used for
317       * communication that occurs on the connection after the authentication has
318       * completed, in order from most preferred to least preferred.
319       *
320       * @param  allowedQoP  The list of allowed qualities of protection that may be
321       *                     used for communication that occurs on the connection
322       *                     after the authentication has completed, in order from
323       *                     most preferred to least preferred.  If this is
324       *                     {@code null} or empty, then a list containing only the
325       *                     {@link SASLQualityOfProtection#AUTH} quality of
326       *                     protection value will be used.
327       */
328      public void setAllowedQoP(final List<SASLQualityOfProtection> allowedQoP)
329      {
330        if ((allowedQoP == null) || allowedQoP.isEmpty())
331        {
332          this.allowedQoP = Collections.unmodifiableList(Arrays.asList(
333               SASLQualityOfProtection.AUTH));
334        }
335        else
336        {
337          this.allowedQoP = Collections.unmodifiableList(
338               new ArrayList<SASLQualityOfProtection>(allowedQoP));
339        }
340      }
341    
342    
343    
344      /**
345       * Specifies the list of allowed qualities of protection that may be used for
346       * communication that occurs on the connection after the authentication has
347       * completed, in order from most preferred to least preferred.
348       *
349       * @param  allowedQoP  The list of allowed qualities of protection that may be
350       *                     used for communication that occurs on the connection
351       *                     after the authentication has completed, in order from
352       *                     most preferred to least preferred.  If this is
353       *                     {@code null} or empty, then a list containing only the
354       *                     {@link SASLQualityOfProtection#AUTH} quality of
355       *                     protection value will be used.
356       */
357      public void setAllowedQoP(final SASLQualityOfProtection... allowedQoP)
358      {
359        setAllowedQoP(StaticUtils.toList(allowedQoP));
360      }
361    
362    
363    
364      /**
365       * Retrieves a string representation of the GSSAPI bind request properties.
366       *
367       * @return  A string representation of the GSSAPI bind request properties.
368       */
369      @Override()
370      public String toString()
371      {
372        final StringBuilder buffer = new StringBuilder();
373        toString(buffer);
374        return buffer.toString();
375      }
376    
377    
378    
379      /**
380       * Appends a string representation of the GSSAPI bind request properties to
381       * the provided buffer.
382       *
383       * @param  buffer  The buffer to which the information should be appended.
384       */
385      public void toString(final StringBuilder buffer)
386      {
387        buffer.append("DIGESTMD5BindRequestProperties(authenticationID='");
388        buffer.append(authenticationID);
389        buffer.append('\'');
390    
391        if (authorizationID != null)
392        {
393          buffer.append(", authorizationID='");
394          buffer.append(authorizationID);
395          buffer.append('\'');
396        }
397    
398        if (realm != null)
399        {
400          buffer.append(", realm='");
401          buffer.append(realm);
402          buffer.append('\'');
403        }
404    
405        buffer.append(", qop='");
406        buffer.append(SASLQualityOfProtection.toString(allowedQoP));
407        buffer.append("')");
408      }
409    }