Class RegistryPermission

public class RegistryPermission implements IPermission, 
            IEncodablePermission
{
  // Fields
  public static final int CREATE;
  public static final int DELETE;
  public static final int OPEN;
  public static final int READ;
  public static final int WRITE;

  // Constructors
  public RegistryPermission ();

  // Methods
  public void check(Object param);
  public IPermission combine(IPermission source2);
  public int compareSet (Object target);
  public IPermission copy();
  public boolean decode(String tag, InputStream data);
  public boolean encode(String tag, OutputStream out);
  public void excludeRule(int access, String pattern);
  public WildcardExpression getExcludedRules(int accessType);
  public WildcardExpression getIncludedRules(int accessType);
  public void includeRule(int access, String pattern);
  public String mapFormat(String format);
  public void reset ();
  public String[] supportedFormats();
  public String toString();
}

This class represents a permission that controls the ability to access the registry. The StandardSecurityManager checks for this permission type when performing the checkRegistry operation.

The registry permission distinguishes between five different types of access to registry keys or values, shown in the following list.

OPEN

Keys can be opened (does not apply to values).

READ

Information about a key or value can be read.

WRITE

A key or value can be modified.

DELETE

A key or value can be deleted.

CREATE

A key or value can be created.

The specific key or value allowed for each operation is defined by a pair of include/exclude patterns. Keys are specified by a trailing backslash (\). Absolute registry paths must start with a root key specifier, which is one of the following strings:

"HKCR"

HKEY_CLASSES_ROOT

"HKLM"

HKEY_LOCAL_MACHINE

"HKCU"

HKEY_CURRENT_USER

"HKUR"

HKEY_USERS

For example, "HKCU\\dog\\" specifies a key named "dog" under HKEY_CURRENT_USER. But "HKCU\\dog\\Fido" specifies the value named "Fido" within the key HKEY_CURRENT_USER\dog.

Note In source code, you must type two backslashes to represent the single backslash necessary for specifying a key.

Also see com.ms.security.permissions.RegistryRequest

Constructors

RegistryPermission

public RegistryPermission ();

Creates a new RegistryPermission instance. The new instance will not allow any access to any portion of the registry. Access to specific portions of the registry must be explicitly enabled.

Methods

check

public void check(Object param);

Determines whether the specified registry operation is allowed by the permission object.

Return Value:

No return value.

Parameter	Description
param	The security request parameter. It must be an instance of the RegistryRequest class.

Exceptions:

SecurityException if this permission does not allow the specified operation.

combine

public IPermission combine(IPermission source2);

Creates and returns a new RegistryPermission object that is a combination of the current permission object and the specified permission object. The new object allows access to exactly those resources allowed by either one of the permission objects that it was constructed from.

Return Value:

Returns the resulting RegistryPermission object.

Parameter	Description
source2	The other RegistryPermission object to combine with.

Exceptions:

IllegalArgumentException if the specified object to combine with is not an instance of RegistryPermission.

compareSet

public int compareSet (Object target);

Compares the RegistryPermission instance with a specified permission object.

Return Value:

Returns one of the following constants:

• DISJOINT
• EMPTY
• OVERLAP
• EQUAL
• SUBSET
• SUPERSET
• EMPTY_SUBSET
• EMPTY_SUPERSET

Parameter	Description
target	The permission object that the RegistryPermission instance is compared with.

copy

public IPermission copy();

Retrieves a copy of the RegistryPermission object.

Return Value:

Returns the copy of the RegistryPermission object.

decode

public boolean decode(String tag, InputStream data);

Decodes the contents of the specified data stream into this permission object. The tag parameter specifies the type of data in the stream.

Return Value:

Returns true if the decoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
data	The raw data to construct the object from. The type of data is specified by the tag parameter.

encode

public boolean encode(String tag, OutputStream out);

Encodes the contents of this permission object and sends the encoded data to the specified stream. The tag parameter specifies the type of encoding that should be used.

Return Value:

Returns true if the encoding operation succeeded; otherwise, returns false.

Parameter	Description
tag	The encoding type identifier.
out	The output stream to send the encoded data to.

excludeRule

public void excludeRule(int access, String pattern);

Adds a rule that explicitly denies the specified access type to the registry keys or values specified by the pattern string. This method is used to modify a previously allowed rule to a more restricted type of access.

Return Value:

No return value.

Parameter	Description
access	The access types being added. Must be one of the following types: OPEN, READ, WRITE, DELETE, or CREATE, or any combination of these types used with the OR operator.
pattern	The registry keys/values to which the specified access type is being added. This parameter must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.

getExcludedRules

public WildcardExpression getExcludedRules(int accessType);

Returns the wildcard expression representing all the keys or values that are explicitly denied for the specified access type.

Return Value:

Returns the wildcard expression representing all the keys/values that are explicitly denied for the specified access type.

Parameter	Description
accessType	This value must be one of the following: OPEN, READ, WRITE, DELETE, or CREATE.

getIncludedRules

public WildcardExpression getIncludedRules(int accessType);

Retrieves the wildcard expression that represents all the keys or values that are allowed for the specified access type.

Return Value:

Returns the wildcard expression representing all the keys or values that are allowed for the specified access type.

Parameter	Description
accessType	The type of access used to determine the wildcard expression. This value must be one of the following: OPEN, READ, WRITE, DELETE, or CREATE.

includeRule

public void includeRule(int access, String pattern);

Adds a rule that allows the specified access types to the registry keys/values specified by the pattern string.

Return Value:

No return value.

Parameter	Description
access	The access types being added. Must be one of the following types: OPEN, READ, WRITE, DELETE, or CREATE, or any combination of these types used with the OR operator (|).
pattern	The registry keys or values to which the specified access type is being added. This parameter must be of the form accepted by a WildcardExpression with the ESCAPED flag enabled.

mapFormat

public String mapFormat(String format);

Retrieves a permission-specific tag, given an encoding format. The tag is then used with the encode and decode methods to specify an encoding type.

Return Value:

Returns the permission-specific tag that corresponds to the specified format.

Parameter	Description
format	The encoding format to retrieve the tag for.

reset

public void reset ();

Resets the permission state to empty. This is a state in which the object allows no registry access.

Return Value:

No return value.

supportedFormats

public String[] supportedFormats();

Retrieves the encoding formats that the permission type supports.

Return Value:

Returns an array of the supported format identifiers.

toString

public String toString();

Retrieves a textual representation of the permission object.

Return Value:

Returns the string representation of the permission object.

Fields

CREATE

An access type that indicates that a key or value can be created.

DELETE

An access type that indicates that a key or value can be deleted.

OPEN

An access type that indicates that keys can be opened.

READ

An access type that indicates that information about a key or value can be read.

WRITE

An access type that indicates that a key or value can be modified.