net.jini.security

Class AuthenticationPermission

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

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