001/*
002 * Copyright 2022 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright 2022 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) 2022 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.unboundidds;
037
038
039
040import java.io.File;
041import java.io.Serializable;
042import java.util.concurrent.TimeUnit;
043
044import com.unboundid.util.Mutable;
045import com.unboundid.util.NotNull;
046import com.unboundid.util.ThreadSafety;
047import com.unboundid.util.ThreadSafetyLevel;
048import com.unboundid.util.Validator;
049
050
051
052/**
053 * This class defines a number of configuration properties that may be used by
054 * the {@link TopologyRegistryTrustManager}.
055 * <BR>
056 * <BLOCKQUOTE>
057 *   <B>NOTE:</B>  This class, and other classes within the
058 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
059 *   supported for use against Ping Identity, UnboundID, and
060 *   Nokia/Alcatel-Lucent 8661 server products.  These classes provide support
061 *   for proprietary functionality or for external specifications that are not
062 *   considered stable or mature enough to be guaranteed to work in an
063 *   interoperable way with other types of LDAP servers.
064 * </BLOCKQUOTE>
065 */
066@Mutable()
067@ThreadSafety(level=ThreadSafetyLevel.NOT_THREADSAFE)
068public final class TopologyRegistryTrustManagerProperties
069       implements Serializable
070{
071  /**
072   * The default cache duration in milliseconds.
073   */
074  private static final long DEFAULT_CACHE_DURATION_MILLIS =
075       TimeUnit.MINUTES.toMillis(5L);
076
077
078
079  /**
080   * The serial version UID for this serializable class.
081   */
082  private static final long serialVersionUID = -4753111539481801666L;
083
084
085
086  // Indicates whether to ignore the validity window for issuer certificates
087  // when determining whether to trust a certificate chain.
088  private boolean ignoreIssuerCertificateValidityWindow;
089
090  // Indicates whether to ignore the validity window for the peer certificate
091  // when determining whether to trust a certificate chain.
092  private boolean ignorePeerCertificateValidityWindow;
093
094  // Indicates whether to require the peer certificate itself to be included in
095  // the topology registry for a certificate chain to be trusted.
096  private boolean requirePeerCertificateInTopologyRegistry;
097
098  // The server configuration file from which the topology registry certificates
099  // will be read.
100  @NotNull private File configurationFile;
101
102  // The maximum length of time in milliseconds that previously loaded
103  // certificates may be cached.
104  private long cacheDurationMillis;
105
106
107
108  /**
109   * Creates a new topology registry trust manager properties object with the
110   * specified configuration file and the default settings for all other
111   * properties.  Default settings include:
112   * <UL>
113   *   <LI>cacheDurationMillis -- 300,000 (five minutes)</LI>
114   *   <LI>requirePeerCertificateInTopologyRegistry -- false</LI>
115   *   <LI>ignorePeerCertificateValidityWindow -- false</LI>
116   *   <LI>ignoreIssuerCertificateValidityWindow -- false</LI>
117   * </UL>
118   *
119   * @param  configurationFilePath  The path to the server configuration file
120   *                                from which the topology registry
121   *                                certificates will be read.  It must not be
122   *                                {@code null}, and the file must exist.
123   */
124  public TopologyRegistryTrustManagerProperties(
125              @NotNull final String configurationFilePath)
126  {
127    this(new File(configurationFilePath));
128  }
129
130
131
132  /**
133   * Creates a new topology registry trust manager properties object with the
134   * specified configuration file and the default settings for all other
135   * properties.  Default settings include:
136   * <UL>
137   *   <LI>cacheDurationMillis -- 300,000 (five minutes)</LI>
138   *   <LI>requirePeerCertificateInTopologyRegistry -- false</LI>
139   *   <LI>ignorePeerCertificateValidityWindow -- false</LI>
140   *   <LI>ignoreIssuerCertificateValidityWindow -- false</LI>
141   * </UL>
142   *
143   * @param  configurationFile  The server configuration file from which the
144   *                            topology registry certificates will be read.  It
145   *                            must not be {@code null}, and the file must
146   *                            exist.
147   */
148  public TopologyRegistryTrustManagerProperties(
149              @NotNull final File configurationFile)
150  {
151    Validator.ensureNotNull(configurationFile,
152         "TopologyRegistryTrustManagerProperties.configurationFile must not " +
153              "be null.");
154
155    this.configurationFile = configurationFile;
156
157    cacheDurationMillis = DEFAULT_CACHE_DURATION_MILLIS;
158    requirePeerCertificateInTopologyRegistry = false;
159    ignorePeerCertificateValidityWindow = false;
160    ignoreIssuerCertificateValidityWindow = false;
161  }
162
163
164
165  /**
166   * Retrieves the server configuration file from which the topology registry
167   * certificates will be read.
168   *
169   * @return  The server configuration file from which the topology registry
170   *          certificates will be read.
171   */
172  @NotNull()
173  public File getConfigurationFile()
174  {
175    return configurationFile;
176  }
177
178
179
180  /**
181   * Specifies the server configuration file from which the topology registry
182   * certificates will be read.
183   *
184   * @param  configurationFile  The server configuration file from which the
185   *                            topology registry certificates will be read.  It
186   *                            must not be {@code null}, and the file must
187   *                            exist.
188   */
189  public void setConfigurationFile(@NotNull final File configurationFile)
190  {
191    Validator.ensureNotNull(configurationFile,
192         "TopologyRegistryTrustManagerProperties.configurationFile must not " +
193              "be null.");
194
195    this.configurationFile = configurationFile;
196  }
197
198
199
200  /**
201   * Retrieves the maximum length of time in milliseconds that cached topology
202   * registry information should be considered valid.
203   *
204   * @return  The maximum length of time in milliseconds that cached topology
205   *          registry information should be considered valid, or zero if
206   *          topology registry information should not be cached.
207   */
208  public long getCacheDurationMillis()
209  {
210    return cacheDurationMillis;
211  }
212
213
214
215  /**
216   * Specifies the maximum length of time that cached topology registry
217   * information should be considered valid.
218   *
219   * @param  cacheDurationValue     The cache duration value to use with the
220   *                                given time unit.  If this is less than or
221   *                                equal to zero, then topology registry
222   *                                information will not be cached.
223   * @param  cacheDurationTimeUnit  The time unit to use with the given value.
224   *                                It must not be {@code null}.
225   */
226  public void setCacheDuration(final long cacheDurationValue,
227                               @NotNull final TimeUnit cacheDurationTimeUnit)
228  {
229    Validator.ensureNotNullWithMessage(cacheDurationTimeUnit,
230         "TopologyRegistryTrustManagerProperties.setCacheDuration." +
231              "cacheDurationTimeUnit must not be null.");
232
233    if (cacheDurationValue <= 0L)
234    {
235      cacheDurationMillis = 0L;
236    }
237    else
238    {
239      cacheDurationMillis = cacheDurationTimeUnit.toMillis(cacheDurationValue);
240    }
241  }
242
243
244
245  /**
246   * Indicates whether to require the peer certificate itself to be included in
247   * the topology registry for a certificate chain to be trusted.
248   *
249   * @return  {@code true} if a certificate chain may only be trusted if the
250   *          topology registry includes the peer certificate itself, or
251   *          {@code false} if a certificate chain may be trusted if the
252   *          topology registry contains the peer certificate or any of its
253   *          issuers.
254   */
255  public boolean requirePeerCertificateInTopologyRegistry()
256  {
257    return requirePeerCertificateInTopologyRegistry;
258  }
259
260
261
262  /**
263   * Specifies whether to require the peer certificate itself to be included in
264   * the topology registry for a certificate chain to be trusted.
265   *
266   * @param  requirePeerCertificateInTopologyRegistry
267   *              Indicates whether to require the peer certificate itself to be
268   *              included in the topology registry for a certificate chain to
269   *              be trusted.  If this is {@code true}, then a certificate chain
270   *              may be trusted only if the topology registry contains the
271   *              peer certificate itself.  If this is {@code false}, then a
272   *              certificate chain may be trusted if the topology registry
273   *              contains the peer certificate or any of its issuers.
274   */
275  public void setRequirePeerCertificateInTopologyRegistry(
276                   final boolean requirePeerCertificateInTopologyRegistry)
277  {
278    this.requirePeerCertificateInTopologyRegistry =
279         requirePeerCertificateInTopologyRegistry;
280  }
281
282
283
284  /**
285   * Indicates whether to ignore the validity window for the peer certificate
286   * when determining whether to trust a certificate chain.
287   *
288   * @return  {@code true} if a certificate chain may be considered trusted
289   *          even if the current time is outside the peer certificate's
290   *          validity window, or {@code false} if a certificate chain may only
291   *          be considered trusted if the current time is between the
292   *          {@code notBefore} and {@code notAfter} timestamps for the peer
293   *          certificate.
294   */
295  public boolean ignorePeerCertificateValidityWindow()
296  {
297    return ignorePeerCertificateValidityWindow;
298  }
299
300
301
302  /**
303   * Indicates whether to ignore the validity window for the peer certificate
304   * when determining whether to trust a certificate chain.
305   *
306   * @param  ignorePeerCertificateValidityWindow
307   *              Specifies whether to ignore the validity window for the peer
308   *              certificate when determining whether to trust a certificate
309   *              chain.  If this is {@code true}, then a certificate chain may
310   *              be trusted even if the current time is outside the peer
311   *              certificate's validity window.  If this is {@code false}, then
312   *              a certificate chain may only be trusted if the current time is
313   *              between the {@code notBefore} and {@code notAfter} timestamps
314   *              for the peer certificate.
315   */
316  public void setIgnorePeerCertificateValidityWindow(
317                   final boolean ignorePeerCertificateValidityWindow)
318  {
319    this.ignorePeerCertificateValidityWindow =
320         ignorePeerCertificateValidityWindow;
321  }
322
323
324
325  /**
326   * Indicates whether to ignore the validity window for issuer certificates
327   * when determining whether to trust a certificate chain.
328   *
329   * @return  {@code true} if a certificate chain may be considered trusted
330   *          even if the current time is outside the any issuer certificate's
331   *          validity window, or {@code false} if a certificate chain may only
332   *          be considered trusted if the current time is between the
333   *          {@code notBefore} and {@code notAfter} timestamps for all issuer
334   *          certificates.
335   */
336  public boolean ignoreIssuerCertificateValidityWindow()
337  {
338    return ignoreIssuerCertificateValidityWindow;
339  }
340
341
342
343  /**
344   * Indicates whether to ignore the validity window for the issuer certificates
345   * when determining whether to trust a certificate chain.
346   *
347   * @param  ignoreIssuerCertificateValidityWindow
348   *              Specifies whether to ignore the validity window for issuer
349   *              certificates when determining whether to trust a certificate
350   *              chain.  If this is {@code true}, then a certificate chain may
351   *              be trusted even if the current time is outside any issuer
352   *              certificate's validity window.  If this is {@code false}, then
353   *              a certificate chain may only be trusted if the current time is
354   *              between the {@code notBefore} and {@code notAfter} timestamps
355   *              for all issuer certificate.
356   */
357  public void setIgnoreIssuerCertificateValidityWindow(
358                   final boolean ignoreIssuerCertificateValidityWindow)
359  {
360    this.ignoreIssuerCertificateValidityWindow =
361         ignoreIssuerCertificateValidityWindow;
362  }
363
364
365
366  /**
367   * Retrieves a string representation of the topology registry trust manager
368   * properties.
369   *
370   * @return  A string representation of the topology registry trust manager
371   *          properties.
372   */
373  @Override()
374  @NotNull()
375  public String toString()
376  {
377    final StringBuilder buffer = new StringBuilder();
378    toString(buffer);
379    return buffer.toString();
380  }
381
382
383
384  /**
385   * Appends a string representation of the topology registry trust manager
386   * properties to the given buffer.
387   *
388   * @param  buffer  The buffer to which the string representation should be
389   *                 appended.
390   */
391  public void toString(@NotNull final StringBuilder buffer)
392  {
393    buffer.append("TopologyRegistryTrustManagerProperties(configurationFile='");
394    buffer.append(configurationFile.getAbsolutePath());
395    buffer.append("', cacheDurationMillis=");
396    buffer.append(cacheDurationMillis);
397    buffer.append(", requirePeerCertificateInTopologyRegistry=");
398    buffer.append(requirePeerCertificateInTopologyRegistry);
399    buffer.append(", ignorePeerCertificateValidityWindow=");
400    buffer.append(ignorePeerCertificateValidityWindow);
401    buffer.append(", ignoreIssuerCertificateValidityWindow=");
402    buffer.append(ignoreIssuerCertificateValidityWindow);
403    buffer.append(')');
404  }
405}