Worklets Documentation: Security

back to Worklets documentation


The Worklet security system provides methods for securing Worklet transmission. The vulnerable objects are the RMI (Remote Method Invocation) transport layer, the WVM (Worklet Virtual Machine) transport layer and the class loaders. Other objects that have or provide methods for security measures are HostnameVerifier and WorkletJunctions.

The RMI Transport layer involves an RMI registry, associated RMI servers and class loaders. Only one registry can be created on a specific host:port to which many RMI servers can be bound. A secure registry authenticates all registry calls such as server lookups, binds, and unbinds. A secure RMI server uses custom secure sockets to authenticate and encrypt all communication. In the instance of a secure server, the default RMI class loader is set to our own implementation that uses a class loader with secure sockets. Both plain and secure RMI servers can be bound to plain registries but only secure RMI servers can be bound to secure registries. Communication between RMI servers can only proceed plain-plain or secure-secure. Depending on the security level (described in the Usage section) the RMI server could have either only plain, only secure, or both class loaders available to load classes.

The WVM transport layer includes server sockets and class loaders. Depending on the level of security the transport layer can be created with plain, secure, or both types of server sockets and associated class loaders.

A HostnameVerifier is also implemented and is used on the remote (receiving) end. This object is used by the remote host if the hostname of the sending WVM is not recognized from the CA certificate file. The specification of the hosts that are allowed and denied is described in the usage section.

There are situations where the user of the WorkletJunctions could be uncertain of the security specifications at a certain WVM. The user can now specify parameters that allow the users to specify which methods of transport (plain RMI, secure RMI, plain socket, secure socket) the WorkletJunction should try and in what order. The RMI related methods specify what type of communication to try when looking up the recipient RMI server, not the actual RMI server. The socket related features specify the type of socket to try connecting on. The ability to specify transport methods contributes to the robustness of WorkletJunction communication.


Note that all previous functionality is retained. This section documents the features pertinent to Worklet Security. I make a delineation between the remote and local hosts. The remote host represents the intended recipient of the Worklet while the local host is the entity that is sending the Worklet.

Remote Host

To create a plain host you need not specify any parameters, like this:

java psl.worklets.WVM

The name and port of the RMI server will default to WVM_Host and 9100. If a remote host is created in this manner communication will not be authenticated nor encrypted. You can specify the RMI server name and port by using the switches -name and -port. See java psl.worklets.WVM -help for option details.

To create secure hosts you must specify at least the keys file, password, and WVM properties file (WVM file). Because the WVM file must contain the keysfile and password it is usually sufficient to simply specify the WVM file. The keys file is the file containing the public/private keys of the host and the password is the passphrase specified in the creation of the keysfile. For more information on how to create a keysfile see the FAQ below. The WVM file holds the security specifications. These security specifications can be specified by setting environment variables with the -D java switch or non the command line. The parameter loading precedence is:

The WVM file contains property=value pairs separated by white space. The important parameters in the WVM file are the keysfile and password as these are used by the Worklet system at different times. It is very important that the security of this file is set at the operating systems level, meaning that the permissions on this file should be set accordingly. For example, for maximum security I would set the permission to user read-only. This can be done under Unix with the following:

chmod a-rwx wvm_properties
chmod u+r wvm_properties

Included with the distribution should be an example WVM file named ``wvm_properties''. It should look like this:

# WVM host related parameters
WVM_RMI_PORT=9100 # port that the rmi registry will be created on
WVM_RMI_NAME=target # name that the RMI server will be bound to

# Security related parameters
WVM_KEYSFILE=testkeys # file holding the public/private keys
WVM_PASSWORD=passphrase # password into the keysfile.
WVM_SSLCONTEXT=TLS # SSL context instance to use
WVM_KEYMANAGER=SunX509 # key manager implementation type
WVM_KEYSTORE=JKS # key store implementation type
WVM_RNG=SHA1PRNG # random number generator algorithm to use # location of the certified security certificates.
WVM_HOSTS_ALLOW=localhost, # allowed hosts
WVM_HOSTS_DENY= # denied hosts
WVM_FILE=wvm_properties # reference to this file

