3. Client Usage

3.1 Command-Line Utilities

3.1.1 clarens-proxy-init

This command is used to create a so-called proxy certificate. This certificate actually consist of three parts: a temporary certificate, an accompanying private key, and a longer-lived certificate. The latter is used to sign the temporary certificate.

Shell

clarens-proxy-init -h

Usage: clarens-proxy-init [options]
 
Options:
  -h          Show this message
  -c FILE     Use FILE as certificate file
                  [default: /home/conrad/.globus/usercert.pem]
  -k FILE     Use FILE as private key file
                  [default: /home/conrad/.globus/userkey.pem]
  -t DAYS     Time that the proxy will remain valid in days
                  [default: 2]
  -b bits     Number of bits to use for key
                  [default: 512]
  -d          Show some debugging information
  -v          Print version number and exit

The use of a proxy certificate has several advantages:

• It is valid only for a limited time, shortening the time that a proxy can be used by potential attackers.
• Since it contains a true certificate and an accompanying key, it can be used for so-called credential delegation, where a third party can act on your behalf for a restricted time.

Of course, there are also several disadvantages:

• The limited validity period requires that the proxy be renewed if a long-running process or job makes use of the delegation feature.
• If the certificate and key are misapproriated, they may be used to impersonate the user who created the proxy. Revoking the user's certificate is the only recourse available when a proxy becomes compromised. The delays in propagating certificate revocation lists leaves enough time for an attacker to considerable damage. And of course issuing a replacement certificate may be slow.

Usually the command is issued from a shell prompt without any options. The user is then asked for the password used to decrypt the private key used to sign the newly created temporary certificate:

Shell

clarens-proxy-init
Enter pass phrase for /home/user/.globus/userkey.pem:

This process ensures that only the owner of the long-lived certificate can create proxy certificates. The default is to use the user's certificate and key files $HOME/.globus/usercert.pem and $HOME/.globus/userkey.pem To use different certificate and key files, specify the file names with the -c and -k options.

3.1.2 clarens-ping

In analogy to the well-known ping command, the clarens-ping command can be used to check whether a Clarens server responds to requests, and the turnaround times for those requests. The command is part of the clarens-client-python packages, and simply calls the server's echo.echo method.

Shell

clarens-ping --help

Usage:
 /opt/openpkg/bin/clarens-ping --<option>=<value> URL
   or
 /opt/openpkg/bin/clarens-ping --<option>
 
Currently options known are:
--debug    Turn on debugging
--help     Show this message
--host     Name of the host to connect to
--max      The maximum number of times to try
--path     The path to the clarens server on the remote host
--port     The port the remote server is listening on
--protocol The transport protocol: either http or https
--size     Message size, excluding header and encoding
--sleep    Delay between packets in seconds
--url      A complete URL to specify the location of the server

The simplest use of the clarens-ping command is with the URL of the server as the only argument. Pressing Ctrl-C aborts the process, and prints the minimum, average, and maximum response times of the server.

Shell

clarens-ping http://localhost:8080/clarens/

Contacting http://localhost:8080/clarens/...
OK
Received 289 bytes, time = 3.752 ms
Received 289 bytes, time = 4.278 ms
Received 289 bytes, time = 64.776 ms
Received 289 bytes, time = 4.043 ms
Received 289 bytes, time = 4.015 ms
rtt min/avg/max = 3.752/16.173/64.776 ms

3.1.3 clarens-package-hostcert

Since it is convenient to keep track of files stored as part of a particular installation via the RPM file database, this command provides a way to package a host certificate into an RPM. The RPM will also ensure that the certificate is installed correctly.

Shell

clarens-package-hostcert
Usage: clarens-package-hostcert <certfile.pem>

The command should be supplied with the file name of a PEM-encoded certificate, e.g.:

Shell

clarens-package-hostcert hostcert.pem
Wrote: /opt/openpkg/RPM/PKG/hostcert-ServerName-5e4666aa-1.noarch.rpm

The name of the package is constructed out of the certificate's distinguished name (DN), with the version number being a hash value calculated from the certificate. This ensures that the RPM package name should be unique. The resultant RPM package can be installed as usual:

Shell

rpm -i /opt/openpkg/RPM/PKG/hostcert-ServerName-5e4666aa-1.noarch.rpm

The certificate will be installed in $opkg_root/etc/grid-security/hostcert.pem.

3.1.4 clarens-package-hostkey

In analogy to the previous command, the host key can also be packaged:

Shell

clarens-package-hostkey
Usage: clarens-package-hostcert <keyfile.pem> <certfile.pem>

The key will be encrypted inside the RPM package since host keys are usually stored unencrypted in the server filesystem. This provides some modicum of security for storing the key in paces that may not be entirely secure.

E.g.:

Shell

clarens-package-hostkey hostkey.pem hostcert.pem
 
For security reasons we will encrypt the key inside the package
Enter Encryption Password:
Verifying - Enter Encryption Password:
Wrote: /opt/openpkg/RPM/PKG/hostkey-ServerName-5e4666aa-1.noarch.rpm

Upon installation of the resultant RPM package, the user will be prompted for the password used to encrypt the key. If the correct password is entered, the unencrypted key will be installed in $opkg_root/etc/grid-security/hostkey.pem. The encrypted key file will be stored in $opkg_root/etc/grid-security/hostkey_unenc.pem.

3.1.5 clarens-package-cacert

This command provides a convenient way to package certificate authority (CA) certificates.

Shell

clarens-package-cacert
Usage: clarens-package-cacert <certfile.pem>

E.g.

Shell

clarens-package-cacert cacert.pem
Wrote: /opt/openpkg/RPM/PKG/cacert-CAName-5e4666aa-1.noarch-anyos-hco.rpm

As with the host certificate, the package name is constructed in such a way that it should be unique. In addition, the dependencies of the RPM package will be set up to that the whole certificate chain must be installed. E.g. if the CA with the distinguished name CAName was issued by a higer level CA with a DN of CA-pki, an RPM package named
cacert-CA-pki-XXXXXX-1.noarch.rpm
will be required to be installed first. This might seem onerous, but using a CA certificate without having the full certificate chain available makes it virtually useless!

The RPM package will install the certificate in the directory
$opkg_root/etc/grid-security/certificates/5e4666aa.0, linked to the real file in
$opkg_root/etc/grid-security/certificates.real/cacert-CAName-5e4666aa in the above example.

3.1.6 clarens-package-cadir

CA certificates are often distributed as a bundle, or are available as a set of files in a single directory. To package all the CA certificates in such a directory, use

Shell

clarens-package-cacert /my/dirname

The RPM files will be created exactly as if the clarens-package-cacert command was invoked for each of the files.

3.1.7 clarens-package-root

The ROOT[13] analysis package is distributed in binary form as a compressed tar archive. Since manually compiling this package from source may result is a package that is binary incompatible with the released binary versions, this command makes it possible to repackage the tar archive as an RPM package.

Usage is simply e.g.:

Shell

clarens-package-root root_v3.10.02.Linux.RH10.0.gcc33.tar.gz

The resultant RPM package will install files in $opkg_root/lib/root/. Upon initializing the OpenPKG environment, the binary and library paths and environment variables will be set up so that the ROOT application can be invoked from the command line by simply typing root.

3.2 Kerberos Certificate Authority

In a Kerberos environment users are authenticated by a central authority and a strong cryptographic ticket is created on the client system. This ticket is very similar to a proxy certificate, containing a public and private keypair. The Kerberos infrastructure can be leveraged to provide an authentication environment similar to that provided by a certificate authority that issues certificates by converting the temporary ticket information into an X509 certificate and private key pair.

This functionality is provided by the kx509 utility, which can be downloaded and installed using the command clump install kx509.

To create a proxy certificate from a Kerberos ticket:

Shell

kinit
kx509
kxlist -p

The proxy certificate will be valid for the same period as the ticket.

3.3 Python

In the clarens-client-python package, the file Clarens.py contains a Clarens base class that can be used from the command line or from more complex scripts or programs. This base class has a dependency on the M2Crypto package, which is also used on the server.

