001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  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,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.shiro.authz;
020    
021    /**
022     * A Permission represents the ability to perform an action or access a resource.  A Permission is the most
023     * granular, or atomic, unit in a system's security policy and is the cornerstone upon which fine-grained security
024     * models are built.
025     * <p/>
026     * It is important to understand a Permission instance only represents functionality or access - it does not grant it.
027     * Granting access to an application functionality or a particular resource is done by the application's security
028     * configuration, typically by assigning Permissions to users, roles and/or groups.
029     * <p/>
030     * Most typical systems are what the Shiro team calls <em>role-based</em> in nature, where a role represents
031     * common behavior for certain user types.  For example, a system might have an <em>Aministrator</em> role, a
032     * <em>User</em> or <em>Guest</em> roles, etc.
033     * <p/>
034     * But if you have a dynamic security model, where roles can be created and deleted at runtime, you can't hard-code
035     * role names in your code.  In this environment, roles themselves aren't aren't very useful.  What matters is what
036     * <em>permissions</em> are assigned to these roles.
037     * <p/>
038     * Under this paradigm, permissions are immutable and reflect an application's raw functionality
039     * (opening files, accessing a web URL, creating users, etc).  This is what allows a system's security policy
040     * to be dynamic: because Permissions represent raw functionality and only change when the application's
041     * source code changes, they are immutable at runtime - they represent 'what' the system can do.  Roles, users, and
042     * groups are the 'who' of the application.  Determining 'who' can do 'what' then becomes a simple exercise of
043     * associating Permissions to roles, users, and groups in some way.
044     * <p/>
045     * Most applications do this by associating a named role with permissions (i.e. a role 'has a' collection of
046     * Permissions) and then associate users with roles (i.e. a user 'has a' collection of roles) so that by transitive
047     * association, the user 'has' the permissions in their roles.  There are numerous variations on this theme
048     * (permissions assigned directly to users, or assigned to groups, and users added to groups and these groups in turn
049     * have roles, etc, etc).  When employing a permission-based security model instead of a role-based one, users, roles,
050     * and groups can all be created, configured and/or deleted at runtime.  This enables  an extremely powerful security
051     * model.
052     * <p/>
053     * A benefit to Shiro is that, although it assumes most systems are based on these types of static role or
054     * dynamic role w/ permission schemes, it does not require a system to model their security data this way - all
055     * Permission checks are relegated to {@link org.apache.shiro.realm.Realm} implementations, and only those
056     * implementations really determine how a user 'has' a permission or not.  The Realm could use the semantics described
057     * here, or it could utilize some other mechanism entirely - it is always up to the application developer.
058     * <p/>
059     * Shiro provides a very powerful default implementation of this interface in the form of the
060     * {@link org.apache.shiro.authz.permission.WildcardPermission WildcardPermission}.  We highly recommend that you
061     * investigate this class before trying to implement your own <code>Permission</code>s.
062     *
063     * @see org.apache.shiro.authz.permission.WildcardPermission WildcardPermission
064     * @since 0.2
065     */
066    public interface Permission {
067    
068        /**
069         * Returns {@code true} if this current instance <em>implies</em> all the functionality and/or resource access
070         * described by the specified {@code Permission} argument, {@code false} otherwise.
071         * <p/>
072         * <p>That is, this current instance must be exactly equal to or a <em>superset</em> of the functionalty
073         * and/or resource access described by the given {@code Permission} argument.  Yet another way of saying this
074         * would be:
075         * <p/>
076         * <p>If &quot;permission1 implies permission2&quot;, i.e. <code>permission1.implies(permission2)</code> ,
077         * then any Subject granted {@code permission1} would have ability greater than or equal to that defined by
078         * {@code permission2}.
079         *
080         * @param p the permission to check for behavior/functionality comparison.
081         * @return {@code true} if this current instance <em>implies</em> all the functionality and/or resource access
082         *         described by the specified {@code Permission} argument, {@code false} otherwise.
083         */
084        boolean implies(Permission p);
085    }