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.ds.api; 028 029 030 031 import java.security.cert.Certificate; 032 import java.util.Collections; 033 import java.util.List; 034 import java.util.Map; 035 036 import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider; 037 import com.unboundid.directory.sdk.common.internal.Reconfigurable; 038 import com.unboundid.directory.sdk.common.internal.UnboundIDExtension; 039 import com.unboundid.directory.sdk.ds.config.CertificateMapperConfig; 040 import com.unboundid.directory.sdk.ds.types.DirectoryServerContext; 041 import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 042 import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 043 import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 044 import com.unboundid.ldap.sdk.LDAPException; 045 import com.unboundid.ldap.sdk.ResultCode; 046 import com.unboundid.util.Extensible; 047 import com.unboundid.util.ThreadSafety; 048 import com.unboundid.util.ThreadSafetyLevel; 049 import com.unboundid.util.args.ArgumentException; 050 import com.unboundid.util.args.ArgumentParser; 051 052 053 054 /** 055 * This class defines an API that must be implemented by extensions which 056 * attempt to map a certificate presented by a client (e.g., via SSL or 057 * StartTLS) to a user defined in the server. This is primarily used during 058 * the course of SASL EXTERNAL bind processing when a client uses a certificate 059 * to authenticate to the server. Any information contained in the provided 060 * certificate chain (including the subject, fingerprint, validity, extensions, 061 * etc. of the client certificate, as well as any information about any issuer 062 * certificates) may be used to map information in the provided certificate 063 * chain to exactly one user in the server. If the certificate cannot be mapped 064 * to any user, or if it is mapped to multiple users, then the authentication 065 * attempt must fail. 066 * <BR> 067 * <H2>Configuring Certificate Mappers</H2> 068 * In order to configure a certificate mapper created using this API, use a 069 * command like: 070 * <PRE> 071 * dsconfig create-certificate-mapper \ 072 * --mapper-name "<I>{mapper-name}</I>" \ 073 * --type third-party \ 074 * --set enabled:true \ 075 * --set "extension-class:<I>{class-name}</I>" \ 076 * --set "extension-argument:<I>{name=value}</I>" 077 * </PRE> 078 * where "<I>{mapper-name}</I>" is the name to use for the certificate mapper 079 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class 080 * that extends {@code com.unboundid.directory.sdk.ds.api.CertificateMapper}, 081 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to 082 * provide to the certificate mapper. If multiple arguments should be provided 083 * to the certificate mapper, then the 084 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be 085 * provided multiple times. 086 * 087 * @see com.unboundid.directory.sdk.ds.scripting.ScriptedCertificateMapper 088 */ 089 @Extensible() 090 @DirectoryServerExtension() 091 @DirectoryProxyServerExtension(appliesToLocalContent=true, 092 appliesToRemoteContent=true) 093 @SynchronizationServerExtension(appliesToLocalContent=true, 094 appliesToSynchronizedContent=false) 095 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 096 public abstract class CertificateMapper 097 implements UnboundIDExtension, Reconfigurable<CertificateMapperConfig>, 098 ExampleUsageProvider 099 { 100 /** 101 * Creates a new instance of this certificate mapper. All certificate mapper 102 * implementations must include a default constructor, but any initialization 103 * should generally be done in the {@code initializeCertificateMapper} method. 104 */ 105 public CertificateMapper() 106 { 107 // No implementation is required. 108 } 109 110 111 112 /** 113 * {@inheritDoc} 114 */ 115 public abstract String getExtensionName(); 116 117 118 119 /** 120 * {@inheritDoc} 121 */ 122 public abstract String[] getExtensionDescription(); 123 124 125 126 /** 127 * {@inheritDoc} 128 */ 129 public void defineConfigArguments(final ArgumentParser parser) 130 throws ArgumentException 131 { 132 // No arguments will be allowed by default. 133 } 134 135 136 137 /** 138 * Initializes this certificate mapper. 139 * 140 * @param serverContext A handle to the server context for the server in 141 * which this extension is running. 142 * @param config The general configuration for this certificate 143 * mapper. 144 * @param parser The argument parser which has been initialized from 145 * the configuration for this certificate mapper. 146 * 147 * @throws LDAPException If a problem occurs while initializing this 148 * certificate mapper. 149 */ 150 public void initializeCertificateMapper( 151 final DirectoryServerContext serverContext, 152 final CertificateMapperConfig 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(final CertificateMapperConfig config, 165 final ArgumentParser parser, 166 final List<String> unacceptableReasons) 167 { 168 // No extended validation will be performed by default. 169 return true; 170 } 171 172 173 174 /** 175 * {@inheritDoc} 176 */ 177 public ResultCode applyConfiguration(final CertificateMapperConfig config, 178 final ArgumentParser parser, 179 final List<String> adminActionsRequired, 180 final List<String> messages) 181 { 182 // By default, no configuration changes will be applied. If there are any 183 // arguments, then add an admin action message indicating that the extension 184 // needs to be restarted for any changes to take effect. 185 if (! parser.getNamedArguments().isEmpty()) 186 { 187 adminActionsRequired.add( 188 "No configuration change has actually been applied. The new " + 189 "configuration will not take effect until this certificate " + 190 "mapper is disabled and re-enabled or until the server is " + 191 "restarted."); 192 } 193 194 return ResultCode.SUCCESS; 195 } 196 197 198 199 /** 200 * Performs any cleanup which may be necessary when this certificate mapper is 201 * to be taken out of service. 202 */ 203 public void finalizeCertificateMapper() 204 { 205 // No implementation is required. 206 } 207 208 209 210 /** 211 * Performs any processing which may be necessary to map the provided 212 * certificate chain to a user within the server. 213 * 214 * @param certChain The certificate chain presented by the client. 215 * 216 * @return The DN of the user within the server to which the provided 217 * certificate corresponds. 218 * 219 * @throws LDAPException If the presented certificate cannot be mapped to 220 * exactly one user in the server. 221 */ 222 public abstract String mapCertificate(final Certificate[] certChain) 223 throws LDAPException; 224 225 226 227 /** 228 * {@inheritDoc} 229 */ 230 public Map<List<String>,String> getExamplesArgumentSets() 231 { 232 return Collections.emptyMap(); 233 } 234 }