AuthenticationPermission (Apache River v3.0.0 Specification-only API Documentation)

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

All Implemented Interfaces:

Serializable, Guard
```
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

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
    
    Specified by:
    
    implies in class Permission
    
    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.
    
    Specified by:
    
    getActions in class Permission
  - newPermissionCollection
```
public PermissionCollection newPermissionCollection()
```
    Returns an empty PermissionCollection for storing AuthenticationPermission instances.
    
    Overrides:
    
    newPermissionCollection in class Permission
    
    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.
    
    Specified by:
    
    equals in class Permission
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for this object.
    
    Specified by:
    
    hashCode in class Permission

Class AuthenticationPermission

Constructor Summary

Method Summary

Methods inherited from class java.security.Permission

Methods inherited from class java.lang.Object

Constructor Detail

AuthenticationPermission

AuthenticationPermission

Method Detail

implies

getActions

newPermissionCollection

equals

hashCode