Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.jini.security
Class AuthenticationPermission

    java.lang.Object
      java.security.Permission
          net.jini.security.AuthenticationPermission

All Implemented Interfaces:
  Guard, Serializable

public final class AuthenticationPermission
extends Permission

Represents permission to use the private credentials of subjects for the purpose of authenticating as any subset of the local principals specified in the target name, during secure remote calls with any peer that authenticates as at least the set of peer principals specified in the target name. In general, security providers check for this permission instead of checking for `PrivateCredentialPermission`. This permission does not need to be granted for anonymous communication; it only needs to be granted if an entity needs to authenticate itself.

An instance of this class contains a name (also referred to as a "target name") and a set of actions. The target name specifies both the maximum set of principals that an entity can authenticate as, and the minimum set of principals that the peer must authenticate as. The actions specify whether the permission is granted for making outbound remote calls with or without delegation, listening for incoming remote calls, receiving incoming remote calls, or some combination.

The syntax of the target name is either:

    LocalPrincipals

or:

    LocalPrincipals peer PeerPrincipals

where LocalPrincipals specifies the maximum set of principals that an entity can authenticate as (that is, the entity can authenticate as any subset of these principals), and PeerPrincipals specifies the minimum set of principals that the peer must authenticate as (that is, the peer must authenticate as at least all of these principals). If the first syntactic form is used, the peer can authenticate as anyone (and can be anonymous). The syntax of both LocalPrincipals and PeerPrincipals is:

    PrincipalClass "PrincipalName" ...

That is, alternating principal classes and principal names, separated by spaces, with each principal name surrounded by quotes. The order in which principals are specified does not matter, but both class names and principal names are case sensitive. For LocalPrincipals, in any given principal specification, a wildcard value of "*" can be used for both PrincipalClass and PrincipalName or for just PrincipalName, but it is illegal to use a wildcard value for just PrincipalClass. Explicit wildcard values cannot be used in PeerPrincipals; only complete wildcarding of the peer is supported, and is expressed by using the first syntactic form instead.

The syntax of the actions is a comma-separated list of any of the following (case-insensitive) action names: `listen`, `accept`, `connect`, `delegate`. The `listen` action grants permission to authenticate as the server when listening for incoming remote calls; in this case, the peer principals are ignored (because it is assumed that in general servers authenticate themselves before clients do). The `accept` action grants permission to receive authenticated incoming remote calls; in this case, the entity has authenticated as the server, and the peer has authenticated as the client. If the `accept` action is specified, the `listen` action is implied and need not be specified explicitly. The `connect` action grants permission to authenticate when making outgoing remote calls; in this case, the entity authenticates as the client, and the peer authenticates as the server. The `delegate` action grants permission to authenticate with (or without) delegation when making outgoing remote calls. If the `delegate` action is specified, the `connect` action is implied and need not be specified explicitly.

A principal `p` matches LocalPrincipals if LocalPrincipals has any of the following principal specifications:

- "*" for both PrincipalClass and PrincipalName
- a PrincipalClass equal to the value of `p.getClass().getName()` and a PrincipalName equal to "*"
- a PrincipalClass equal to the value of `p.getClass().getName()` and a PrincipalName equal to the value of `p.getName()`

A principal `p` matches PeerPrincipals if PeerPrincipals has a PrincipalClass equal to the value of `p.getClass().getName()` and a PrincipalName equal to the value of `p.getName()`.

Some example policy file permissions:

     // client authenticate as jack, with or without delegation, to any server
     permission net.jini.security.AuthenticationPermission
         "javax.security.auth.x500.X500Principal \"CN=jack\"", "delegate";

     // client authenticate as joe and/or sue, without delegation, to any server
     permission net.jini.security.AuthenticationPermission
         "javax.security.auth.x500.X500Principal \"CN=joe\" javax.security.auth.x500.X500Principal \"CN=sue\"", "connect";

     // client authenticate as any X500 principals, without delegation, to jack
     permission net.jini.security.AuthenticationPermission
         "javax.security.auth.x500.X500Principal \"*\" peer javax.security.auth.x500.X500Principal \"CN=jack\"", "connect";

     // authenticate as jack to jack, bi-directional, with or without delegation
     permission net.jini.security.AuthenticationPermission
         "javax.security.auth.x500.X500Principal \"CN=jack\" peer javax.security.auth.x500.X500Principal \"CN=jack\"", "accept,delegate";

     // authenticate as anyone to jack, bi-directional, without delegation
     permission net.jini.security.AuthenticationPermission
         "* \"*\" peer javax.security.auth.x500.X500Principal \"CN=jack\"", "accept,connect";

