1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. 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, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 module hunt.shiro.authz.permission.Permission; 20 21 import hunt.util.Common; 22 23 /** 24 * A Permission represents the ability to perform an action or access a resource. A Permission is the most 25 * granular, or atomic, unit in a system's security policy and is the cornerstone upon which fine-grained security 26 * models are built. 27 * <p/> 28 * It is important to understand a Permission instance only represents functionality or access - it does not grant it. 29 * Granting access to an application functionality or a particular resource is done by the application's security 30 * configuration, typically by assigning Permissions to users, roles and/or groups. 31 * <p/> 32 * Most typical systems are what the Shiro team calls <em>role-based</em> in nature, where a role represents 33 * common behavior for certain user types. For example, a system might have an <em>Administrator</em> role, a 34 * <em>User</em> or <em>Guest</em> roles, etc. 35 * <p/> 36 * But if you have a dynamic security model, where roles can be created and deleted at runtime, you can't hard-code 37 * role names in your code. In this environment, roles themselves aren't aren't very useful. What matters is what 38 * <em>permissions</em> are assigned to these roles. 39 * <p/> 40 * Under this paradigm, permissions are immutable and reflect an application's raw functionality 41 * (opening files, accessing a web URL, creating users, etc). This is what allows a system's security policy 42 * to be dynamic: because Permissions represent raw functionality and only change when the application's 43 * source code changes, they are immutable at runtime - they represent 'what' the system can do. Roles, users, and 44 * groups are the 'who' of the application. Determining 'who' can do 'what' then becomes a simple exercise of 45 * associating Permissions to roles, users, and groups in some way. 46 * <p/> 47 * Most applications do this by associating a named role with permissions (i.e. a role 'has a' collection of 48 * Permissions) and then associate users with roles (i.e. a user 'has a' collection of roles) so that by transitive 49 * association, the user 'has' the permissions in their roles. There are numerous variations on this theme 50 * (permissions assigned directly to users, or assigned to groups, and users added to groups and these groups in turn 51 * have roles, etc, etc). When employing a permission-based security model instead of a role-based one, users, roles, 52 * and groups can all be created, configured and/or deleted at runtime. This enables an extremely powerful security 53 * model. 54 * <p/> 55 * A benefit to Shiro is that, although it assumes most systems are based on these types of static role or 56 * dynamic role w/ permission schemes, it does not require a system to model their security data this way - all 57 * Permission checks are relegated to {@link hunt.shiro.realm.Realm} implementations, and only those 58 * implementations really determine how a user 'has' a permission or not. The Realm could use the semantics described 59 * here, or it could utilize some other mechanism entirely - it is always up to the application developer. 60 * <p/> 61 * Shiro provides a very powerful default implementation of this interface in the form of the 62 * {@link hunt.shiro.authz.permission.WildcardPermission WildcardPermission}. We highly recommend that you 63 * investigate this class before trying to implement your own <code>Permission</code>s. 64 * 65 * @see hunt.shiro.authz.permission.WildcardPermission WildcardPermission 66 */ 67 interface Permission : Comparable!Permission { 68 69 /** 70 * Returns {@code true} if this current instance <em>implies</em> all the functionality and/or resource access 71 * described by the specified {@code Permission} argument, {@code false} otherwise. 72 * <p/> 73 * <p>That is, this current instance must be exactly equal to or a <em>superset</em> of the functionality 74 * and/or resource access described by the given {@code Permission} argument. Yet another way of saying this 75 * would be: 76 * <p/> 77 * <p>If "permission1 implies permission2", i.e. <code>permission1.implies(permission2)</code> , 78 * then any Subject granted {@code permission1} would have ability greater than or equal to that defined by 79 * {@code permission2}. 80 * 81 * @param p the permission to check for behavior/functionality comparison. 82 * @return {@code true} if this current instance <em>implies</em> all the functionality and/or resource access 83 * described by the specified {@code Permission} argument, {@code false} otherwise. 84 */ 85 bool implies(Permission p); 86 }