All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class sun.server.realm.Realm

java.lang.Object
   |
   +----sun.server.realm.Realm

public class Realm
extends Object
A realm is an administrative entity around which basic operational security policies revolve. Realms are normally used to organize the objects used in defining access control policies. For example, the resources on a particular web server are all expressed in terms of the users, groups, and access control lists provided by a realm.

Other uses of realms include organizing entities used for defining trust policies. For example, a group can be defined to say what X.509 certificate authorities are trusted to authenticate clients, or whose signatures on code modules implies granting special privileges.


A Realm object provides access to the following data, and supports modifying (and extending) it according to policies defined by the realm administrator and by each particular kind of realm:


A realm is an abstract class. Simple implementations of realms will just provide the user authentication (and home directory) component. Other implementations may desire more control over the data formats used to represent groups and ACLs. For example, they may use a database to support particular scaling or performance goals; or may use a networked administrative database such as NIS in order to meet goals of robustness in the face of network failures.

Realms are used inside servers, and the code which uses the realm object is required to maintain the security policy which applies to that realm (as expressed by its ACL). Unless it is known otherwise, a realm should not be concurrently manipulated by two different processes.

When objects associated with a realm are modified, they will automatically store their persistent state.

NOTE: programming interfaces used to repair corrupt realm data structures are currently not defined.

See Also:
Principal, Acl, Group

Variable Index

 o authSharedPassword
Identifies an authentication scheme where the server and client share knowledge of the same secret passphrase (or password).
 o authUNIX
Identifies the classic UNIX (tm) authentication scheme, where the server holds the result of a salted encryption of the user's secret passphrase.
 o authX509DSS
Identifies an authentication scheme where the server holds a DSS/DSA certificate with the user's public key, signed by some certificate authority which it trusts.
 o authX509RSA
Identifies an authentication scheme where the server holds an RSA certificate with the user's public key, signed by some certificate authority which it trusts.

Constructor Index

 o Realm(File)
Constructor for use by subclasses.

Method Index

 o deleteAcl(String)
Deletes the named ACL.
 o deleteGroup(String)
Deletes a group, if it is empty and is a member of no group or ACL
 o deleteUser(String)
Deletes the identified user, if it is supported by the underlying realm implementation.
 o get(String)
Returns the realm identified by the name which is passed as a parameter.
 o getAcl()
Returns the access control list controlling which users within this realm have administrative privileges on this realm itself.
 o getAcl(String)
Returns a particular named Access Control List (ACL) which is associated with this realm.
 o getAclNames()
Returns names of all the Acls in this realm.
 o getAuthSchemes()
This identifies the authentication schemes supported by a given realm.
 o getDefaultAclOwner()
Returns the Principal which, by default, owns ACLs within this realm.
 o getGroup(String)
Returns the group with the name which is given as a parameter.
 o getGroupNames()
Returns names of all the groups in this particular realm.
 o getName()
Returns the name of this realm, as presented to users
 o getRealmDir()
Normally identifies the directory where the realm stores realm-specific information, such as group membership lists, ACLs, and user authentication information.
 o getUser(String)
Returns the information recorded about a particular named user.
 o getUserNames()
Returns names of all the users in this particular realm.
 o isAuthSupported(String)
Returns true iff the realm supports the authentication scheme requested.
 o list()
Returns the names of accessible realms.
 o logError(Exception, String)
Logs an error in realm operation in a place where a realm administrator can find the error message.
 o logError(String)
 o makeAcl(String, Principal)
Returns a newly created empty ACL.
 o makeGroup(String)
Returns a newly created empty group, with the name which is given as a parameter.
 o setDefaultPolicies()
Establishes default realm policies, such as existence of an "adminGroup" principal which owns the realm's "adminAcl".
 o setName(String)
Assigns the name of this realm, and stores it in the cache of realms.
 o toString()
Identifies this realm
 o verifyNotInPolicies(Principal)
Utility for use when checking if it's alright to delete a user or group: raises an exception if the principal is in a group or ACL.

Variables

 o authSharedPassword
  public final static String authSharedPassword
