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 2010-2024 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;
034import javax.net.ssl.KeyManager;
035
036import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
037import com.unboundid.directory.sdk.common.config.KeyManagerProviderConfig;
038import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
039import com.unboundid.directory.sdk.common.internal.Reconfigurable;
040import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
041import com.unboundid.directory.sdk.common.types.ServerContext;
042import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
043import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
044import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
045import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
046import com.unboundid.ldap.sdk.LDAPException;
047import com.unboundid.ldap.sdk.ResultCode;
048import com.unboundid.util.Extensible;
049import com.unboundid.util.ThreadSafety;
050import com.unboundid.util.ThreadSafetyLevel;
051import com.unboundid.util.args.ArgumentException;
052import com.unboundid.util.args.ArgumentParser;
053
054
055
056/**
057 * This class defines an API that must be implemented by extensions which
058 * provide access to key managers.  Key managers allow the server to access
059 * certificates in a form that can be presented to another system during SSL or
060 * StartTLS negotiation.  If the server is configured to accept secure
061 * communication from clients, then a key manager provider will be used to
062 * access the certificate that the server presents to the client.  If the server
063 * needs to establish a secure connection to another system (e.g., the Directory
064 * Proxy Server connecting to a backend Directory Server instance), then the
065 * key manager provider may also be used to obtain a client certificate that may
066 * be used for authentication.
067 * <BR>
068 * <H2>Configuring Key Manager Providers</H2>
069 * In order to configure a key manager provider created using this API, use a
070 * command like:
071 * <PRE>
072 *      dsconfig create-key-manager-provider \
073 *           --provider-name "<I>{provider-name}</I>" \
074 *           --type third-party \
075 *           --set enabled:true \
076 *           --set "extension-class:<I>{class-name}</I>" \
077 *           --set "extension-argument:<I>{name=value}</I>"
078 * </PRE>
079 * where "<I>{provider-name}</I>" is the name to use for the key manager
080 * provider instance, "<I>{class-name}</I>" is the fully-qualified name of the
081 * Java class that extends
082 * {@code com.unboundid.directory.sdk.common.api.KeyManagerProvider}, and
083 * "<I>{name=value}</I>" represents name-value pairs for any arguments to
084 * provide to the key manager provider.  If multiple arguments should be
085 * provided to the key manager provider, then the
086 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
087 * provided multiple times.
088 */
089@Extensible()
090@DirectoryServerExtension()
091@DirectoryProxyServerExtension(appliesToLocalContent=true,
092     appliesToRemoteContent=false)
093@SynchronizationServerExtension(appliesToLocalContent=true,
094     appliesToSynchronizedContent=false)
095@MetricsEngineExtension()
096@BrokerExtension()
097@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
098public abstract class KeyManagerProvider
099       implements UnboundIDExtension, Reconfigurable<KeyManagerProviderConfig>,
100                  ExampleUsageProvider
101{
102  /**
103   * Creates a new instance of this key manager provider.  All key manager
104   * provider implementations must include a default constructor, but any
105   * initialization should generally be done in the
106   * {@code initializeKeyManagerProvider} method.
107   */
108  public KeyManagerProvider()
109  {
110    // No implementation is required.
111  }
112
113
114
115  /**
116   * {@inheritDoc}
117   */
118  public abstract String getExtensionName();
119
120
121
122  /**
123   * {@inheritDoc}
124   */
125  public abstract String[] getExtensionDescription();
126
127
128
129  /**
130   * {@inheritDoc}
131   */
132  public void defineConfigArguments(final ArgumentParser parser)
133         throws ArgumentException
134  {
135    // No arguments will be allowed by default.
136  }
137
138
139
140  /**
141   * Initializes this key manager provider.
142   *
143   * @param  serverContext  A handle to the server context for the server in
144   *                        which this extension is running.
145   * @param  config         The general configuration for this key manager
146   *                        provider.
147   * @param  parser         The argument parser which has been initialized from
148   *                        the configuration for this key manager provider.
149   *
150   * @throws  LDAPException  If a problem occurs while initializing this
151   *                         key manager provider.
152   */
153  public void initializeKeyManagerProvider(final ServerContext serverContext,
154                   final KeyManagerProviderConfig config,
155                   final ArgumentParser parser)
156         throws LDAPException
157  {
158    // No initialization will be performed by default.
159  }
160
161
162
163  /**
164   * {@inheritDoc}
165   */
166  public boolean isConfigurationAcceptable(
167                      final KeyManagerProviderConfig config,
168                      final ArgumentParser parser,
169                      final List<String> unacceptableReasons)
170  {
171    // No extended validation will be performed by default.
172    return true;
173  }
174
175
176
177  /**
178   * {@inheritDoc}
179   */
180  public ResultCode applyConfiguration(final KeyManagerProviderConfig config,
181                                       final ArgumentParser parser,
182                                       final List<String> adminActionsRequired,
183                                       final List<String> messages)
184  {
185    // By default, no configuration changes will be applied.  If there are any
186    // arguments, then add an admin action message indicating that the extension
187    // needs to be restarted for any changes to take effect.
188    if (! parser.getNamedArguments().isEmpty())
189    {
190      adminActionsRequired.add(
191           "No configuration change has actually been applied.  The new " +
192                "configuration will not take effect until this key manager " +
193                "provider is disabled and re-enabled or until the server is " +
194                "restarted.");
195    }
196
197    return ResultCode.SUCCESS;
198  }
199
200
201
202  /**
203   * Performs any cleanup which may be necessary when this key manager provider
204   * is to be taken out of service.
205   */
206  public void finalizeKeyManagerProvider()
207  {
208    // No implementation is required.
209  }
210
211
212
213  /**
214   * Retrieves a set of key managers that may be used for operations within
215   * the server which may require access to certificates.
216   *
217   * @return  The set of key managers that may be used for operations within the
218   *          server which may require access to certificates.
219   *
220   * @throws  LDAPException  If a problem occurs while attempting to retrieve
221   *                         the key managers.
222   */
223  public abstract KeyManager[] getKeyManagers()
224         throws LDAPException;
225
226
227
228  /**
229   * {@inheritDoc}
230   */
231  public Map<List<String>,String> getExamplesArgumentSets()
232  {
233    return Collections.emptyMap();
234  }
235}