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-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.api; 028 029 030 031 import java.util.Collections; 032 import java.util.List; 033 import java.util.Map; 034 import javax.net.ssl.TrustManager; 035 036 import com.unboundid.directory.sdk.broker.internal.IdentityBrokerExtension; 037 import com.unboundid.directory.sdk.common.config.TrustManagerProviderConfig; 038 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider; 039 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 040 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension; 041 import com.unboundid.directory.sdk.common.types.ServerContext; 042 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 043 import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension; 044 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 045 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 046 import com.unboundid.ldap.sdk.LDAPException; 047 import com.unboundid.ldap.sdk.ResultCode; 048 import com.unboundid.util.Extensible; 049 import com.unboundid.util.ThreadSafety; 050 import com.unboundid.util.ThreadSafetyLevel; 051 import com.unboundid.util.args.ArgumentException; 052 import 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 @IdentityBrokerExtension() 094 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 095 public 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 }