Identifies an authentication scheme where the server and client share knowledge of the same secret passphrase (or password). Realms which support this scheme need to to be extremely careful how they protect these secrets, since the risk of disclosing the secrets is both to the realm and to the users. (User passphrases are often the same in multiple realms.)

 o authX509RSA
  public final static String authX509RSA
Identifies an authentication scheme where the server holds an RSA certificate with the user's public key, signed by some certificate authority which it trusts. This information does not need to be kept secret.

 o authX509DSS
  public final static String authX509DSS
Identifies an authentication scheme where the server holds a DSS/DSA certificate with the user's public key, signed by some certificate authority which it trusts. This information does not need to be kept secret.

 o authUNIX
  public final static String authUNIX
Identifies the classic UNIX (tm) authentication scheme, where the server holds the result of a salted encryption of the user's secret passphrase. Realms which use this scheme can worry a bit less about protecting their authentication data than ones which use the shared password scheme, since well chosen passwords are resistant to common attacks against their encrypted form.

Constructors

 o Realm
  protected Realm(File realmDir)
Constructor for use by subclasses.

Parameters:
realmDir - directory where the realm's state is stored.

Methods

 o getAcl
  public Acl getAcl() throws BadRealmException
Returns the access control list controlling which users within this realm have administrative privileges on this realm itself. The following initial behaviours are predefined:
Members of admingroup Are owners of the realm's ACL
The ACL named adminAcl Controls administrative privileges

Returns:
the ACL controlling administrative privileges
Throws: BadRealmException
if realm data structures are bad
 o getAuthSchemes
  public abstract String[] getAuthSchemes()
This identifies the authentication schemes supported by a given realm. Realms sometimes support multiple schemes, despite the administrative and security problems inherent in such approaches. Attackers may well be able to exploit one scheme but not others; it is important to match the strength of the authentication scheme against the risks of the channel that scheme is used with.

A number of standard scheme identifiers are defined; constants for these identifiers are public auth* symbols in this class.

Returns:
the authentication schemes supported by the realm.
 o isAuthSupported
  public abstract boolean isAuthSupported(String scheme)
Returns true iff the realm supports the authentication scheme requested.

Parameters:
scheme - the authentication scheme in question
Returns:
true iff the scheme is supported
 o getAclNames
  public Enumeration getAclNames() throws BadRealmException
Returns names of all the Acls in this realm.

Throws: BadRealmException
if realm data structures are bad
 o getAcl
  public Acl getAcl(String name) throws NoSuchAclException, BadRealmException
Returns a particular named Access Control List (ACL) which is associated with this realm.

Parameters:
name - the name of the ACL which is requested
Throws: NoSuchAclException
if the ACL doesn't exist
Throws: BadRealmException
if realm data structures are bad
 o makeAcl
  public Acl makeAcl(String name,
                     Principal owner) throws BadRealmException
Returns a newly created empty ACL. This ACL has a single owner.

Parameters:
name - name of the group whose creation is desired
owner - initial owner of the ACL, which must be a principal returned via getUser.
Returns:
the newly created empty acl
Throws: BadRealmException
if realm data structures are bad
See Also:
getUser
 o deleteAcl
  public void deleteAcl(String name) throws NoSuchAclException, BadRealmException
Deletes the named ACL. It is the caller's responsibility to make sure that this ACL is not used for anything.

Parameters:
name - the name of the ACL to be deleted
Throws: NoSuchAclException
if the ACL doesn't exist
Throws: BadRealmException
if realm data structures are bad
 o getUserNames
  public abstract Enumeration getUserNames() throws BadRealmException
Returns names of all the users in this particular realm.

Returns:
enumeration of user names (strings)
Throws: BadRealmException
if realm data structures are bad
 o getUser
  public abstract User getUser(String name) throws NoSuchUserException, BadRealmException
Returns the information recorded about a particular named user.

Parameters:
name - name of the user whose information is desired
Returns:
the user object
Throws: NoSuchUserException
if the user doesn't exist
Throws: BadRealmException
if realm data structures are bad
 o deleteUser
  public abstract void deleteUser(String name) throws NoSuchUserException, BadRealmException, InUseException
Deletes the identified user, if it is supported by the underlying realm implementation.

