Interface IEncodablePermission

public interface IEncodablePermission
{
  // Methods
  boolean decode(String tag, InputStream data);
  boolean encode(String tag, OutputStream data);
  String mapFormat(String format);
  String[] supportedFormats();
}

This interface provides methods that allow permissions to represent their internal state in any desired format. For example, a permission can encode itself into an arbitrary binary format or a textual format.

The contract with the caller of the IEncodablePermission interface can be described in the following way.

• The caller can obtain a tag for a specified format, and then call the encode and decode methods with that tag.
• If a caller chooses to persist the encoding, the caller must store the tag along with the encoding.
• To decode the persisted encoding, the caller must get the tag from its storage location, and then pass it (along with the encoding) to the decode method.
• The caller can request the tag for a specified format using the mapFormat method.
• If the specified format is not available, the caller can obtain the default tag by passing null to the mapFormat method.
• If the caller does not recognize the format, the caller must be able to store the default encoding in an opaque manner (as binary data of an arbitrary length).
• An instance of any class that implements the IEncodablePermission interface is guaranteed that its default encoding can be stored.

The tag is defined by a class that implements the IEncodablePermission interface and is meaningful only to that class. It is not meaningful to any other IEncodablePermission class. The tag allows the object to do version control and to handle multiple types of encodings. The tag is an arbitrary string that the permission class decides on. It is likely that the string will contain some type of version information; its form is determined by the permission class.

This interface is useful for developers who write Java packages that are digitally signed. When the package is installed on a client's computer, the user gets a dialog box asking for permission to access certain resources. The permission needs to be attached to the digital signature so that the security system can determine what permissions are needed. The developer should create a permission class that implements IEncodablePermission. The signcode tool takes the name of the permission class, creates an instance of it, and then calls the encode method of the permission class to cause the instance to encode itself. This encoding is stored inside the digital signature, which is then attached to a package.

The security system within the Microsoft Win32 VM for Java gets the encoding from the signature and creates an instance of the permission class. It then calls the class's decode method, passing in the tag that was used at the time of signing (the tag is part of the signature's encoding). Because signatures are static, and because the permission class can be located in any package, the current implementation of the permission class can determine what version of the IEncodablePermission class was encoded with the tag.

For example, suppose you created a package of classes that manipulate SQL databases. This package might contain applets that access portions of the database, based on a table name. You could create a database permission class called DBPermission that stores the name of an SQL table. Then you would sign each applet with the DBPermission, asking for a specific table. The DBPermission class would then be distributed with your package, and the applets are sent to Web sites that are accessed by users.

You might, at some point, enhance your package by adding the ability to restrict access to particular rows and columns of a database. You would then update your permission class to keep track of the rows and columns that can be accessed. New applets would be signed with the new permission. However, the old applets might still be in use on the Internet, signed with the old permission. The tag provides a way to identify the version used to encode a permission class.

If permissions that implement the IEncodablePermission interface are inserted into a PermissionDataSet object so that they can be used in digital signatures, the signing tool will find out whether the permissions support ASN1 format. If ASN1 is not supported, the class's default encoding will be used.

Methods

decode

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

boolean encode(String tag, OutputStream data);

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.
data	The output stream to send the encoded data to.

mapFormat

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.

supportedFormats

String[] supportedFormats();

Retrieves the encoding formats that the permission type supports.

Return Value:

Returns an array of the supported format identifiers.