6 Security Management

6.1 Managing Applets and Applications

Currently, all Java 2 SDK system code invokes SecurityManager methods to check the policy currently in effect and perform access control checks. There is typically a security manager (SecurityManager implementation) installed whenever an applet is running; the appletviewer and most browsers, including those from Netscape and Microsoft, install a security manager.

A security manager is not automatically installed when an application is running. To apply the same security policy to an application found on the local file system as to downloaded applets, either the user running the application must invoke the Java Virtual Machine with the new "-Djava.security.manager" command-line argument (which sets the value of the java.security.manager property), as in

    java -Djava.security.manager  SomeApp

or the application itself must call the setSecurityManager method in the java.lang.System class to install a security manager.

It is possible to specify on the command line a particular security manager to be utilized, by following "-Djava.security.manager" with an equals and the name of the class to be used as the security manager, as in

    java -Djava.security.manager=COM.abc.MySecMgr  SomeApp

If no security manager is specified, the built-in default security manager is utilized (unless the application installs a different security manager). All of the following are equivalent and result in usage of the default security manager:

    java -Djava.security.manager  SomeApp
    java -Djava.security.manager=""  SomeApp
    java -Djava.security.manager=default  SomeApp

Java 2 SDK includes a property named java.class.path. Classes that are stored on the local file system but should not be treated as base classes (e.g., classes built into the SDK) should be on this path. Classes on this path are loaded with a secure class loader and are thus subjected to the security policy being enforced.

There is also a "-Djava.security.policy" command-line argument whose usage determines what policy files are utilized. This command-line argument is described in detail in the "Default System and User Policy Files" section. Basically, if you don't include "-Djava.security.policy" on the command line, then the policy files specified in the security properties file will be used.

You can use a "-Djava.security.policy" command-line argument to specify an additional or a different policy file when invoking execution of an application. For example, if you type the following, where pURL is a URL specifying the location of a policy file, then the specified policy file will be loaded in addition to all the policy files specified in the security properties file:

    java -Djava.security.manager -Djava.security.policy=pURL SomeApp

If you instead type the following command, using a double equals, then just the specified policy file will be used; all others will be ignored:

java -Djava.security.manager -Djava.security.policy==pURL SomeApp

6.2 SecurityManager versus AccessController

The new access control mechanism is fully backward compatible. For example, all check methods in SecurityManager are still supported, although most of their implementations are changed to call the new SecurityManager checkPermission method, whose default implementation calls the AccessController checkPermission method. Note that certain internal security checks may stay in the SecurityManager class, unless it can be parameterized.

We have not at this time revised any system code to call AccessController instead of calling SecurityManager (and checking for the existence of a classloader), because of the potential of existing third-party applications that subclass the SecurityManager and customize the check methods. In fact, we added a new method SecurityManager.checkPermission that by default simply invokes AccessController.checkPermission.

To understand the relationship between SecurityManager and AccessController, it is sufficient to note that SecurityManager represents the concept of a central point of access control, while AccessController implements a particular access control algorithm, with special features such as the doPrivileged method. By keeping SecurityManager up to date, we maintain backward compatibility (e.g., for those applications that have written their own security manager classes based on earlier versions of the JDK) and flexibility (e.g., for someone wanting to customize the security model to implement mandatory access control or multilevel security). By providing AccessController, we build in the algorithm that we believe is the most restrictive and that relieves the typical programmer from the burden of having to write extensive security code in most scenarios.

We encourage the use of AccessController in application code, while customization of a security manager (via subclassing) should be the last resort and should be done with extreme care. Moreover, a customized security manager, such as one that always checks the time of the day before invoking standard security checks, could and should utilize the algorithm provided by AccessController whenever appropriate.

6.3 Auxiliary Tools

This section briefly describes the usage of three tools that assist in the deployment of the new security features. These tools may be packaged together in the future.

More extensive documentation for the tools can be found in the

/docs/tooldocs/solaris

and

/docs/tooldocs/win32

