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}