001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2006-2008 Sun Microsystems, Inc. 015 * Portions Copyright 2014-2016 ForgeRock AS. 016 */ 017package org.opends.server.api; 018import org.forgerock.i18n.LocalizableMessage; 019 020 021 022import java.util.List; 023 024import org.forgerock.opendj.server.config.server.SASLMechanismHandlerCfg; 025import org.forgerock.opendj.config.server.ConfigException; 026import org.opends.server.core.BindOperation; 027import org.opends.server.types.InitializationException; 028 029 030 031/** 032 * This class defines the set of methods and structures that must be 033 * implemented by a Directory Server module that implements the 034 * functionality required for one or more SASL mechanisms. 035 * 036 * @param <T> The type of configuration handled by this SASL 037 * mechanism handler. 038 */ 039@org.opends.server.types.PublicAPI( 040 stability=org.opends.server.types.StabilityLevel.VOLATILE, 041 mayInstantiate=false, 042 mayExtend=true, 043 mayInvoke=false) 044public abstract class SASLMechanismHandler 045 <T extends SASLMechanismHandlerCfg> 046{ 047 /** 048 * Initializes this SASL mechanism handler based on the information 049 * in the provided configuration entry. It should also register 050 * itself with the Directory Server for the particular kinds of SASL 051 * mechanisms that it will process. 052 * 053 * @param configuration The configuration to use to initialize 054 * this SASL mechanism handler. 055 * 056 * @throws ConfigException If an unrecoverable problem arises in 057 * the process of performing the 058 * initialization. 059 * 060 * @throws InitializationException If a problem occurs during 061 * initialization that is not 062 * related to the server 063 * configuration. 064 */ 065 public abstract void initializeSASLMechanismHandler(T configuration) 066 throws ConfigException, InitializationException; 067 068 069 070 /** 071 * Indicates whether the provided configuration is acceptable for 072 * this SASL mechanism handler. It should be possible to call this 073 * method on an uninitialized SASL mechanism handler instance in 074 * order to determine whether the SASL mechanism handler would be 075 * able to use the provided configuration. 076 * <BR><BR> 077 * Note that implementations which use a subclass of the provided 078 * configuration class will likely need to cast the configuration 079 * to the appropriate subclass type. 080 * 081 * @param configuration The SASL mechanism handler 082 * configuration for which to make the 083 * determination. 084 * @param unacceptableReasons A list that may be used to hold the 085 * reasons that the provided 086 * configuration is not acceptable. 087 * 088 * @return {@code true} if the provided configuration is acceptable 089 * for this SASL mechanism handler, or {@code false} if 090 * not. 091 */ 092 public boolean isConfigurationAcceptable( 093 SASLMechanismHandlerCfg configuration, 094 List<LocalizableMessage> unacceptableReasons) 095 { 096 // This default implementation does not perform any special 097 // validation. It should be overridden by SASL mechanism handler 098 // implementations that wish to perform more detailed validation. 099 return true; 100 } 101 102 103 104 /** 105 * Performs any finalization that may be necessary for this SASL 106 * mechanism handler. By default, no finalization is performed. 107 */ 108 public void finalizeSASLMechanismHandler() 109 { 110 // No implementation is required by default. 111 } 112 113 114 115 /** 116 * Processes the SASL bind operation. SASL mechanism 117 * implementations must ensure that the following actions are taken 118 * during the processing of this method: 119 * <UL> 120 * <LI>The {@code BindOperation.setResultCode} method must be used 121 * to set the appropriate result code.</LI> 122 * <LI>If the SASL processing gets far enough to be able to map 123 * the request to a user entry (regardless of whether the 124 * authentication is ultimately successful), then this method 125 * must call the {@code BindOperation.setSASLAuthUserEntry} 126 * method to provide it with the entry for the user that 127 * attempted to authenticate.</LI> 128 * <LI>If the bind processing was successful, then the 129 * {@code BindOperation.setAuthenticationInfo} method must be 130 * used to set the authentication info for the bind 131 * operation.</LI> 132 * <LI>If the bind processing was not successful, then the 133 * {@code BindOperation.setAuthFailureReason} method should be 134 * used to provide a message explaining why the authentication 135 * failed.</LI> 136 * </UL> 137 * 138 * @param bindOperation The SASL bind operation to be processed. 139 */ 140 public abstract void processSASLBind(BindOperation bindOperation); 141 142 143 144 /** 145 * Indicates whether the specified SASL mechanism is password-based 146 * or uses some other form of credentials (e.g., an SSL client 147 * certificate or Kerberos ticket). 148 * 149 * @param mechanism The name of the mechanism for which to make 150 * the determination. This will only be invoked 151 * with names of mechanisms for which this 152 * handler has previously registered. 153 * 154 * @return {@code true} if this SASL mechanism is password-based, 155 * or {@code false} if it uses some other form of 156 * credentials. 157 */ 158 public abstract boolean isPasswordBased(String mechanism); 159 160 161 162 /** 163 * Indicates whether the specified SASL mechanism should be 164 * considered secure (i.e., it does not expose the authentication 165 * credentials in a manner that is useful to a third-party observer, 166 * and other aspects of the authentication are generally secure). 167 * 168 * @param mechanism The name of the mechanism for which to make 169 * the determination. This will only be invoked 170 * with names of mechanisms for which this 171 * handler has previously registered. 172 * 173 * @return {@code true} if this SASL mechanism should be considered 174 * secure, or {@code false} if not. 175 */ 176 public abstract boolean isSecure(String mechanism); 177} 178