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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. 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 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.api; 028 import org.opends.messages.Message; 029 030 031 032 import java.util.List; 033 034 import org.opends.server.admin.std.server.PasswordStorageSchemeCfg; 035 import org.opends.server.config.ConfigException; 036 import org.opends.server.types.ByteString; 037 import org.opends.server.types.DirectoryException; 038 import org.opends.server.types.InitializationException; 039 040 041 042 /** 043 * This class defines the set of methods and structures that must be 044 * implemented by a Directory Server module that implements a password 045 * storage scheme. Each subclass may only implement a single password 046 * storage scheme type. 047 * 048 * @param <T> The type of configuration handled by this 049 * password storage scheme 050 */ 051 @org.opends.server.types.PublicAPI( 052 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 053 mayInstantiate=false, 054 mayExtend=true, 055 mayInvoke=false) 056 public abstract class 057 PasswordStorageScheme <T extends PasswordStorageSchemeCfg> 058 { 059 /** 060 * Initializes this password storage scheme handler based on the 061 * information in the provided configuration entry. It should also 062 * register itself with the Directory Server for the particular 063 * storage scheme that it will manage. 064 * 065 * @param configuration The configuration entry that contains the 066 * information to use to initialize this 067 * password storage scheme handler. 068 * 069 * @throws ConfigException If an unrecoverable problem arises in 070 * the process of performing the 071 * initialization. 072 * 073 * @throws InitializationException If a problem occurs during 074 * initialization that is not 075 * related to the server 076 * configuration. 077 */ 078 public abstract void initializePasswordStorageScheme( 079 T configuration) 080 throws ConfigException, InitializationException; 081 082 083 084 /** 085 * Indicates whether the provided configuration is acceptable for 086 * this password storage scheme. It should be possible to call this 087 * method on an uninitialized password storage scheme instance in 088 * order to determine whether the password storage scheme would be 089 * able to use the provided configuration. 090 * <BR><BR> 091 * Note that implementations which use a subclass of the provided 092 * configuration class will likely need to cast the configuration 093 * to the appropriate subclass type. 094 * 095 * @param configuration The password storage scheme 096 * configuration for which to make the 097 * determination. 098 * @param unacceptableReasons A list that may be used to hold the 099 * reasons that the provided 100 * configuration is not acceptable. 101 * 102 * @return {@code true} if the provided configuration is acceptable 103 * for this password storage scheme, or {@code false} if 104 * not. 105 */ 106 public boolean isConfigurationAcceptable( 107 PasswordStorageSchemeCfg configuration, 108 List<Message> unacceptableReasons) 109 { 110 // This default implementation does not perform any special 111 // validation. It should be overridden by password storage scheme 112 // implementations that wish to perform more detailed validation. 113 return true; 114 } 115 116 117 118 /** 119 * Performs any necessary finalization that might be required when 120 * this password storage scheme is no longer needed (e.g., the 121 * scheme is disabled or the server is shutting down). 122 */ 123 public void finalizePasswordStorageScheme() 124 { 125 // No implementation required by default. 126 } 127 128 129 130 /** 131 * Retrieves the name of the password storage scheme provided by 132 * this handler. 133 * 134 * @return The name of the password storage scheme provided by this 135 * handler. 136 */ 137 public abstract String getStorageSchemeName(); 138 139 140 141 /** 142 * Encodes the provided plaintext password for this storage scheme, 143 * without the name of the associated scheme. Note that the 144 * provided plaintext password should not be altered in any way. 145 * 146 * @param plaintext The plaintext version of the password. 147 * 148 * @return The password that has been encoded using this storage 149 * scheme. 150 * 151 * @throws DirectoryException If a problem occurs while 152 * processing. 153 */ 154 public abstract ByteString encodePassword(ByteString plaintext) 155 throws DirectoryException; 156 157 158 159 /** 160 * Encodes the provided plaintext password for this storage scheme, 161 * prepending the name of the scheme in curly braces. Note that the 162 * provided plaintext password should not be altered in any way. 163 * 164 * @param plaintext The plaintext version of the password. 165 * 166 * @return The encoded password, including the name of the storage 167 * scheme. 168 * 169 * @throws DirectoryException If a problem occurs while 170 * processing. 171 */ 172 public abstract ByteString encodePasswordWithScheme( 173 ByteString plaintext) 174 throws DirectoryException; 175 176 177 178 179 /** 180 * Indicates whether the provided plaintext password included in a 181 * bind request matches the given stored value. The provided stored 182 * value should not include the scheme name in curly braces. 183 * 184 * @param plaintextPassword The plaintext password provided by the 185 * user as part of a simple bind attempt. 186 * @param storedPassword The stored password to compare against 187 * the provided plaintext password. 188 * 189 * @return {@code true} if the provided plaintext password matches 190 * the provided stored password, or {@code false} if not. 191 */ 192 public abstract boolean passwordMatches( 193 ByteString plaintextPassword, 194 ByteString storedPassword); 195 196 197 198 /** 199 * Indicates whether this password storage scheme supports the 200 * ability to interact with values using the authentication password 201 * syntax defined in RFC 3112. 202 * 203 * @return {@code true} if this password storage scheme supports 204 * the ability to interact with values using the 205 * authentication password syntax, or {@code false} if it 206 * does not. 207 */ 208 public abstract boolean supportsAuthPasswordSyntax(); 209 210 211 212 /** 213 * Retrieves the scheme name that should be used with this password 214 * storage scheme when it is used in the context of the 215 * authentication password syntax. This default implementation will 216 * return the same value as the {@code getStorageSchemeName} method. 217 * 218 * @return The scheme name that should be used with this password 219 * storage scheme when it is used in the context of the 220 * authentication password syntax. 221 */ 222 public String getAuthPasswordSchemeName() 223 { 224 return getStorageSchemeName(); 225 } 226 227 228 229 /** 230 * Encodes the provided plaintext password for this storage scheme 231 * using the authentication password syntax defined in RFC 3112. 232 * Note that the provided plaintext password should not be altered 233 * in any way. 234 * 235 * @param plaintext The plaintext version of the password. 236 * 237 * @return The password that has been encoded in the authentication 238 * password syntax. 239 * 240 * @throws DirectoryException If a problem occurs while processing 241 * of if this storage scheme does not 242 * support the authentication password 243 * syntax. 244 */ 245 public abstract ByteString encodeAuthPassword(ByteString plaintext) 246 throws DirectoryException; 247 248 249 250 /** 251 * Indicates whether the provided plaintext password matches the 252 * encoded password using the authentication password syntax with 253 * the given authInfo and authValue components. 254 * 255 * @param plaintextPassword The plaintext password provided by the 256 * user. 257 * @param authInfo The authInfo component of the password 258 * encoded in the authentication password 259 * syntax. 260 * @param authValue The authValue component of the 261 * password encoded in the authentication 262 * password syntax. 263 * 264 * @return {@code true} if the provided plaintext password matches 265 * the encoded password according to the authentication 266 * password info syntax, or {@code false} if it does not or 267 * this storage scheme does not support the authentication 268 * password syntax. 269 */ 270 public abstract boolean authPasswordMatches( 271 ByteString plaintextPassword, 272 String authInfo, String authValue); 273 274 275 276 /** 277 * Indicates whether this storage scheme is reversible (i.e., it is 278 * possible to obtain the original plaintext value from the stored 279 * password). 280 * 281 * @return {@code true} if this is a reversible password storage 282 * scheme, or {@code false} if it is not. 283 */ 284 public abstract boolean isReversible(); 285 286 287 288 /** 289 * Retrieves the original plaintext value for the provided stored 290 * password. Note that this should only be called if 291 * {@code isReversible} returns {@code true}. 292 * 293 * @param storedPassword The password for which to obtain the 294 * plaintext value. It should not include 295 * the scheme name in curly braces. 296 * 297 * @return The plaintext value for the provided stored password. 298 * 299 * @throws DirectoryException If it is not possible to obtain the 300 * plaintext value for the provided 301 * stored password. 302 */ 303 public abstract ByteString getPlaintextValue( 304 ByteString storedPassword) 305 throws DirectoryException; 306 307 308 309 /** 310 * Retrieves the original plaintext value for the provided password 311 * stored in the authPassword syntax. Note that this should only be 312 * called if {@code isReversible} returns {@code true}. 313 * 314 * @param authInfo The authInfo component of the password encoded 315 * in the authentication password syntax. 316 * @param authValue The authValue component of the password 317 * encoded in the authentication password syntax. 318 * 319 * @return The plaintext value for the provided stored password. 320 * 321 * @throws DirectoryException If it is not possible to obtain the 322 * plaintext value for the provided 323 * stored password, or if this storage 324 * scheme does not support the 325 * authPassword syntax.. 326 */ 327 public abstract ByteString getAuthPasswordPlaintextValue( 328 String authInfo, String authValue) 329 throws DirectoryException; 330 331 332 333 /** 334 * Indicates whether this password storage scheme should be 335 * considered "secure". If the encoding used for this scheme does 336 * not obscure the value at all, or if it uses a method that is 337 * trivial to reverse (e.g., base64), then it should not be 338 * considered secure. 339 * <BR><BR> 340 * This may be used to determine whether a password may be included 341 * in a set of search results, including the possibility of 342 * overriding access controls in the case that access controls would 343 * allow the password to be returned but the password is considered 344 * too insecure to reveal. 345 * 346 * @return {@code false} if it may be trivial to discover the 347 * original plain-text password from the encoded form, or 348 * {@code true} if the scheme offers sufficient protection 349 * that revealing the encoded password will not easily 350 * reveal the corresponding plain-text value. 351 */ 352 public abstract boolean isStorageSchemeSecure(); 353 } 354