3.3.1 Simple example

To initiate a client session, import the Clarens module, and instantiate a clarens_client object:

PYTHON

import Clarens
dbsvr=Clarens.clarens_client('http://localhost:8080/clarens/')

Note that the URI does not have a fixed form like some other XMLRPC servers use (e.g. always ending in the path /RPC2).

The object constructor has the following options:

OPTION	VALUES	default	DESCRIPTION
debug	0 or 1	0	Show requests responses when set.
certfile	Filename	/tmp/x509up_u$UID then
		$HOME/.globus/usercert.pem	Path to a PEM-encoded certificate.
keyfile	Filename	/tmp/x509up_u$UID	Path to a PEM-encoded private key.
		then
		$HOME/.globus/userkey.pem
callback	Function	util.passphrase_callback	The name of a function
			that returns a password.
passwd	string	None	The private key password.

3.3.2 Procedure calls

Procedure calls implemented by the remote server may now be called as methods of the client object. The simplest method is the echo.echo method, which merely returns its argument. Return values are part of a list by convention of the XMLRPC protocol:

PYTHON

>>> dbsvr.echo.echo('Hello')
['Hello']

In this case, the string Hello would be returned as ['Hello'].

There are a whole list of system.method methods implemented to query the server as to the methods it implements. These are discussed elsewhere.

3.3.3 Session termination

Using the system.logout method of the client object:

PYTHON

>>> dbsvr.system.logout()
0

3.3.4 Complete example

In summary, the complete example will look as follows:

PYTHON

import Clarens
dbsvr=Clarens.clarens_client('http://localhost:8080/clarens/')
dbsvr.echo.echo('Hello')
dbsvr.system.logout()

3.3.5 Binary return data

While encoding requests and responses simplifies server and client interactions, it does have one serious drawback: large binary responses are difficult to handle. Such a response must be returned as a string encoded in a text-friendly way, e.g. so-called base-64 encoding. This increases the CPU requirements on both the server and client. Since the data encoding increases the size of the response, more bandwidth is required to transport the data.

For that reason, Clarens returns binary data responses in raw form. This might confuse a client application expecting XML-encoded text. To enable or disable automatic XML deserialization, use the enable_deserialize and disable_deserialize methods as follows:

PYTHON

import Clarens
dbsvr=Clarens.clarens_client('http://localhost:8080/clarens/')
dbsvr.disable_deserialize()
content=dbsvr.file.read("/file.txt",0,-1)
dbsvr.enable_deserialize()
dbsvr.system.logout()

The variable contents should contain the content of the remote file after this code is executed.

3.3.6 Debugging

To see the requests being passed to the server, and the return values from the server enable the debug option:

PYTHON

import Clarens
dbsvr=Clarens.clarens_client('http://localhost:8080/clarens/',debug=1)
dbsvr.echo.echo('Hello')
dbsvr.system.logout()

3.3.7 Using a different certificate file

To use a different certificate and key file combination, use the certfile and keyfile options:

PYTHON

import Clarens
dbsvr=Clarens.clarens_client('http://localhost:8080/clarens/',
                             certfile='usercert.pem',
                             keyfile='userkey.pem')
dbsvr.echo.echo('Hello')
dbsvr.system.logout()

The certificate and key filenames must be accessible from the current working directory in the way they are specified. There are no special directories searched for these files.

3.4 ROOT

The ROOT client is written in C++, for use in both compiled and CINT-interpreted code. The client provides both the basic infrastructure to log into an Clarens server and execute RPC calls, as well as a high-level interface to the file.<method> methods. The latter can be used as a replacement for the standard TFile class.

This interface depends on Root, OpenSSL and the cURL HTTP transport library being present on the system.

3.4.1 TCWebfile

The most useful part of the client at this stage is the ability to open a remote file using this class, which inherits from TFile details are given in section FIXME

3.4.2 A simple example

The following example shows how to open the file named hsimple.root in the top-level directory on the remote server:

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA();
 Clarens *clarens=new Clarens("http://localhost:8080/clarens/",rsa);
 TCWebFile f("/hsimple.root",clarens);
 TBrowser T;
}

