Other Moses tools

A number of other tools part of the moses package are designed to support the law development process and leverage the interaction with the controller infrastructure. These tools are as follows:

  • Security related tools: provide the means to handle keys, signatures, hashes, and certificates;
  • Management tools - the controller manager : provides for automatic management of controllers.

Security tools

The Moses security tools are mix of programmatic and executable classes that assist the user in handling public/private keys, digital signatures, secure hashes, and digital certificates. They can be either used as parts of larger programs, or as stand-alone programs that can be run in separate virtual machines. In this tutorial only the stand alone usage is explained. For more details about these tools see the Moses reference manual.

Working with public keys

The Moses middleware uses public/private keys for digital signature purpose. These keys implement the corresponding interface defined in the java.security package, and are generated using the DSA algorithm. Moses uses keyPairCreation class in order to generate these keys as follows: 

java moses.security.keyPairCreation pubkeyfile privkeyfile

This class generates a new pair of public/private keys and saves them in the pubkeyfile and privkeyfile, respectively.
Another class, called KeyGenerator can also be used to create keys within a program. This class provides the methods PublicKey getPublic() and PrivateKey getPrivate() for the programmatic retrieval of the keys.

Working with certificates

For simplicity reasons, Moses uses its own format of certificates, implemented by the Java class LGICert. These certificates maintain the essential fields of any certificate (i.e. issuer public key, subject public key, attributes, and the signature of the issuer over the certificate). The LGICert class provides a number of methods to handle the certificates programmatically.
Additionally, a stand-alone class, called certCreation can be executed as a utility class, as follows: 

java moses.security.certCreation CApubkf CAprivkf SUBpubkf CERTf ATTRIBUTES

where CApubkf represent the file holding the public key of the issuer, CAprivkf the file holding the private key of the issuer, SUBpubkf the file holding the public key of the subject, CERTf the destination file for the certificate, and ATTRIBUTES represent the attributes of the certificate, as immediate argument.

Note that, depending on the operating system, and shell type, the argument has to obey a certain syntax. For example, in Unix/tcsh a role(manager) attributes has to be supplied as "role\(mgr\)".

An additional class, moses.Secu provides a programmatic API for handling digital signatures. Among the most useful methods provided by this class are byte[] sign(String msg, PrivateKey priv) and byte[] {signSelfCertificate(LGICert c, PrivateKey myKey).

Working with hashes

Moses uses hashes mainly for two purposes: for law and for public key identification. The body of a given law often refers to subjects by their public key hash, and specifies other laws to interact with by their hash.
The following executables can be used in order to compute the hashes: 

java moses.controller.AuthorityTable -fkeyfile
or
java moses.controller.AuthorityTable -ukeyURL

-- computes and displays the hash of the public key given as argument (URL or file). 

java moses.controller.PreparedLaw -flawfile
or
java moses.controller.PreparedLaw -ulawURL

-- computes and displays the hash of the law given as argument (URL or file).

Controller manager

The controller manager is an interactive web-based tool designed to manage a set of controllers in a tightly coupled environment, like in a cluster of servers. The controller manager serves a double purpose: 1) as a name server, it lists a number of registered controller, and 2) as a manger, it helps to start, monitor and stop the controllers that makeup the deployed Moses runtime infrastructure.

Prerequisites

In order to leverage its administrative functions, a controller manager should be started in a cluster environment with tightly coupled servers. The manager uses the ssh protocol to start controllers on remote machines. The cluster of server should have the protocol installed such that the following usage is enabled: ssh -t hostname command. Furthermore, every target machine in the cluster should be configured to start a controller remotely by having the classpath and path variables set up accordingly.

Starting the controller manager

An administrator user can start an instance of the controller manager by issuing the following command: 

java moses.ControllerManager
or:
java moses.ControllerManager -spport -ppath-to-config-directory -fcfg-file [-debug]

where port represents the HTTP port for web access, path-to-config-directory represents the configuration directory containing configuration files (if other than the default), and cfg-file represent the runtime configuration and access setup file.

Accessing the controller manager

As a name server, the controller manager is publicly accessible through its web-based interface. Assuming that the manager runs on port 9001 on the host hostname, one can view the controllers registered with the manager by accessing the following URL: 

http://hostname:9001/

The information presented by this web page is similar to the one displayed in Figure 1):

Figure 1) Controller manager main page

This page offers links to the management interface (not covered here), and provides two tables advertising controllers available as infrastructure. The top table lists all the controllers maintained by this controller manager, while the bottom table presents a list of foreign controllers registered with this controller manager (also called adopted controllers). For each controller, the following pieces of information is available:
  • Host represents the name of the host where the controller is running. By clicking on it, one can browse to the main page of each controller.
  • Port represents the port on which the controller is to be contacted by adopting actors.
  • Type represents the declared type of the controller (interpreting Java and Prolog laws, or both); this is an obsolete field, mostly maintained for legacy reasons.
  • User represents the user name of the manager that has started the controller.
  • Output provides a link to the standard output of a controller. During debugging and testing phase, the controller standard output is an important piece of information law developers need. This information is provided by the manager through this link. Because a controller can be shared among multiple actors, accessing it is subject to access control. When this field has the value public, everybody can access the output. If this field is private, the access is password protected. The password is assigned by the manager starting the controller.
  • Start time represents the time and date the controller has been started.
  • Test time represents the time and date the controller has been last tested. The manager has a built in agent that connects periodically to each controller and performs minimal interaction for the purpose of testing.
  • Status represents the status of the controller as detected by the periodic testing procedure described above. If the test is successful, the value of this field is Test_Java_Success, Test_Prolog_Success. Due to the current controller limitation of handling a single Prolog law at a time, the Test_Prolog_Failure message might suggest a false negative. If correlated, however, to a Test_Java_Failure message, this indicates an unavailable controller.
  • Load represents the number of actors a controller handles at the moment of last testing. If the controller is unavailable , this field displays unknown.
  • Certificate represents the certificate a controller carries for both mutual controller-to-controller, and for actor-to-controller authentication. When following the link provided by this field, the public key of the controller and of the certifying authority are displayed along with the certificate attributes.