# security level of the WVM.
# 0: no security.
# 1: low security = plain RMI Registry, secure RMI server,
# plain and secure server sockets, and
# plain and secure class loaders.
# 2: medium security = same as 1 but with a secure RMI Registry
# 3: high security = secure RMI Registry, secure RMI server,
# secure server socket and secure class loaders.

Notice the last parameter of WVM_SECURITY_LEVEL. This parameter is what you would modify to tailor the security level according to the needs at a certain WVM. A security level of 1 is the most flexible as it creates a registry that will allow binding by both plain and secure RMI servers. Also created with a security level of 1 are plain and secure server sockets and class loaders. The only difference between security level 1 and 2 is that the registry is secure in the latter. A security level of 3 creates a WVM host that has a secure RMI server that must be bound to a secure registry, a secure server socket, and only secure class loaders. There is a plain server socket created, but that is used only for internal purposes for robust registry upkeep.

The WVM_HOSTS_ALLOW and WVM_HOSTS_DENY specify which hosts on the remote end are allowed and denied. If no hosts are specified in both settings, then all hosts will be allowed. These entries are the only parameters that are concatenated, meaning that if you specify these parameters in the system environment, the WVM file, and on the command line then all entries will be used.


Create a plain host with the RMI name target on port 9100.
java psl.worklets.WVM -name target

Create a host according to the parameters in the WVM file.
java psl.worklets.WVM -wvmfile wvm_properties

Create a host according to the parameters in the WVM file, but with the RMI name target and a security level of 2.
java -DWVM_FILE=wvm_properties psl.worklets.WVM -name target -S 2

Local Host

The sending of secure Worklets involves the creation of a local WVM host that bootstraps the Worklet into the WVM system. Creation of secure Worklets and WorkletJunctions is the same as described in the Worklet documentation except that you need to set the WVM_FILE system property to your WVM file (described above). This can either be done with the -D java switch or within the application with the System.setProperty method. Included in the distribution should be an example program ``''.

Here is the portion within the example program that sets the security parameters. Also shown is the creation of the WVM.

psl.worklets.OptionsParser op = new psl.worklets.OptionsParser();
wvm = new psl.worklets.WVM(new Object(), InetAddress.getLocalHost().getHostAddress(),
"SendSecure", op.port, op.keysfile, op.password,
op.ctx, op.kmf, op.ks, op.rng, op.securityLevel);

The WVM_FILE system property was set on the command line like this:
java -DWVM_FILE=wvm_properties SendSecure localhost target 9101 Apps.Face 1 0 mysend

You can also manage the WorkletJunction transport methods by setting the transportMethods to a combination of plainRMI, secureRMI, plainSocket, and secureSocket. The plainRMI and secureRMI keywords specify the type of registry used by that server. The type of server cannot be specified because the parameters for which type of socket to use is set at creation time. The plainSocket and secureSocket keywords specify which type of socket to communicate with. The security will always default to the ``parent'' if not set. So if the Worklet.isSecure and the WorkletJunction.isSecure have not been specified, then the WorkletJunction will default to the security of the current WVM system. The default for plain systems is plainRMI and plainSocket and the default for secure systems is secureRMI and secureSocket. If WorkletJunction.isSecure is set and the WorkletJunction.isSecure has not been set then those WorkletJunctions will default to the security level of the Worklet. The last, and highest priority level is at the WorkletJunction. You can either use the isSecure method or specify the methods through the transportMethods function. Using the transportMethods function alone is sufficient, and will override the isSecure method. Here's an example of how to set the methods:

String[] tm = {"secureRMI", "plainRMI", "secureSocket", "plainSocket"};

Frequently Asked Questions (FAQ)

Possible errors

Future Items

Questions, Contact

Any questions or comments can be directed to Dan Phung.

back to Worklets documentation

Copyright 2002: The Trustees of Columbia University in the City of New York. All Rights Reserved
Author: Dan Phung
Last Modified 20 October 2002