The GSS Assist API provides helper functions wrapping the process of security (GSS) context establishment, support for gridmap authorization and various other helper functions that wrap GSSAPI functions and capture common usage.

The GSSAPI implementation provided by the toolkit is based upon SSL/TLS with extensions to the standard path validation mechanism to handle proxy certificates. It relies upon the credential and certificate utility APIs for general certificate acquisition and inspection functionality.

This API provides a callback that can be plugged into the OpenSSL path validation framework. This callback provides the additions to path validation required for dealing with proxy certificates and X.509 extensions. Furthermore, it allows applications to inspect data, e.g. the validated certificate chain, after the validation is done.

The Certificate Utilities API provides helper functions for dealing with X.509 certificates. This API does not use the "handle" concept mentioned in the introduction. Rather, it operates on datatypes provided by the OpenSSL APIs.

The Credential API deals with reading and writing certificates from and to the file system and the OpenSSL I/O abstraction layer. It also provides functions for inspecting and validating the read credentials.

The Proxy APIs provide a implementation of the X.509 Proxy Certificate Extension ASN.1 structure as well as functions for creating new proxies.

This API serves as a abstraction layer for OS specific information needed by the security infrastructure. It provides OS specific functions for discovering certificates from a set of predefined standard locations as well as functions for doing the same for various configuration files.

The GSSAPI implementation contained in this component produces security tokens that follow an extended version of the SSL/TLS protocol. More information about the protocol can be found here.

The GSSAPI implementation contained in this component produces security tokens that follow an extended version of the SSL/TLS protocol. More information about the protocol can be found here.

[provide an overview of the purpose and structure of the domain-specific interface]

[list and describe detailed information here]

The Globus tools will trust certificates issued by a CA if (and only if) it can find information about the CA in the trusted certificates directory. The trusted certificates directory is located as described in Section 9, “Environment variable interface” and exists either on a per machine or on a per installation basis. The following two files must exist in the directory for each trusted CA:

Pre-WS Globus components will honor a certificate only if:

Java-based components ignore the signing policy file and will honor all valid certificates issued by trusted CAs.

The cert_hash that appears in the file names above is the hash of the CA certificate, which can be found by running the command:

$GLOBUS_LOCATION/bin/openssl x509 -hash -noout < ca_certificate

Some CAs provide tools to install their CA certificates and signing policy files into the trusted certificates directory. You can, however, create a signing policy file by hand; the signing policy file has the following format:

access_id_CA X509 'CA Distinguished Name'
pos_rights globus CA:sign
cond_subjects globus '"Distinguished Name Pattern"'

In the above, the CA Distinguished Name is the subject name of the CA certificate, and the Distinguished Name Pattern is a string used to match the distinguished names of certificates granted by the CA. Some very simple wildcard matching is done: if the Distinguished Name Pattern ends with a '*', then any distinguished name that matches the part of the CA subject name before the '*' is considered a match. Note: the cond_subjects line may contain a space-separated list of distinguished name patterns.

A repository of CA certificates that are widely used in academic and research settings can be found here.

The grid-cert-request command, which is used to create certificates, uses the following configuration files:

Many CAs provide tools to install configuration files called globus-user-ssl.conf.cert_hash, globus-host-ssl.conf.cert_hash, grid_security.conf.cert_hash, and directions.cert_hash in the trusted certificates directory. The command:

grid-cert-request -ca cert_hash

will create a certificate request based on the specified CA's configuration files. The command:

grid-cert-request -ca

will list the available CAs and let the user choose which one to create a request for.

You can specify a default CA for certificate requests (i.e., a CA that will be used if grid-cert-request is invoked without the -ca flag) by making the following symbolic links (where GRID_SECURITY is the grid security directory and TRUSTED_CA is the trusted CAs directory):

ln -s TRUSTED_CA/globus-user-ssl.conf.cert_hash \
      GRID_SECURITY/globus-user-ssl.conf
ln -s TRUSTED_CA/globus-host-ssl.conf.cert_hash \
      GRID_SECURITY/globus-host-ssl.conf