Parameters:
name - name of the user to be deleted
Throws: NoSuchUserException
if the user doesn't exist
Throws: BadRealmException
if realm data structures are bad
Throws: InUseException
if the user object could not be deleted because it is involved in some aspect of realm security policy
 o getDefaultAclOwner
  public abstract Principal getDefaultAclOwner() throws BadRealmException
Returns the Principal which, by default, owns ACLs within this realm. This is typically a group. This is a messy spot in the API, since ACL owners can't be examined and because there's an assumption in most places that there is really only one owner, but the core interface expects there to be multiple owners.

Returns:
the principal of this realm's default ACL owner
Throws: BadRealmException
in case of error
 o verifyNotInPolicies
  protected void verifyNotInPolicies(Principal p) throws BadRealmException, InUseException
Utility for use when checking if it's alright to delete a user or group: raises an exception if the principal is in a group or ACL.

Deleting the principal would make the security policy expressed in an ACL invalid. Later creation of a user with the same name could cause problem since the user might be in groups they'd not normally be permitted to join.

Parameters:
p - user, or group, being checked
Throws: BadRealmException
if realm data structures are bad
Throws: InUseException
if the principal is in use.
 o getGroupNames
  public Enumeration getGroupNames() throws BadRealmException
Returns names of all the groups in this particular realm.

Returns:
enumeration of group names (strings)
Throws: BadRealmException
if realm data structures are bad
 o getGroup
  public Group getGroup(String name) throws BadRealmException, NoSuchGroupException
Returns the group with the name which is given as a parameter.

Parameters:
name - name of the group whose information is desired
Returns:
the group
Throws: NoSuchGroupException
if the Group doesn't exist
Throws: BadRealmException
if realm data structures are bad
 o makeGroup
  public Group makeGroup(String name) throws BadRealmException, InUseException
Returns a newly created empty group, with the name which is given as a parameter.

Parameters:
name - name of the group whose creation is desired
Returns:
the newly created empty group
Throws: BadRealmException
if realm data structures are bad
Throws: InUseException
if the group name is already in use
 o deleteGroup
  public boolean deleteGroup(String name) throws BadRealmException, NoSuchGroupException, InUseException
Deletes a group, if it is empty and is a member of no group or ACL

Parameters:
name - name of the group
Returns:
true iff the group is successfully deleted; false if it could not be deleted because the group is used in some aspect of realm security policy
Throws: NoSuchGroupException
if the Group doesn't exist
Throws: BadRealmException
if realm data structures are bad
Throws: InUseException
if the group name is in use as part of the realm's security policies
 o get
  public static Realm get(String name) throws NoSuchRealmException, BadRealmException
Returns the realm identified by the name which is passed as a parameter. This function knows about all the realms which exist; it is not possible to store (or create) one which is not accessible through this routine.

Parameters:
name - identifies the realm
Returns:
the requested realm
Throws: NoSuchRealmException
if the realm is invalid
Throws: BadRealmException
if realm data structures are bad
 o list
  public static String[] list()
Returns the names of accessible realms.

Returns:
set of realm names
 o getName
  public final String getName()
Returns the name of this realm, as presented to users

 o setName
  protected final void setName(String name)
Assigns the name of this realm, and stores it in the cache of realms. Used when initializing a newly created in-memory realm object; if the realm already has a name, there is no effect.

Parameters:
name - name to be assigned to this realm.
 o toString
  public String toString()
Identifies this realm

Overrides:
toString in class Object
 o setDefaultPolicies
  protected void setDefaultPolicies() throws BadRealmException
Establishes default realm policies, such as existence of an "adminGroup" principal which owns the realm's "adminAcl". This is intended to be used by subclasses as part of creating new realms.

Throws: BadRealmException
if realm data structures are bad
 o getRealmDir
  public File getRealmDir()
Normally identifies the directory where the realm stores realm-specific information, such as group membership lists, ACLs, and user authentication information.

 o logError
  public static void logError(Exception e,
                              String info)
Logs an error in realm operation in a place where a realm administrator can find the error message. Most such errors are worth looking into, since they can reflect major system security problems.

 o logError
  public static void logError(String info)

All Packages  Class Hierarchy  This Package  Previous  Next  Index