Since:
  2.0
See Also:
  Serialized Form

Constructor Summary
`AuthenticationPermission(Set local, Set peer, String actions)` Creates an instance with the specified actions and a target name constructed from the specified local and peer principals.
`AuthenticationPermission(String name, String actions)` Creates an instance with the specified target name and actions.

Method Summary
`boolean` | `equals(Object obj)` Two instances of this class are equal if each implies the other; that is, both instances have the same actions, every principal that matches the local principals of one instance matches the local principals of the other instance, and (if the instances have any action besides `listen`) every principal that matches the peer principals of one instance matches the peer principals of the other instance.
`String` | `getActions()` Returns the actions.
`int` | `hashCode()` Returns a hash code value for this object.
`boolean` | `implies(Permission perm)` Returns `true` if the specified permission is an instance of `AuthenticationPermission`, and every action included in the specified permission is included as an action of this permission, and every principal that matches the local principals of the specified permission also matches the local principals of this permission, and (if the specified permission has any action besides `listen`) every principal that matches the peer principals of this permission also matches the peer principals of the specified permission; returns `false` otherwise.
`PermissionCollection` | `newPermissionCollection()` Returns an empty `PermissionCollection` for storing `AuthenticationPermission` instances.

Methods inherited from class java.security.Permission
`checkGuard, getName, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Constructor Detail

### AuthenticationPermission

    public AuthenticationPermission(String name,
                                    String actions)

  Creates an instance with the specified target name and actions.

Parameters:
  `name` - the target name
  `actions` - the actions
Throws:
  `NullPointerException` - if the target name or actions string is `null`
  `IllegalArgumentException` - if the target name or actions string does not match the syntax specified in the comments at the beginning of this class

### AuthenticationPermission

    public AuthenticationPermission(Set local,
                                    Set peer,
                                    String actions)

  Creates an instance with the specified actions and a target name constructed from the specified local and peer principals.

Parameters:
  `local` - the local principals
  `peer` - the peer principals, or `null`
  `actions` - the actions
Throws:
  `NullPointerException` - if the local principals set or the actions string is `null`
  `IllegalArgumentException` - if the local principals set is empty, or either set contains objects that are not `java.security.Principal` instances, or the actions string does not match the syntax specified in the comments at the beginning of this class

Method Detail

### implies

    public boolean implies(Permission perm)

  Returns `true` if the specified permission is an instance of `AuthenticationPermission`, and every action included in the specified permission is included as an action of this permission, and every principal that matches the local principals of the specified permission also matches the local principals of this permission, and (if the specified permission has any action besides `listen`) every principal that matches the peer principals of this permission also matches the peer principals of the specified permission; returns `false` otherwise.

  Parameters:
    `perm` - the permission to check
  Returns:
    `true` if the specified permission is an instance of `AuthenticationPermission`, and every action included in the specified permission is included as an action of this permission, and every principal that matches the local principals of the specified permission also matches the local principals of this permission, and (if the specified permission has any action besides `listen`) every principal that matches the peer principals of this permission also matches the peer principals of the specified permission; `false` otherwise

### getActions

    public String getActions()

  Returns the actions.

### newPermissionCollection

    public PermissionCollection newPermissionCollection()

  Returns an empty `PermissionCollection` for storing `AuthenticationPermission` instances.

  Returns:
    an empty `PermissionCollection` for storing `AuthenticationPermission` instances

### equals

    public boolean equals(Object obj)

  Two instances of this class are equal if each implies the other; that is, both instances have the same actions, every principal that matches the local principals of one instance matches the local principals of the other instance, and (if the instances have any action besides `listen`) every principal that matches the peer principals of one instance matches the peer principals of the other instance.

### hashCode

    public int hashCode()

  Returns a hash code value for this object.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved