UserAdminPermission
Date: 2016-06-25

org.osgi.service.useradmin

## Class UserAdminPermission

- java.lang.Object
- - java.security.Permission
  - - java.security.BasicPermission
    - - org.osgi.service.useradmin.UserAdminPermission

- All Implemented Interfaces:
    java.io.Serializable, java.security.Guard

      public final class UserAdminPermission
      extends java.security.BasicPermission

  Permission to configure and access the `Role` objects managed by a User Admin service.

  This class represents access to the `Role` objects managed by a User Admin service and their properties and credentials (in the case of `User` objects).

  The permission name is the name (or name prefix) of a property or credential. The naming convention follows the hierarchical property naming convention. Also, an asterisk may appear at the end of the name, following a ".", or by itself, to signify a wildcard match. For example: "org.osgi.security.protocol.*" or "*" is valid, but "*protocol" or "a*b" are not valid.

  The `UserAdminPermission` with the reserved name "admin" represents the permission required for creating and removing `Role` objects in the User Admin service, as well as adding and removing members in a `Group` object. This `UserAdminPermission` does not have any actions associated with it.

  The actions to be granted are passed to the constructor in a string containing a list of one or more comma-separated keywords. The possible keywords are: `changeProperty`,`changeCredential`, and `getCredential`. Their meaning is defined as follows:

        action
        changeProperty    Permission to change (i.e., add and remove)
                          Role object properties whose names start with
                          the name argument specified in the constructor.
        changeCredential  Permission to change (i.e., add and remove)
                          User object credentials whose names start
                          with the name argument specified in the constructor.
        getCredential     Permission to retrieve and check for the
                          existence of User object credentials whose names
                          start with the name argument specified in the
                          constructor.

  The action string is converted to lowercase before processing.

  Following is a PermissionInfo style policy entry which grants a user administration bundle a number of `UserAdminPermission` object:

        (org.osgi.service.useradmin.UserAdminPermission "admin")
        (org.osgi.service.useradmin.UserAdminPermission "com.foo.*"
                      "changeProperty,getCredential,changeCredential")
        (org.osgi.service.useradmin.UserAdminPermission "user.*"
                                    "changeProperty,changeCredential")

  The first permission statement grants the bundle the permission to perform any User Admin service operations of type "admin", that is, create and remove roles and configure `Group` objects.

  The second permission statement grants the bundle the permission to change any properties as well as get and change any credentials whose names start with `com.foo.`.

  The third permission statement grants the bundle the permission to change any properties and credentials whose names start with `user.`. This means that the bundle is allowed to change, but not retrieve any credentials with the given prefix.

  The following policy entry empowers the Http Service bundle to perform user authentication:

        grant codeBase "${jars}http.jar" {
          permission org.osgi.service.useradmin.UserAdminPermission
            "user.password", "getCredential";
        };

  The permission statement grants the Http Service bundle the permission to validate any password credentials (for authentication purposes), but the bundle is not allowed to change any properties or credentials.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ADMIN` The permission name "admin".
    `static java.lang.String` | `CHANGE_CREDENTIAL` The action string "changeCredential".
    `static java.lang.String` | `CHANGE_PROPERTY` The action string "changeProperty".
    `static java.lang.String` | `GET_CREDENTIAL` The action string "getCredential".

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UserAdminPermission(java.lang.String name, java.lang.String actions)` Creates a new `UserAdminPermission` with the specified name and actions.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Checks two `UserAdminPermission` objects for equality.
    `java.lang.String` | `getActions()` Returns the canonical string representation of the actions, separated by comma.
    `int` | `hashCode()` Returns the hash code value for this object.
    `boolean` | `implies(java.security.Permission p)` Checks if this `UserAdminPermission` object "implies" the specified permission.
    `java.security.PermissionCollection` | `newPermissionCollection()` Returns a new `PermissionCollection` object for storing `UserAdminPermission` objects.
    `java.lang.String` | `toString()` Returns a string describing this `UserAdminPermission` object.

    - ### Methods inherited from class java.security.Permission

      `checkGuard, getName`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### ADMIN

          public static final java.lang.String ADMIN

      The permission name "admin".
      See Also:
        Constant Field Values

    - #### CHANGE_PROPERTY

          public static final java.lang.String CHANGE_PROPERTY

      The action string "changeProperty".
      See Also:
        Constant Field Values

    - #### CHANGE_CREDENTIAL

          public static final java.lang.String CHANGE_CREDENTIAL

      The action string "changeCredential".
      See Also:
        Constant Field Values

    - #### GET_CREDENTIAL

          public static final java.lang.String GET_CREDENTIAL

      The action string "getCredential".
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### UserAdminPermission

          public UserAdminPermission(java.lang.String name,
                             java.lang.String actions)

      Creates a new `UserAdminPermission` with the specified name and actions. `name` is either the reserved string "admin" or the name of a credential or property, and `actions` contains a comma-separated list of the actions granted on the specified name. Valid actions are `changeProperty`,`changeCredential`, and getCredential.
      Parameters:
        `name` - the name of this `UserAdminPermission`
        `actions` - the action string.
      Throws:
        `java.lang.IllegalArgumentException` - If `name` equals "admin" and `actions` are specified.

  - ### Method Detail

    - #### implies

          public boolean implies(java.security.Permission p)

      Checks if this `UserAdminPermission` object "implies" the specified permission.

      More specifically, this method returns `true` if:

      - p is an instanceof `UserAdminPermission`,
      - p's actions are a proper subset of this object's actions, and
      - p's name is implied by this object's name. For example, "java.*" implies "java.home".
      Overrides:
        `implies` in class `java.security.BasicPermission`
      Parameters:
        `p` - the permission to check against.
      Returns:
        `true` if the specified permission is implied by this object; `false` otherwise.

    - #### getActions

          public java.lang.String getActions()

      Returns the canonical string representation of the actions, separated by comma.
      Overrides:
        `getActions` in class `java.security.BasicPermission`
      Returns:
        the canonical string representation of the actions.

    - #### newPermissionCollection

          public java.security.PermissionCollection newPermissionCollection()

      Returns a new `PermissionCollection` object for storing `UserAdminPermission` objects.
      Overrides:
        `newPermissionCollection` in class `java.security.BasicPermission`
      Returns:
        a new `PermissionCollection` object suitable for storing `UserAdminPermission` objects.

    - #### equals

          public boolean equals(java.lang.Object obj)

      Checks two `UserAdminPermission` objects for equality. Checks that `obj` is a `UserAdminPermission`, and has the same name and actions as this object.
      Overrides:
        `equals` in class `java.security.BasicPermission`
      Parameters:
        `obj` - the object to be compared for equality with this object.
      Returns:
        `true` if `obj` is a `UserAdminPermission` object, and has the same name and actions as this `UserAdminPermission` object.

    - #### hashCode

          public int hashCode()

      Returns the hash code value for this object.
      Overrides:
        `hashCode` in class `java.security.BasicPermission`
      Returns:
        A hash code value for this object.

    - #### toString

          public java.lang.String toString()

      Returns a string describing this `UserAdminPermission` object. This string must be in `PermissionInfo` encoded format.
      Overrides:
        `toString` in class `java.security.Permission`
      Returns:
        The `PermissionInfo` encoded string for this `UserAdminPermission` object.
      See Also:
        "org.osgi.service.permissionadmin.PermissionInfo.getEncoded()"