The first two gSystem.Load statements loads the Clarens client extensions into memory, making them available for the script of program to use.

The UserRSA class above holds the user's authentication credentials and can be reused multiple times for connecting to different servers.

The Clarens class represents a connection to one server. A connection may be established explicitly using the open method.

Finally, the TCWebfile class represents a remote file. The object f can be used the same as any read-only TFile, including browsing its contents using the builting object browser, as is demonstrated above.

Note that multiple files can be opened on the server using the same Clarens object, which will remain instantiated until all references to it have been removed, after which it can be deleted. Deleting the Clarens object will also log the user out of the server using the system.logout remote method.

3.4.3 Different certificate and key files

The default user certificate and private key files are looked up in a proxy certificate, or in the files $HOME/.globus/usercert.pem and $HOME/.globus/userkey.pem. To use a different set of files, add the certificate and key filenames as arguments to the UserRSA object constructor:

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA("mycert.pem","mykey.pem);
 Clarens *clarens=new Clarens("http://localhost:8080/clarens/",rsa);
 TCWebFile f("/hsimple.root",clarens);

 TBrowser T;
}

This example uses the same file for both the private key and the certificate. This happens to be the way that the grid-proxy-init command stores its temporary certificate and an unencrypted private key for the user with ID 510.

3.4.4 Caching file reads

Since the call latency for an RPC call on a wide area network (WAN) can be significant, it is always useful to to some client-side caching of the file in question. By default, a cache size of 1 MB is used. To change the cache size we instruct the the TCWebFile constructor to not create a cache through an optional fourth flags parameter:

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA("mycert.pem","mykey.pem);
 Clarens *clarens=new Clarens("http://localhost:8080/clarens/",rsa,0);

 f.UseCache(10,512*1024);  // Set cache size
 f.Init(kFALSE);            // Initialize the object
 
 TBrowser T;
}

In this example the TCWebfile object is set to use a cache of a 10 pages, with a page size of 512 kB each. The cache is not persistent, so that data downloaded by the client is lost when the TCWebFile is destroyed.

3.4.5 Multiple files on a single site

Multiple files can be opened using the same connection to the remote server.

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA();
 Clarens *clarens=new Clarens("http://localhost:8080/clarens/",rsa);
 TCWebFile f("/hsimple.root",clarens);
 TCWebFile f("/mydata.root",clarens);

 TBrowser T;
}

3.4.6 Multiple sites, single login

Opening files from multiple sites could be useful for doing simultaneous analysis on these files. This certificate and private key are read only once. If the private key is encrypted, the password is only needed once.

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA();
 
 // Create two connections
 Clarens *c1=new Clarens("http://localhost:8080/clarens/",rsa);
 Clarens *c2=new Clarens("https://otherhost:8443/clarens/",rsa); 
 
 // Open one file on each server
 TCWebFile f1("/hsimple.root",c1);
 TCWebFile f2("/mydata.root",c2);

 TBrowser T;
}

3.4.7 TCSystemDirectory

The TCSystemDirectory class can be used to browse a remote filesystem through Clarens.

The constructor takes 5 arguments, the last of which is optional. Here is an example:

C++

{
 gSystem.Load("clarens.sl");
 gSystem.Load("clarens_file.sl");

 UserRSA *rsa=new UserRSA();
 TCSystemDirectory s("/","localhost","/",
            "http://localhost:8080/clarens/",rsa);
 TBrowser T;
 s.Browse(&T);
}

This should make a connection to the server running on the localhost at the URL specified in the fourth argument. The UserRSA object is used once again to hold authentication information.

The first and second arguments corresponds to the Name and Title arguments of a Root TNamed object, and is used to construct a tree in the TBrowser. The third argument is the full path of the directory being browsed on the Clarens server, as seen from the client side. In this case we browse the root directory.

A TBrowser object is instantiated, and the Browse method of the TCSystemDirectory is called. If the remote server was contacted successfully, a folder named localhost should show up in the left panel of the browser window.