subdirectories of the SDK release directory (where the directory separators are actually "\" on Windows systems).

For example, if the Java 2 SDK is installed in a directory named "/j2sdk1.2" on a Solaris system, then the keytool documentation for Solaris and Windows users, respectively, can be found in

/j2sdk1.2/docs/tooldocs/solaris/keytool.html
/j2sdk1.2/docs/tooldocs/win32/keytool.html

If the Java 2 SDK is installed in a directory named "C:\j2sdk1.2" on a Windows system, then the keytool documentation for Solaris and Windows users, respectively, can be found in

C:\j2sdk1.2\docs\tooldocs\solaris\keytool.html
C:\j2sdk1.2\docs\tooldocs\win32\keytool.html

6.3.1 The Key and Certificate Management Tool

keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. The authentication information includes both a sequence (chain) of X.509 certificates, and an associated private key, which can be referenced by a so-called "alias". This tool also manages certificates (that are "trusted" by the user), which are stored in the same database as the authentication information, and can be referenced by an "alias".

keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password.

The chains of X.509 certificates are provided by organizations called Certification Authorities, or CAs. Identities (including CAs) use their private keys to authenticate their association with objects (such as with channels which are secured using SSL), with archives of code they signed, or (for CAs) with X.509 certificates they have issued. As a bootstrapping tool, certificates generated using the -genkey command may be used until a Certification Authority returns a certificate chain.

The private keys in this database are always stored in encrypted form, to make it difficult to disclose these private keys inappropriately. A password is required to access or modify the database. These private keys are encrypted using the "password", which should be several words long. If the password is lost, those authentication keys cannot be recovered.

In fact, each private key in the keystore can be protected using its own individual password, which may or may not be the same as the password that protects the keystore's overall integrity.

This tool is (currently) intended to be used from the command line, where one simply types "keytool" as a shell prompt. keytool is a script that executes the appropriate Java classes and is built together with the SDK.

The command line options for each command may be provided in any order. Typing an incorrect option or typing "keytool -help" will cause the tool's usage to be summarized on the output device (such as a shell window), as given below.

% keytool -help
KeyTool usage:
 
-certreq     [-v] [-alias <alias>] [-sigalg <sigalg>]
             [-file <certreq_file>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-delete      [-v] -alias <alias>
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-export      [-v] [rfc] [-alias <alias>] [-file <cert_file>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-genkey      [-v] [-alias <alias>] [-keyalg <keyalg>]
             [-keysize <keysize>] [-sigalg <sigalg>]
             [-dname <distinguished_name>] [-validity <valDays>]
             [-keypass <keypass>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-help
  
-identitydb  [-v] [-file <idb_file>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]

-import      [-v] [-noprompt] [-alias <alias>]
             [-file <cert_file>] [-keypass <keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-keyclone    [-v] [-alias <alias>] -dest <dest_alias>
             [-keypass <keypass>] [-new <new_keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-keypasswd   [-v] [-alias <alias>]
             [-keypass <old_keypass>] [-new <new_keypass>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-list        [-v | -rfc] [-alias <alias>]
             [-keystore <keystore>] [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-printcert   [-v] [-file <cert_file>]
 
-selfcert    [-v] [-alias <alias>] [-sigalg <sigalg>]
             [-dname <distinguished_name>] [-validity <valDays>]
             [-keypass <keypass>] [-keystore <keystore>]
             [-storepass <storepass>]
             [-storetype <i>storetype</i>]
 
-storepasswd  [-v] [-new <new_storepass>]
             [-keystore <keystore>] [-storepass <storepass>]
              [-storetype <i>storetype</i>]

6.3.2 Policy Tool

The Policy Tool is a graphical user interface (illustrated below with a screen shot) that assists a user (such as a system administrator) in specifying, generating, editing, exporting, or importing a security policy. The tool is invoked from the command line as policytool. This again is a script built with the SDK that invokes the appropriate (non-public) implementation classes.

See the Policy Tool documentation for usage information and examples with up-to-date screen shots. The documentation can be found in the policytool.html file in the

/docs/tooldocs/solaris/

or

/docs/tooldocs/win32/

directory in the directory in which the SDK was installed (where the file separators are actually backslashes on Windows systems).

6.3.3 The JAR Signing and Verification Tool

The jarsigner tool can be used to digitally sign Java archives (JAR files), and to verify such signatures. This tool, like the Policy Tool, depends on the keystore that is managed by the keytool. Its usage is quickly summarized below.

% jarsigner
Usage: jarsigner [options] jar-file alias
       jarsigner -verify [options] jar-file
  [-keystore <url>]         keystore file location
  [-storepass <password>]   password for keystore integrity
  [-keypass <password>]     password for private key (if different)
  [-sigfile <file>]         name of .SF/.DSA file
  [-signedjar <file>]       name of signed JAR file
  [-verify]                 verify a signed JAR file
  [-verbose]                verbose output when signing/verifying
  [-certs]          display certificates when verbose and verifying
  [-internalsf]             include .SF file inside signature block
  [-sectionsonly]           don't compute hash of entire manifest

Again, this tool is a script built with the SDK. Note that it is expected that this tool and the existing jar tool script may be merged in the near future to form a single command-line primitive to create JARs, either signed or unsigned.