The keychain server is used to store basic user data that the rest of the system can access (ex: the full name/emailo/instance URI for the Person instance that represents the CALO user).
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 section describes how to run the keychain service and how to connect to it and manage it. In addition to end user documentation, this section also provides developer documentation and testing information.
The distribution files for the CALO keychain service can be located under the build 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 distrbution 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.
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 documentation 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. See the keychain launch runtime parameter for more information on how to change this setting.
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.