+ * Note:This class is not yet implemented! + *
* + * @author rvonburg */ public class BootstrapConfigurationHelper { -// private static final Logger logger = Logger.getLogger(BootstrapConfigurationHelper.class); + + // private static final Logger logger = Logger.getLogger(BootstrapConfigurationHelper.class); private static String path; @@ -58,6 +62,7 @@ public class BootstrapConfigurationHelper { /** * @param args + * the args from the command line */ public static void main(String[] args) { BasicConfigurator.resetConfiguration(); diff --git a/src/ch/eitchnet/privilege/helper/ClassHelper.java b/src/ch/eitchnet/privilege/helper/ClassHelper.java index 1ecdae89f..eda6f8eea 100644 --- a/src/ch/eitchnet/privilege/helper/ClassHelper.java +++ b/src/ch/eitchnet/privilege/helper/ClassHelper.java @@ -16,7 +16,6 @@ import ch.eitchnet.privilege.i18n.PrivilegeException; * The {@link ClassHelper} class is a helper to instantiate classes using reflection * * @author rvonburg - * */ public class ClassHelper { diff --git a/src/ch/eitchnet/privilege/helper/HashHelper.java b/src/ch/eitchnet/privilege/helper/HashHelper.java index fa095ffca..cbf6ae8f3 100644 --- a/src/ch/eitchnet/privilege/helper/HashHelper.java +++ b/src/ch/eitchnet/privilege/helper/HashHelper.java @@ -15,8 +15,9 @@ import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; /** - * @author rvonburg + * Helper class to hash a String for a certain hash algorithm, using the Java {@link MessageDigest} classes * + * @author rvonburg */ public class HashHelper { diff --git a/src/ch/eitchnet/privilege/helper/InitializationHelper.java b/src/ch/eitchnet/privilege/helper/InitializationHelper.java index 46a723212..e0c2aadb6 100644 --- a/src/ch/eitchnet/privilege/helper/InitializationHelper.java +++ b/src/ch/eitchnet/privilege/helper/InitializationHelper.java @@ -24,15 +24,20 @@ import ch.eitchnet.privilege.handler.PrivilegeHandler; import ch.eitchnet.privilege.i18n.PrivilegeException; /** - * @author rvonburg + * This class implements the initializing of the {@link PrivilegeHandler} by loading an XML file containing the + * configuration * + * @author rvonburg */ public class InitializationHelper { private static final Logger logger = Logger.getLogger(InitializationHelper.class); /** + * Initializes the {@link PrivilegeHandler} from the configuration file + * * @param privilegeContainerXmlFile + * a {@link File} reference to the XML file containing the configuration for Privilege * * @return the {@link PrivilegeHandler} instance loaded from the configuration file */ @@ -110,7 +115,12 @@ public class InitializationHelper { } /** + * Converts an {@link XmlConstants#XML_PARAMETERS} element containing {@link XmlConstants#XML_PARAMETER} elements to + * a {@link Map} of String key/value pairs + * * @param element + * the XML {@link Element} with name {@link XmlConstants#XML_PARAMETERS} containing + * {@link XmlConstants#XML_PARAMETER} elements * * @return the {@link Map} of the parameter name/value combinations from the given {@link Element} */ diff --git a/src/ch/eitchnet/privilege/helper/PasswordCreator.java b/src/ch/eitchnet/privilege/helper/PasswordCreator.java index adf243d26..a70dda885 100644 --- a/src/ch/eitchnet/privilege/helper/PasswordCreator.java +++ b/src/ch/eitchnet/privilege/helper/PasswordCreator.java @@ -15,14 +15,23 @@ import java.io.InputStreamReader; import java.security.MessageDigest; /** - * @author rvonburg + *+ * Simple main class which can be used to create a hash from a password which the user must type in at the command line + *
* + *+ * TODO: Note: currently the password input is echoed which is a security risk. This is a TODO + *
+ * + * @author rvonburg */ public class PasswordCreator { /** * @param args - * @throws Exception + * the args from the command line, NOT USED + * @throws Exception + * thrown if anything goes wrong */ public static void main(String[] args) throws Exception { diff --git a/src/ch/eitchnet/privilege/helper/XmlConstants.java b/src/ch/eitchnet/privilege/helper/XmlConstants.java index 06f838c9f..465e1cf53 100644 --- a/src/ch/eitchnet/privilege/helper/XmlConstants.java +++ b/src/ch/eitchnet/privilege/helper/XmlConstants.java @@ -11,8 +11,9 @@ package ch.eitchnet.privilege.helper; /** - * @author rvonburg + * The constants used in parsing XML documents which contain the configuration for Privilege * + * @author rvonburg */ public class XmlConstants { /** diff --git a/src/ch/eitchnet/privilege/helper/XmlHelper.java b/src/ch/eitchnet/privilege/helper/XmlHelper.java index 53febb9ab..c77dcec08 100644 --- a/src/ch/eitchnet/privilege/helper/XmlHelper.java +++ b/src/ch/eitchnet/privilege/helper/XmlHelper.java @@ -30,8 +30,9 @@ import org.dom4j.io.XMLWriter; import ch.eitchnet.privilege.i18n.PrivilegeException; /** - * @author rvonburg + * Helper class for performing XML based tasks using Dom4J * + * @author rvonburg */ public class XmlHelper { diff --git a/src/ch/eitchnet/privilege/i18n/AccessDeniedException.java b/src/ch/eitchnet/privilege/i18n/AccessDeniedException.java index c84978e3f..339bd6fed 100644 --- a/src/ch/eitchnet/privilege/i18n/AccessDeniedException.java +++ b/src/ch/eitchnet/privilege/i18n/AccessDeniedException.java @@ -11,17 +11,19 @@ package ch.eitchnet.privilege.i18n; /** - * @author rvonburg + * Exception thrown if access is denied during login, or if a certain privilege is not granted * + * @author rvonburg */ public class AccessDeniedException extends PrivilegeException { private static final long serialVersionUID = 1L; /** - * @param string + * @param msg + * detail on why and where access was denied */ - public AccessDeniedException(String string) { - super(string); + public AccessDeniedException(String msg) { + super(msg); } } diff --git a/src/ch/eitchnet/privilege/i18n/PrivilegeException.java b/src/ch/eitchnet/privilege/i18n/PrivilegeException.java index 4960a42f9..decd696a9 100644 --- a/src/ch/eitchnet/privilege/i18n/PrivilegeException.java +++ b/src/ch/eitchnet/privilege/i18n/PrivilegeException.java @@ -11,24 +11,31 @@ package ch.eitchnet.privilege.i18n; /** - * @author rvonburg + * Main {@link RuntimeException} thrown if something goes wrong in Privilege * + * @author rvonburg */ public class PrivilegeException extends RuntimeException { private static final long serialVersionUID = 1L; /** + * Default constructor + * * @param string + * message to go with the exception */ public PrivilegeException(String string) { super(string); } /** + * Constructor with underlying exception * * @param string + * message to go with the exception * @param t + * throwable to wrap with this exception which is the underlying exception of this exception */ public PrivilegeException(String string, Throwable t) { super(string, t); diff --git a/src/ch/eitchnet/privilege/model/Certificate.java b/src/ch/eitchnet/privilege/model/Certificate.java index e55af8a44..7dfe3b6a9 100644 --- a/src/ch/eitchnet/privilege/model/Certificate.java +++ b/src/ch/eitchnet/privilege/model/Certificate.java @@ -13,11 +13,16 @@ package ch.eitchnet.privilege.model; import java.io.Serializable; import java.util.Locale; +import ch.eitchnet.privilege.handler.PrivilegeHandler; import ch.eitchnet.privilege.i18n.PrivilegeException; +import ch.eitchnet.privilege.model.internal.Session; /** - * @author rvonburg + * The {@link Certificate} is the object a client keeps when accessing a Privilege enabled system. This object is the + * instance which is always used when performing an access and is returned when a user performs a login through + * {@link PrivilegeHandler#authenticate(String, String)} * + * @author rvonburg */ public final class Certificate implements Serializable { @@ -31,11 +36,22 @@ public final class Certificate implements Serializable { private Locale locale; /** + * Default constructor initializing with all information needed for this certificate + * + *Note, both the authentication token and password are private fields which are generated on login and only known by the {@link PrivilegeHandler}
+ * * @param sessionId + * the users session id * @param username + * the users login name * @param authToken + * the authentication token defining the users unique session and is a private field of this certificate. + * It corresponds with the authentication token on the {@link Session} * @param authPassword + * the password to access the authentication token, this is not known to the client but set by the + * {@link PrivilegeHandler} on authentication. It corresponds with the authentication password on the {@link Session} * @param locale + * the users {@link Locale} */ public Certificate(String sessionId, String username, String authToken, String authPassword, Locale locale) { @@ -86,12 +102,12 @@ public final class Certificate implements Serializable { } /** - * Returns the authToken if the given authPassword is corret, null otherwise + * Returns the authToken if the given authPassword is correct, null otherwise * * @param authPassword - * the auth password with which this certificate was created + * the authentication password with which this certificate was created * - * @return the authToken if the given authPassword is corret, null otherwise + * @return the authToken if the given authPassword is correct, null otherwise */ public String getAuthToken(String authPassword) { if (this.authPassword.equals(authPassword)) @@ -170,5 +186,4 @@ public final class Certificate implements Serializable { builder.append("]"); return builder.toString(); } - } diff --git a/src/ch/eitchnet/privilege/model/PrivilegeRep.java b/src/ch/eitchnet/privilege/model/PrivilegeRep.java index 82ad3e070..5b92e4613 100644 --- a/src/ch/eitchnet/privilege/model/PrivilegeRep.java +++ b/src/ch/eitchnet/privilege/model/PrivilegeRep.java @@ -13,9 +13,17 @@ package ch.eitchnet.privilege.model; import java.io.Serializable; import java.util.Set; +import ch.eitchnet.privilege.handler.PrivilegeHandler; +import ch.eitchnet.privilege.model.internal.Privilege; +import ch.eitchnet.privilege.model.internal.Role; +import ch.eitchnet.privilege.policy.PrivilegePolicy; + /** - * @author rvonburg + * To keep certain details of the {@link Privilege} itself hidden from remote clients and make sure instances are only + * edited by users with the correct privilege, this representational version is allowed to be viewed by remote clients + * and simply wraps all public data from the {@link Privilege} * + * @author rvonburg */ public class PrivilegeRep implements Serializable { @@ -28,11 +36,19 @@ public class PrivilegeRep implements Serializable { private Set+ * Objects implementing this interface are used to grant/restrict privileges to them. A {@link PrivilegePolicy} + * implements the logic on granting/restricting privileges for a {@link Restrictable} and the + * {@link #getPrivilegeName()} is used to find the {@link Privilege} which has the associated {@link PrivilegePolicy} + * for evaluating access + *
* * @author rvonburg * diff --git a/src/ch/eitchnet/privilege/model/RoleRep.java b/src/ch/eitchnet/privilege/model/RoleRep.java index 8a7bb538f..019f1a408 100644 --- a/src/ch/eitchnet/privilege/model/RoleRep.java +++ b/src/ch/eitchnet/privilege/model/RoleRep.java @@ -13,9 +13,14 @@ package ch.eitchnet.privilege.model; import java.io.Serializable; import java.util.Set; +import ch.eitchnet.privilege.model.internal.Role; + /** - * @author rvonburg + * To keep certain details of the {@link Role} itself hidden from remote clients and make sure instances are only edited + * by users with the correct privilege, this representational version is allowed to be viewed by remote clients and + * simply wraps all public data from the {@link Role} * + * @author rvonburg */ public class RoleRep implements Serializable { @@ -25,8 +30,12 @@ public class RoleRep implements Serializable { private Set+ * {@link Privilege} is the main model object for Privilege. A {@link Role} has a set of Privileges assigned to it which + * defines the privileges a logged in user with that role has. For every privilege a {@link PrivilegePolicy} is + * configured which is used to evaluate if privilege is granted to a {@link Restrictable} + *
* + *+ * {@link Privilege}s have allow and deny rules which the configured {@link PrivilegeHandler} uses to + *
+ * + *Note: This is an internal object which is not to be serialized or passed to clients, {@link PrivilegeRep}s are used for that
+ * + * @author rvonburg */ public final class Privilege { @@ -29,12 +43,19 @@ public final class Privilege { private final Set+ * A {@link User} is assigned a set of roles. These roles have a set of privileges assigned to them by name and they + * define the privileges granted to a user with this role + *
* + *+ * Note: This is an internal object which is not to be serialized or passed to clients, {@link RoleRep}s are used for + * that + *
+ * + * @author rvonburg */ public final class Role { @@ -26,9 +35,12 @@ public final class Role { private final Set+ * A {@link Session} is linked to currently logged in user. The {@link PrivilegeHandler} creates an instance of this + * class once a {@link User} has successfully logged in and keeps this object private but hands out a + * {@link Certificate} which the user must use every time a privilege needs to be granted + *
* + *+ * Note: This is an internal object which is not to be serialized or passed to clients, the client must keep his + * {@link Certificate} which is used for accessing privileges + *
+ * + * @author rvonburg */ public final class Session { @@ -24,18 +37,32 @@ public final class Session { private final String authPassword; /** + * Default constructor + * + *+ * Note, both the authentication token and password are private fields which are generated on login and only known + * by the {@link PrivilegeHandler} + *
* * @param sessionId - * @param authToken - * @param authPassword + * the users session id * @param username + * the users login name + * @param authToken + * the authentication token defining the users unique session and is a private field of this session. It + * corresponds with the authentication token on the {@link Certificate} + * @param authPassword + * the password to access the authentication token, this is not known to the client but set by the + * {@link PrivilegeHandler} on authentication. It corresponds with the authentication password on the + * {@link Certificate} * @param loginTime + * the time the user logged in */ - public Session(String sessionId, String authToken, String authPassword, String username, long loginTime) { + public Session(String sessionId, String username, String authToken, String authPassword, long loginTime) { this.sessionId = sessionId; + this.username = username; this.authToken = authToken; this.authPassword = authPassword; - this.username = username; this.loginTime = loginTime; } diff --git a/src/ch/eitchnet/privilege/model/internal/User.java b/src/ch/eitchnet/privilege/model/internal/User.java index 176481429..2118763e3 100644 --- a/src/ch/eitchnet/privilege/model/internal/User.java +++ b/src/ch/eitchnet/privilege/model/internal/User.java @@ -19,6 +19,14 @@ import ch.eitchnet.privilege.model.UserRep; import ch.eitchnet.privilege.model.UserState; /** + * This class defines the actual login information for a given user which can be granted privileges. Every user is + * granted a set of {@link Role}s and has a {@link UserState} including detail information like first name and surname + * + *+ * Note: This is an internal object which is not to be serialized or passed to clients, {@link UserRep}s are used for + * that + *
+ * * @author rvonburg * */ @@ -39,14 +47,24 @@ public final class User { private final Locale locale; /** + * Default constructor + * * @param userId + * the user's id * @param username + * the user's login name * @param password + * the user's password (hashed) * @param firstname + * the user's first name * @param surname + * the user's surname * @param userState + * the user's {@link UserState} * @param roles + * the set of {@link Role}s assigned to this user * @param locale + * the user's {@link Locale} */ public User(String userId, String username, String password, String firstname, String surname, UserState userState, Set+ * {@link PrivilegePolicy} implements logic to determine if a {@link User} which has the given {@link Role} and the + * given {@link Privilege} has access to the given {@link Restrictable} + *
* + *+ * Re-think this interface and especially the {@link #actionAllowed(Role, Privilege, Restrictable)}-method... maybe we + * need one with out the {@link Privilege} in its signature? + *
+ * + * @author rvonburg */ public interface PrivilegePolicy { /** + * Checks if the given {@link Role} and the given {@link Privilege} has access to the given {@link Restrictable} + * * @param role + * the {@link Role} trying to access the {@link Restrictable} * @param privilege + * the {@link Privilege} to check with * @param restrictable + * the {@link Restrictable} to which the user wants access * * @return return true if the action is allowed, false if not */