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