Type CertificateManager

object --+
         |
        CertificateManager

A CertificateManager manages the certificates for a user.

It uses a CertificateRepository instance to maintain the certificates.
The repository keeps its certificates in a single large pool; however,
it provides a mechanism by which the user of the repository can
tag certificates with metadata. The certificate manager uses this
tagging mechanism to distinguish between a user's identity
certificates and the user's set of trusted CA certificates.

We accomplish this by defining a metadata tag for each certificate
imported: AG.CertificateManager.certType is the key; the value is
"identity" or "trustedCA".

The user's default identity is marked in the repository as well with
the metadat AG.CertificateManager.isDefaultIdentity, values 0/1. This default
is then returned by the call

    repo.FindCertificatesWithMetadata("AG.CertificateManager.isDefaultIdentity",
                                       "1")

The repo doesn't ensure that multiple certs get set to default; that
is up to this code.

This certificate manager will not use the system trusted CA directory
directly; it maintains a local cache of trusted CA certs in the
repository. Since OpenSSL and the Globus library expect these certificates
to have a particular file layout, the certificate manager will regenerate
this cache from the certificates in teh repository each time the set of
trusted CA certificates  in the repo changes. This set of certificates can
be determined by the call

    repo.FindCertificatesWithMetadata("AG.CertificateManager.certType",
                                       "trustedCA")

Globus proxies are also stored in the repository's space. Since they do
not have unique serial numbers, they are stored in filespace provided
for users with each certificate:

    certDesc = defaultCert
    proxyPath = certDesc.GetFilePath("globus_proxy")
    CreateGlobusProxy(certDesc.GetCertPath(),
                      certDesc.GetKeyPath(),
                      proxyPath)


Initialization
--------------
    
We will assume that if the repository  is not already present 
that we've not run this app before and must therefore initialize
the repository. It may be the case that the user has run an earlier
version of the AG software and therefore has an AG2.0-style certificate
repository already in place. We will ignore this, and initialize directly
from globus state. It is not likely at this stage of the game that
users already have a lot of new state built up in that repository.

Runtime configuration
---------------------

When an app starts up, we will need to do the following things
to initialize the user's environment to work properly with the Globus
toolkit:

    Set up the user's environment to point at the
    appropriate local settings by modifying os.environ.

    Determine if a valid proxy is in place. If not,
    call grid-proxy-init to create one.

We also support a mechanism for determining if the
existing proxy will expire soon, and provide a way
to as the user for a renewal of it.

Instance variables
------------------

userInterface       Reference to the UI object responsbile
                    for manipulations on this manager.

userProfileDir      Location of the per-user profile directory
                    for the user of this manager.

repoPath            Location of the certificate repository used by this mgr.

Configure the process environment to correspond to the chosen
configuration.

This method does not attempt to remedy any problems in the
configuration; rather, if the situation is not to its liking,
it raises an exception telling the caller what the problem
is. It is safe to reinvoke this method as needed.

If self.useDefaultDN is set, use the given DN to be the default
for this instance of the class.

If self.useCertFile is set, use that certificate as the default.

Otherwise,

If there are no identity certificates present, raise the
NoCertificates exception.

If there is exactly one identity certificate, mark it as the
default certificate.

If there are more than one identity certificates and none is
marked default, or more than one is marked default, raise the
NoDefaultIdentity exception.

Examine the default identity certificate.

If it has an encrypted private key, check for the existence of
a Globus proxy for the cert. If one does not exist, raise the
ProxyExpired exception.

Otherwise, set the following environment variables:

    X509_USER_PROXY: user proxy cert
    X509_CERT_DIR: location of trusted CA certificates

If the default identity certificate has an unencrypted private key,
we can use it directly. Set the following environment variables:

    X509_USER_CERT: user's certificate
    X509_USER_KEY: user's private key
    X509_RUN_AS_SERVER: set to override any lingering proxy
                        cert setting


This method sets self.defaultIdentity as a side effect. It
should be viewed as the current appropriate mechanism for
setting defaultIdentity.