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