001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Portions Copyright 2021-2023 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.common.api;
028
029
030
031import java.util.Collections;
032import java.util.List;
033import java.util.Map;
034
035import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
036import com.unboundid.directory.sdk.common.config.PassphraseProviderConfig;
037import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
038import com.unboundid.directory.sdk.common.internal.Reconfigurable;
039import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
040import com.unboundid.directory.sdk.common.types.ServerContext;
041import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
042import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
043import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
044import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
045import com.unboundid.ldap.sdk.LDAPException;
046import com.unboundid.ldap.sdk.ResultCode;
047import com.unboundid.util.Extensible;
048import com.unboundid.util.NotNull;
049import com.unboundid.util.Nullable;
050import com.unboundid.util.ThreadSafety;
051import com.unboundid.util.ThreadSafetyLevel;
052import com.unboundid.util.args.ArgumentException;
053import com.unboundid.util.args.ArgumentParser;
054
055
056
057/**
058 * This class defines an API that must be implemented by extensions that provide
059 * passphrases for server components like external servers and access to key or
060 * trust stores.
061 * <BR>
062 * <H2>Configuring Passphrase Providers</H2>
063 * In order to configure a passphrase provider created using this API, use a
064 * command like:
065 * <PRE>
066 *      dsconfig create-passphrase-provider \
067 *           --provider-name "<I>{provider-name}</I>" \
068 *           --type third-party \
069 *           --set enabled:true \
070 *           --set "extension-class:<I>{class-name}</I>" \
071 *           --set "extension-argument:<I>{name=value}</I>"
072 * </PRE>
073 * where "<I>{provider-name}</I>" is the name to use for the passphrase
074 * provider instance, "<I>{class-name}</I>" is the fully-qualified name of the
075 * Java class that extends
076 * {@code com.unboundid.directory.sdk.common.api.PassphraseProvider}, and
077 * "<I>{name=value}</I>" represents name-value pairs for any arguments to
078 * provide to the passphrase provider.  If multiple arguments should be provided
079 * to the passphrase provider, then the
080 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
081 * provided multiple times.
082 */
083@Extensible()
084@DirectoryServerExtension()
085@DirectoryProxyServerExtension(appliesToLocalContent=true,
086     appliesToRemoteContent=false)
087@SynchronizationServerExtension(appliesToLocalContent=true,
088     appliesToSynchronizedContent=false)
089@MetricsEngineExtension()
090@BrokerExtension()
091@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
092public abstract class PassphraseProvider
093       implements UnboundIDExtension, Reconfigurable<PassphraseProviderConfig>,
094                  ExampleUsageProvider
095{
096  /**
097   * Creates a new instance of this passphrase provider.  All passphrase
098   * provider implementations must include a default constructor, but any
099   * initialization should generally be done in the
100   * {@code initializePassphraseProvider} method.
101   */
102  public PassphraseProvider()
103  {
104    // No implementation is required.
105  }
106
107
108
109  /**
110   * {@inheritDoc}
111   */
112  @NotNull()
113  @Override()
114  public abstract String getExtensionName();
115
116
117
118  /**
119   * {@inheritDoc}
120   */
121  @Nullable()
122  @Override()
123  public abstract String[] getExtensionDescription();
124
125
126
127  /**
128   * {@inheritDoc}
129   */
130  public void defineConfigArguments(@NotNull final ArgumentParser parser)
131         throws ArgumentException
132  {
133    // No arguments will be allowed by default.
134  }
135
136
137
138  /**
139   * Initializes this passphrase provider.
140   *
141   * @param  serverContext  A handle to the server context for the server in
142   *                        which this extension is running.
143   * @param  config         The general configuration for this passphrase
144   *                        provider.
145   * @param  parser         The argument parser which has been initialized from
146   *                        the configuration for this passphrase provider.
147   *
148   * @throws  LDAPException  If a problem occurs while initializing this
149   *                         passphrase provider.
150   */
151  public void initializePassphraseProvider(
152                   @NotNull final ServerContext serverContext,
153                   @NotNull final PassphraseProviderConfig config,
154                   @NotNull final ArgumentParser parser)
155         throws LDAPException
156  {
157    // No initialization will be performed by default.
158  }
159
160
161
162  /**
163   * {@inheritDoc}
164   */
165  public boolean isConfigurationAcceptable(
166                      @NotNull final PassphraseProviderConfig config,
167                      @NotNull final ArgumentParser parser,
168                      @NotNull final List<String> unacceptableReasons)
169  {
170    // No extended validation will be performed by default.
171    return true;
172  }
173
174
175
176  /**
177   * {@inheritDoc}
178   */
179  @NotNull()
180  public ResultCode applyConfiguration(
181              @NotNull final PassphraseProviderConfig config,
182              @NotNull final ArgumentParser parser,
183              @NotNull final List<String> adminActionsRequired,
184              @NotNull final List<String> messages)
185  {
186    // By default, no configuration changes will be applied.  If there are any
187    // arguments, then add an admin action message indicating that the extension
188    // needs to be restarted for any changes to take effect.
189    if (! parser.getNamedArguments().isEmpty())
190    {
191      adminActionsRequired.add(
192           "No configuration change has actually been applied.  The new " +
193                "configuration will not take effect until this passphrase " +
194                "provider is disabled and re-enabled or until the server is " +
195                "restarted.");
196    }
197
198    return ResultCode.SUCCESS;
199  }
200
201
202
203  /**
204   * Performs any cleanup which may be necessary when this passphrase provider
205   * is to be taken out of service.
206   */
207  public void finalizePassphraseProvider()
208  {
209    // No implementation is required.
210  }
211
212
213
214  /**
215   * Retrieves the passphrase.
216   *
217   * @param  allowCached  Indicates whether to allow the server to use a cached
218   *                      version of the passphrase.
219   *
220   * @return  The passphrase that should be used.  It must not be {@code null}
221   *          or empty.
222   *
223   * @throws  LDAPException  If the passphrase cannot be retrieved.
224   */
225  @NotNull()
226  public abstract char[] getPassphrase(final boolean allowCached)
227          throws LDAPException;
228
229
230
231  /**
232   * {@inheritDoc}
233   */
234  @Nullable()
235  public Map<List<String>,String> getExamplesArgumentSets()
236  {
237    return Collections.emptyMap();
238  }
239}