001package org.apache.archiva.redback.policy; 002 003/* 004 * Copyright 2001-2006 The Apache Software Foundation. 005 * 006 * Licensed under the Apache License, Version 2.0 (the "License"); 007 * you may not use this file except in compliance with the License. 008 * You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 019/** 020 * <p> 021 * Interface for performing authentication operations on a password. 022 * </p> 023 * 024 * <p>Javadoc about encoding and salts copied from Acegi Security.</p> 025 * 026 * @author colin sampaleanu 027 * @author <a href="mailto:joakim@erdfelt.com">Joakim Erdfelt</a> 028 * 029 */ 030public interface PasswordEncoder 031{ 032 033 /** 034 * <p> 035 * Sets the system wide salt to use in the encoder. 036 * </p> 037 * 038 * <p> 039 * The specified salt will potentially be used by the implementation to "salt" the initial value before 040 * encoding. A salt is usually a user-specific value which is added to the password before the digest is computed. 041 * This means that computation of digests for common dictionary words will be different than those in the backend 042 * store, because the dictionary word digests will not reflect the addition of the salt. If a per-user salt is 043 * used (rather than a system-wide salt), it also means users with the same password will have different digest 044 * encoded passwords in the backend store. 045 * </p> 046 * 047 * @param salt the salt to use as a default for the encoder. 048 */ 049 void setSystemSalt( Object salt ); 050 051 /** 052 * <p> 053 * Encodes the specified raw password with an implementation specific algorithm, using the system wide salt. 054 * </p> 055 * 056 * <p> 057 * This will generally be a one-way message digest such as MD5 or SHA, but may also be a plaintext 058 * variant which does no encoding at all, but rather returns the same password it was fed. The latter is useful to 059 * plug in when the original password must be stored as-is. 060 * </p> 061 * 062 * @param rawPass the password to encode 063 * 064 * @return encoded password 065 */ 066 String encodePassword( String rawPass ); 067 068 /** 069 * <p> 070 * Encodes the specified raw password with an implementation specific algorithm, using user specific salt. 071 * </p> 072 * 073 * <p> 074 * This will generally be a one-way message digest such as MD5 or SHA, but may also be a plaintext 075 * variant which does no encoding at all, but rather returns the same password it was fed. The latter is useful to 076 * plug in when the original password must be stored as-is. 077 * </p> 078 * 079 * <p> 080 * The specified salt will potentially be used by the implementation to "salt" the initial value before 081 * encoding. A salt is usually a user-specific value which is added to the password before the digest is computed. 082 * This means that computation of digests for common dictionary words will be different than those in the backend 083 * store, because the dictionary word digests will not reflect the addition of the salt. If a per-user salt is 084 * used (rather than a system-wide salt), it also means users with the same password will have different digest 085 * encoded passwords in the backend store. 086 * </p> 087 * 088 * @param rawPass the password to encode 089 * @param salt optionally used by the implementation to "salt" the raw password before encoding. 090 * A <code>null</code> value is legal. 091 * @return encoded password 092 */ 093 String encodePassword( String rawPass, Object salt ); 094 095 096 /** 097 * <p> 098 * Validates a specified "raw" password against an encoded password, using the system wide salt. 099 * </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}