View Javadoc

1   /* 
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.jetspeed.security.spi;
18  
19  import java.sql.Date;
20  import java.util.Set;
21  
22  import org.apache.jetspeed.security.SecurityException;
23  
24  /***
25   * <p>
26   * This interface encapsulates the handling of security credentials.
27   * </p>
28   * <p>
29   * This provides a central placeholder for changing the mapping of user
30   * credentials.  The default implementation only supports <code>PasswordCredential</code>
31   * </p>
32   * <p>
33   * A security implementation wanting to map additional credentials should do so
34   * here.
35   * </p>
36   * 
37   * @author <a href="mailto:dlestrat@apache.org">David Le Strat </a>
38   */
39  public interface CredentialHandler
40  {
41      /***
42       * <p>
43       * Gets the public credentials for the user.
44       * </p>
45       * 
46       * @param username The username.
47       * @return The set of public credentials.
48       */
49      Set getPublicCredentials(String username);
50      
51      /***
52       * <p>
53       * Gets the private credentials for the user.
54       * </p>
55       * 
56       * @param username The username.
57       * @return The set of private credentials.
58       */
59      Set getPrivateCredentials(String username);
60      
61      /***
62       * <p>
63       * Adds or updates a private password credential.<br>
64       * Note that there is no checking of the <code>oldPassword</code> and the provided password is 
65       * assumed to be encoded. Hence no encoding will take place.
66       * 
67       * </p>
68       * 
69       * @param username The user to be updated.
70       * @param newPassword The new password.
71       * @throws SecurityException Throws a {@link SecurityException}.
72       */
73      void importPassword(String userName, String newPassword) throws SecurityException;
74  
75      
76      /***
77       * <p>
78       * Adds or updates a private password credential.<br>
79       * If <code>oldPassword</code> is not null, the oldPassword will first be checked (authenticated).<br>
80       * </p>
81       * 
82       * @param username The user to be updated.
83       * @param oldPassword The old password.
84       * @param newPassword The new password.
85       * @throws SecurityException Throws a {@link SecurityException}.
86       */
87      void setPassword(String userName, String oldPassword, String newPassword) throws SecurityException;
88  
89      
90      
91      /***
92       * <p>
93       * Set the update required state of the user password credential.
94       * </p>
95       * 
96       * @param userName The user name.
97       * @param updateRequired The update required state.
98       * @throws Throws a security exception.
99       */
100     void setPasswordUpdateRequired(String userName, boolean updateRequired) throws SecurityException;
101 
102     /***
103      * <p>
104      * Set the enabled state of the user password credential.
105      * </p>
106      * 
107      * @param userName The user name.
108      * @param enabled The enabled state.
109      * @throws Throws a security exception.
110      */
111     void setPasswordEnabled(String userName, boolean enabled) throws SecurityException;
112 
113     /***
114      * <p>
115      * Set the expiration date and the expired flag of the password credential.</p>
116      * <p>
117      * If a date equal or before the current date is provided, the expired flag will be set to true,
118      * otherwise to false.</p>
119      * 
120      * @param userName The user name.
121      * @param expirationDate The expiration date to set.
122      * @throws Throws a security exception.
123      */
124     void setPasswordExpiration(String userName, Date expirationDate) throws SecurityException;
125 
126     /***
127      * <p>
128      * Authenticate a user.
129      * </p>
130      * 
131      * @param userName The user name.
132      * @param password The user password.
133      * @return Whether or not a user is authenticated.
134      */
135     boolean authenticate(String userName, String password) throws SecurityException;
136 }