1 package org.apache.archiva.redback.policy; 2 3 /* 4 * Copyright 2001-2006 The Apache Software Foundation. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 /** 20 * <p> 21 * Interface for performing authentication operations on a password. 22 * </p> 23 * 24 * <p>Javadoc about encoding and salts copied from Acegi Security.</p> 25 * 26 * @author colin sampaleanu 27 * @author <a href="mailto:joakim@erdfelt.com">Joakim Erdfelt</a> 28 * 29 */ 30 public interface PasswordEncoder 31 { 32 33 /** 34 * <p> 35 * Sets the system wide salt to use in the encoder. 36 * </p> 37 * 38 * <p> 39 * The specified salt will potentially be used by the implementation to "salt" the initial value before 40 * encoding. A salt is usually a user-specific value which is added to the password before the digest is computed. 41 * This means that computation of digests for common dictionary words will be different than those in the backend 42 * store, because the dictionary word digests will not reflect the addition of the salt. If a per-user salt is 43 * used (rather than a system-wide salt), it also means users with the same password will have different digest 44 * encoded passwords in the backend store. 45 * </p> 46 * 47 * @param salt the salt to use as a default for the encoder. 48 */ 49 void setSystemSalt( Object salt ); 50 51 /** 52 * <p> 53 * Encodes the specified raw password with an implementation specific algorithm, using the system wide salt. 54 * </p> 55 * 56 * <p> 57 * This will generally be a one-way message digest such as MD5 or SHA, but may also be a plaintext 58 * variant which does no encoding at all, but rather returns the same password it was fed. The latter is useful to 59 * plug in when the original password must be stored as-is. 60 * </p> 61 * 62 * @param rawPass the password to encode 63 * 64 * @return encoded password 65 */ 66 String encodePassword( String rawPass ); 67 68 /** 69 * <p> 70 * Encodes the specified raw password with an implementation specific algorithm, using user specific salt. 71 * </p> 72 * 73 * <p> 74 * This will generally be a one-way message digest such as MD5 or SHA, but may also be a plaintext 75 * variant which does no encoding at all, but rather returns the same password it was fed. The latter is useful to 76 * plug in when the original password must be stored as-is. 77 * </p> 78 * 79 * <p> 80 * The specified salt will potentially be used by the implementation to "salt" the initial value before 81 * encoding. A salt is usually a user-specific value which is added to the password before the digest is computed. 82 * This means that computation of digests for common dictionary words will be different than those in the backend 83 * store, because the dictionary word digests will not reflect the addition of the salt. If a per-user salt is 84 * used (rather than a system-wide salt), it also means users with the same password will have different digest 85 * encoded passwords in the backend store. 86 * </p> 87 * 88 * @param rawPass the password to encode 89 * @param salt optionally used by the implementation to "salt" the raw password before encoding. 90 * A <code>null</code> value is legal. 91 * @return encoded password 92 */ 93 String encodePassword( String rawPass, Object salt ); 94 95 96 /** 97 * <p> 98 * Validates a specified "raw" password against an encoded password, using the system wide salt. 99 * </p> 100 * 101 * <p> 102 * The encoded password should have previously been generated by {@link #encodePassword(String)}. 103 * This method will encode the <code>rawPass</code> (using the system wide <code>salt</code>), and then 104 * compared it with the presented <code>encPass</code>. 105 * </p> 106 * 107 * <p> 108 * For an explanation of salts, please refer to {@link #setSystemSalt(Object)}. 109 * </p> 110 * 111 * @param encPass a pre-encoded password 112 * @param rawPass a raw password to encode and compare against the pre-encoded password 113 * 114 * @return true if the password is valid , false otherwise 115 */ 116 boolean isPasswordValid( String encPass, String rawPass ); 117 118 /** 119 * <p> 120 * Validates a specified "raw" password against an encoded password, using a user specific salt. 121 * </p> 122 * 123 * <p> 124 * The encoded password should have previously been generated by {@link #encodePassword(String, 125 * Object)}. This method will encode the <code>rawPass</code> (using the optional <code>salt</code>), and then 126 * compared it with the presented <code>encPass</code>. 127 * </p> 128 * 129 * <p> 130 * For a discussion of salts, please refer to {@link #encodePassword(String, Object)}. 131 * </p> 132 * 133 * @param encPass a pre-encoded password 134 * @param rawPass a raw password to encode and compare against the pre-encoded password 135 * @param salt optionally used by the implementation to "salt" the raw password before encoding. A 136 * <code>null</code> value is legal. 137 * 138 * @return true if the password is valid , false otherwise 139 */ 140 boolean isPasswordValid( String encPass, String rawPass, Object salt ); 141 }