The CALO keychain service is a lighweight storage service that runs in the backgrouns on every CALO-enabled machine. The keychain service is the bootstrap mechanism for CALO applications and is the first application that must be run. This document describes how to run the keychain service and how to connect to it and manage it. In addition to end user documentation, this document also provides developer documentation and testing information.
The distribution files for the CALO keychain service can be located under the CVS checkout or installation subdirectory "iris/plugins/keychain/export". The distribution files for the nightly build are located in this directory.
To get the keychain service, download all dostrbution files (if retrieving them from online), or navigate to the export directory on disk. Java 1.5 or higher must be installed. To run the keychain service, simply double-click on the file "keychain.jar". Note that if the keychain service is already running, a new service will not be run and will exit silently. To determine whether or not a keychain service is running, and to shut it down, see the section on Managing the Keychain service.
A Firefox extension is provided to manage the Keychain application. To install the extension, simply open the file "keychain.xpi" in the distribution ("export") directory. The extension can also be obtained for the last successfull nightly build here. Note that you may to right-click and download, and then open the file from disk to install it, because Firefox protects against unsigned xpis and currently the CALO keychain xpi is not signed.
Once the extension is installed, Firefox will need to be restarted. After restarting, simply navigate to the menu option "CALO->Query Keychain". This will bring up a windows that provides further instructions and controls to query/modify the keychain server and also to shut it down.
The developer API docuemntation for keychain service APIs in Java are located by clicking on this link. To obtain access to an IKeychain instance, simply include all the jars from the distribution in your classpath and then use the static accessor methods on the class KeychainService.
Note that within IRIS, the bean named "com.sri.calo.keychain.IKeychain" can be used to access the local keychain service. Also within IRIS is a bean named "keychain_server" which when explicitly set will run the CALO keyshain service within IRIS. Currently this is turned off by default, but is useful in unit testing.
Finally, note that IRIS depends on the keychain service. It stores the user's full name, person uri, login name, login password, and other info in the keychain. For this reason, IRIS automatically launches the keychain service at startup. To turn this feature off, the Java property "iris.keychain.launch" must be set to "false" (this can be done in iris.bat or desktop.bat", also note that if the keychain is already running then there won't be 2 instances run).
As a best practice for writing CALO XMl-RPC services, they should register application information in the keychain. For Java server implementations, developers can inherit from the class Server. This class automatically registers application information in the keychain so a CALO XML-RPC app can be discovered by the CALO client and server (using synchronization from client to server). In this way we should never hard-code application addresses and ports to connect with custom CALO XML-RPC servers.
For other languages besides Java, see the Javadoc for details on how application information is registered in the keychain.
Unit tests exist for the keychain service. The can be run by making sure that JUnit support is compiled into ant, navigating to "iris/plugins-src/keychain/test" and executing "ant test".