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 *      Copyright 2010-2016 UnboundID Corp.
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.TrustManager;
035
036import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
037import com.unboundid.directory.sdk.common.config.TrustManagerProviderConfig;
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 trust managers which are used to determine whether to trust
059 * a certificate that has been presented to the server.  Trust managers are
060 * generally used when performing cryptographic operations, including SSL and
061 * StartTLS communication, in which a certificate is presented to the server.
062 * In such cases, the secure communication will only be allowed if the trust
063 * managers determine that the presented certificate chain is trustworthy.
064 * <BR>
065 * <H2>Configuring Trust Manager Providers</H2>
066 * In order to configure a trust manager provider created using this API, use a
067 * command like:
068 * <PRE>
069 *      dsconfig create-trust-manager-provider \
070 *           --provider-name "<I>{provider-name}</I>" \
071 *           --type third-party \
072 *           --set enabled:true \
073 *           --set "extension-class:<I>{class-name}</I>" \
074 *           --set "extension-argument:<I>{name=value}</I>"
075 * </PRE>
076 * where "<I>{provider-name}</I>" is the name to use for the trust manager
077 * provider instance, "<I>{class-name}</I>" is the fully-qualified name of the
078 * Java class that extends
079 * {@code com.unboundid.directory.sdk.common.api.TrustManagerProvider}, and
080 * "<I>{name=value}</I>" represents name-value pairs for any arguments to
081 * provide to the trust manager provider.  If multiple arguments should be
082 * provided to the trust manager provider, then the
083 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
084 * provided multiple times.
085 */
086@Extensible()
087@DirectoryServerExtension()
088@DirectoryProxyServerExtension(appliesToLocalContent=true,
089     appliesToRemoteContent=false)
090@SynchronizationServerExtension(appliesToLocalContent=true,
091     appliesToSynchronizedContent=false)
092@MetricsEngineExtension()
093@BrokerExtension()
094@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
095public abstract class TrustManagerProvider
096       implements UnboundIDExtension,
097                  Reconfigurable<TrustManagerProviderConfig>,
098                  ExampleUsageProvider
099{
100  /**
101   * Creates a new instance of this trust manager provider.  All trust manager
102   * provider implementations must include a default constructor, but any
103   * initialization should generally be done in the
104   * {@code initializeTrustManagerProvider} method.
105   */
106  public TrustManagerProvider()
107  {
108    // No implementation is required.
109  }
110
111
112
113  /**
114   * {@inheritDoc}
115   */
116  public abstract String getExtensionName();
117
118
119
120  /**
121   * {@inheritDoc}
122   */
123  public abstract String[] getExtensionDescription();
124
125
126
127  /**
128   * {@inheritDoc}
129   */
130  public void defineConfigArguments(final ArgumentParser parser)
131         throws ArgumentException
132  {
133    // No arguments will be allowed by default.
134  }
135
136
137
138  /**
139   * Initializes this trust manager 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 trust manager
144   *                        provider.
145   * @param  parser         The argument parser which has been initialized from
146   *                        the configuration for this trust manager provider.
147   *
148   * @throws  LDAPException  If a problem occurs while initializing this
149   *                         trust manager provider.
150   */
151  public void initializeTrustManagerProvider(final ServerContext serverContext,
152                   final TrustManagerProviderConfig config,
153                   final ArgumentParser parser)
154         throws LDAPException
155  {
156    // No initialization will be performed by default.
157  }
158
159
160
161  /**
162   * {@inheritDoc}
163   */
164  public boolean isConfigurationAcceptable(
165                      final TrustManagerProviderConfig config,
166                      final ArgumentParser parser,
167                      final List<String> unacceptableReasons)
168  {
169    // No extended validation will be performed by default.
170    return true;
171  }
172
173
174
175  /**
176   * {@inheritDoc}
177   */
178  public ResultCode applyConfiguration(final TrustManagerProviderConfig config,
179                                       final ArgumentParser parser,
180                                       final List<String> adminActionsRequired,
181                                       final List<String> messages)
182  {
183    // By default, no configuration changes will be applied.  If there are any
184    // arguments, then add an admin action message indicating that the extension
185    // needs to be restarted for any changes to take effect.
186    if (! parser.getNamedArguments().isEmpty())
187    {
188      adminActionsRequired.add(
189           "No configuration change has actually been applied.  The new " +
190                "configuration will not take effect until this trust manager " +
191                "provider is disabled and re-enabled or until the server is " +
192                "restarted.");
193    }
194
195    return ResultCode.SUCCESS;
196  }
197
198
199
200  /**
201   * Performs any cleanup which may be necessary when this trust manager
202   * provider is to be taken out of service.
203   */
204  public void finalizeTrustManagerProvider()
205  {
206    // No implementation is required.
207  }
208
209
210
211  /**
212   * Retrieves a set of trust managers that may be used for operations within
213   * the server which may need to determine whether to trust a presented
214   * certificate chain.
215   *
216   * @return  The set of trust managers that may be used for operations within
217   *          the server which may need to determine whether to trust a
218   *          presented certificate chain.
219   *
220   * @throws  LDAPException  If a problem occurs while attempting to retrieve
221   *                         the trust managers.
222   */
223  public abstract TrustManager[] getTrustManagers()
224         throws LDAPException;
225
226
227
228  /**
229   * {@inheritDoc}
230   */
231  public Map<List<String>,String> getExamplesArgumentSets()
232  {
233    return Collections.emptyMap();
234  }
235}