ln -s TRUSTED_CA/grid_security.conf.cert_hash \
      GRID_SECURITY/grid_security.conf

And optionally, if the CA specific directions file exists:

ln -s TRUSTED_CA/directions.cert_hash \
      GRID_SECURITY/directions

This can also be accomplished by invoking the grid-default-ca command.

The directions file may contain specific directions on how to use the CA. There are three types of printed messages:

Each message is delimited from others with lines ----- BEGIN message type TEXT ----- and ----- END message type TEXT -----. For example, the directions file would contain the following lines:

----- BEGIN REQUEST HEADER TEXT -----
This is a Certificate Request file

It should be mailed to ${GSI_CA_EMAIL_ADDR}
----- END REQUEST HEADER TEXT -----

If this file does not exist, the default messages are printed.

Different CAs use different mechanisms for issuing end-user certificates; some use mechanisms that are entirely web-based, while others require you to generate a certificate request and send it to the CA. If you need to create a certificate request for a service certificate, you can do so by running:

grid-cert-request -host hostname -service service_name

where hostname is the fully-qualified name of the host on which the service will be running, and service_name is the name of the service. This will create the following three files:

The grid-cert-request command recognizes several other useful options; you can list these with:

grid-cert-request -help

Several Globus services map distinguished names (found in certificates) to local identities (e.g., unix logins). These mappings are maintained in the gridmap file. The gridmap file is discovered according to the rules described in Section 9, “Environment variable interface”. A gridmap line of the form:

"Distinguished Name" local_name

maps the distinguished name Distinguished Name to the local name local_name. A gridmap line of the form:

"Distinguished Name" local_name1,local_name2

maps Distinguished Name to both local_name1 and local_name2; any number of local user names may occur in the comma-separated local name list.

Several tools exist to manage grid map files. To add an entry to the grid map file, run:

$GLOBUS_LOCATION/sbin/grid-mapfile-add-entry \
        -dn "Distinguished Name" \
        -ln local_name

To delete an entry from the gridmap file, run:

$GLOBUS_LOCATION/sbin/grid-mapfile-delete-entry \
        -dn "Distinguished Name" \
        -ln local_name

To check the consistency of the gridmap file, run

$GLOBUS_LOCATION/sbin/grid-mapfile-check-consistency

These commands recognize several useful options, including a -help option, which lists detailed usage information.

The location of the gridmap file is determined as follows:

Credentials are looked for in the following order:

X509_USER_PROXY specifies the path to the proxy credential. If X509_USER_PROXY is not set, the proxy credential is created (by grid-proxy-init) and searched for (by client programs) in an operating-system-dependent local temporary file.

X509_USER_CERT and X509_USER_KEY specify the path to the end entity (user, service, or host) certificate and corresponding private key. The paths to the certificate and key files are determined as follows:

For service credentials:

For host credentials:

For user credentials:

GRIDMAP specifies the path to the grid map file, which is used to map distinguished names (found in certificates) to local names (such as login accounts). The location of the grid map file is determined as follows:

X509_CERT_DIR is used to specify the path to the trusted certificates directory. This directory contains information about which CAs are trusted (including the CA certificates themselves) and, in some cases, configuration information used by grid-cert-request to formulate certificate requests. The location of the trusted certificates directory is determined as follows:

GSI_AUTHZ_CONF is used to specify the path to the GSI authorization callout configuration file. This file is used to configure authorization callouts used by both the gridmap and the authorization API. The location of the GSI authorization callout configuration file is determined as follows:

GSI_GAA_CONF is used to specify the path to the GSI GAA (Generic Authorization and Access control) configuration file. This file is used to configure policy language specific plugins to the GAA-API. The location of the GSI GAA configuration file is determined as follows:

GRID_SECURITY_DIR specifies a path to a directory containing configuration files that specify default values to be placed in certificate requests. This environment variable is used only by the grid-cert-request and grid-default-ca commands.

The location of the grid security directory is determined as follows: