net.jini.security
Class AuthenticationPermission

java.lang.Object
  extended by java.security.Permission
      extended by 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:

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

Nested Class Summary
(package private) static class AuthenticationPermission.AuthenticationPermissionCollection
           
private static class AuthenticationPermission.Data
          Internal structure to work around the fact that you can't do computation on this prior to calling super() in a constructor.
 
Field Summary
private static int ACCEPT
          The accept action (includes the listen action).
private  String actions
          The actions.
private static int CONNECT
          The connect action.
private static int DELEGATE
          The delegate action (includes the connect action).
private static int LISTEN
          The listen action.
private  int mask
          The parsed actions as a bitmask.
private  String[] me
          The parsed elements of the local principals with wildcard principal names replaced by null, or null if there is a principal with both a wildcard class and a wildcard name.
private  String[] peer
          The parsed elements of the peer principals, or null if no peer principals were specified.
private static long serialVersionUID
           
 
Constructor Summary
private AuthenticationPermission(AuthenticationPermission.Data data, String actions)
          Creates an instance with the specified data and actions.
  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
private static String[] cons(Set s, StringBuffer b)
          Returns an array of alternating class and principal names for the specified set of principals, and appends all of those strings to the specified buffer, separated by spaces, with the principal names in quotes.
private static boolean covers(String[] sup, String[] sub)
          Returns true if every principal that matches sub also matches sup.
 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.
private  boolean implies0(AuthenticationPermission ap)
           
private  void init()
          Parses the target name and actions, and initializes the transient fields.
 PermissionCollection newPermissionCollection()
          Returns an empty PermissionCollection for storing AuthenticationPermission instances.
private  void parseActions()
          Parses the actions field and initializes the transient mask field.
private static AuthenticationPermission.Data parseName(Set me, Set peer)
          Constructs the target name and transient field data for the specified principal sets.
private  void parseName(StringTokenizer st, boolean peer)
          Parses what's left of the target name in the specified tokenizer, and initializes the transient fields.
private  void readObject(ObjectInputStream s)
          Verifies the syntax of the target name and recreates any transient state.
private static boolean same(String[] s1, String[] s2)
          Returns true if both arrays are null, or both arrays are the same length and contain the same pairs (ignoring order).
 
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
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

LISTEN

private static final int LISTEN
The listen action.

See Also:
Constant Field Values

CONNECT

private static final int CONNECT
The connect action.

See Also:
Constant Field Values

ACCEPT

private static final int ACCEPT
The accept action (includes the listen action).

See Also:
Constant Field Values

DELEGATE

private static final int DELEGATE
The delegate action (includes the connect action).

See Also:
Constant Field Values

actions

private String actions
The actions.


me

private transient String[] me
The parsed elements of the local principals with wildcard principal names replaced by null, or null if there is a principal with both a wildcard class and a wildcard name. If there is an element with a null principal name, no other element with the same class name will exist.


peer

private transient String[] peer
The parsed elements of the peer principals, or null if no peer principals were specified.


mask

private transient int mask
The parsed actions as a bitmask.

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

AuthenticationPermission

private AuthenticationPermission(AuthenticationPermission.Data data,
                                 String actions)
Creates an instance with the specified data and actions.

Method Detail

init

private void init()
Parses the target name and actions, and initializes the transient fields.


parseActions

private void parseActions()
Parses the actions field and initializes the transient mask field.


parseName

private void parseName(StringTokenizer st,
                       boolean peer)
Parses what's left of the target name in the specified tokenizer, and initializes the transient fields. Peer is false when parsing the local principals, true when parsing the peer principals.


cons

private static String[] cons(Set s,
                             StringBuffer b)
Returns an array of alternating class and principal names for the specified set of principals, and appends all of those strings to the specified buffer, separated by spaces, with the principal names in quotes.


parseName

private static AuthenticationPermission.Data parseName(Set me,
                                                       Set peer)
Constructs the target name and transient field data for the specified principal sets.


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

implies0

private boolean implies0(AuthenticationPermission ap)

covers

private static boolean covers(String[] sup,
                              String[] sub)
Returns true if every principal that matches sub also matches sup.


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

same

private static boolean same(String[] s1,
                            String[] s2)
Returns true if both arrays are null, or both arrays are the same length and contain the same pairs (ignoring order).


hashCode

public int hashCode()
Returns a hash code value for this object.

Specified by:
hashCode in class Permission

readObject

private void readObject(ObjectInputStream s)
                 throws IOException,
                        ClassNotFoundException
Verifies the syntax of the target name and recreates any transient state.

Throws:
InvalidObjectException - if the target name or actions string is null, or if the target name or actions string does not match the syntax specified in the comments at the beginning of this class
IOException
ClassNotFoundException


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.