Implementing Your Own Permission

A Sample Policy File

Below is a complete policy file for a user wanting to run TerrysGame.

The policy file syntax is not described here; if you're interested, see Default Policy Implementation and Policy File Syntax on the public java.sun.com web site.

You don't need to know the syntax; you can always use the Policy Tool to create policy files, as shown in Quick Tour of Controlling Applets , Quick Tour of Controlling Applications , and Signing Code and Granting It Permissions [Tools] lessons.

Here's the sample policy file, followed by a description of the individual entries:

keystore "kim.keystore";

grant SignedBy "chris" {
  // the high score class needs permission to read user.home to find
  // the location of the highscore file

  permission java.util.PropertyPermission "user.home", "read";

  // it needs permission to read and write the high score file itself

  permission java.io.FilePermission "${user.home}${/}.highscore", "read,write";

  // it needs to get granted its own permission, so it can call checkPermission
  // to see if its caller has permission. Only grant it the permission
  // if the permission itself was signed by HighScore...

  permission HighScorePermission "*", signedBy "chris";
};


// grant code signed by "FooGame" the HighScorePermission, if the
// HighScorePermission was signed by "chris".

grant SignedBy "terry" {
 permission HighScorePermission "TerrysGame", signedBy "chris";
};

To ensure the authenticity of the HighScore code, we require that it be signed using a private key belonging to the HighScore creator, say Chris. Chris supplies (in a certificate) anyone that wants it the public key corresponding to the private key that was used to generate the signature. Each user can import the certificate into his or her keystore, and the runtime system will use it to verify the signature when the signed HighScore code attempts to perform a secured action that is allowed by the policy file.

Similarly, to ensure the authenticity of each game, we require that its class file be signed using a private key belonging to the game creator, say Terry. Terry supplies (in a certificate) anyone that wants it the public key corresponding to the private key that was used to generate the signature. Each user can import the certificate into his or her keystore, and the runtime system will use it to verify the signature.

The Keystore Entry

A keystore is a repository of keys and certificates. The keytool utility is used to create and administer keystores. The keystore specified in a policy file is used to look up the public keys of the signers specified in the other entries of the file.

For this lesson, pretend you are a user named Kim and your keystore is named kim.keystore. Then your policy file needs the following line:

    keystore "kim.keystore";

The TerrysGame Entry

The policy file needs an entry for each game, granting code signed by a key from that game's creator a HighScorePermission whose name is the game name. Suppose Kim has imported Terry's public key certificate into kim.keystore and assigned it the alias "terry". Then the policy file needs the following entry:

grant SignedBy "terry" {
 permission HighScorePermission "TerrysGame", signedBy "chris";
};

The signedBy "chris" part of the permission entry specifies the alias to the keystore entry whose public key corresponds to the private key that must have been used to sign the specified permission class, HighScorePermission. That is, the HighScorePermission with name "TerrysGame" will only be granted to code signed by "terry" if the HighScorePermission class was signed by Chris's private key.

Note: If you were using the Policy Tool to create this policy file entry, the "Permissions" dialog box would look like the following:

The HighScore Entry

The HighScore class (signed by its owner Chris) needs three permissions, specified below. First note that the public key corresponding to the private key used to sign the class is herein assumed to reside in a certificate in Kim's keystore entry aliased by "chris".

1. Permission to read the "user.home" property value.

This permission is needed so the HighScore constructor can locate the current user's .highscore file, which is in the user's home directory.

Here's the required permission:

    permission java.util.PropertyPermission "user.home", "read";

2. Permission to read and write to the high score file itself.

This permission is needed so the getHighScore and setHighScore methods can access the user's high score file to get or set, respectively, the current high score for the current game.

Here's the required permission:

    permission java.io.FilePermission "${user.home}${/}.highscore", "read,write";

3. All HighScorePermissions (i.e, HighScorePermissions of any name).

This permission is needed so that the checks to ensure the calling game has been granted a HighScorePermission whose name is the game name will work. That is, the HighScore class must also be granted the permission, since a permission check requires that all code currently on the stack have the specified permission.

Here's the required permission:

    permission HighScorePermission "*", signedBy "chris";

Implementing Your Own Permission