Table of Contents
- 1. Semantics and syntax of APIs
- 2. Semantics and syntax of the WSDL
- 3. Protocol Specifications
- 4. Command line tools
- 5. Overview of Graphical User Interfaces
- 6. Semantics and syntax of domain-specific interface
- 7. Configuration interface
- 7.1. Configuring Globus to Trust a Particular Certificate Authority
- 7.2. Configuring Globus to Create Appropriate Certificate Requests
- 7.3. Requesting Service Certificates
- 7.4. Specifying Identity Mapping Information
- 7.5. Configuring Certificate Revocation Lists (CRLs)
- 7.6. GSI File Permissions Requirements
- 8. Environment variable interface
Documentation for the APIs in this component can be found here:
- gaa_core [no frames]
- gaa_gss_generic [no frames]
- gaa_plugin [no frames]
- globus_authz [no frames]
- globus_authz_callout_error [no frames]
- globus_gridmap_callout_error [no frames]
- globus_gsi_callback [no frames]
- globus_gsi_cert_utils [no frames]
- globus_gsi_credential [no frames]
- globus_gsi_openssl_error [no frames]
- globus_gsi_proxy_core [no frames]
- globus_gsi_proxy_ssl [no frames]
- globus_gsi_sysconfig [no frames]
- globus_gss_assist [no frames]
- globus_gssapi_gsi [no frames]
- globus_openssl_module [no frames]
- gssapi_error [no frames]
For information on the internationalization API, see the C Common Libraries Public Interface.
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.
Please see the Pre-WS A&A Command Reference.
[provide an overview of the purpose and structure of the domain-specific interface]
This section describes the configuration steps required to:
- Determine whether or not to trust certificates issued by a particular Certificate Authority (CA),
- Provide appropriate default values for use by the grid-cert-request command, which is used to generate certificates,
- Request service certificates, used by services to authenticate themselves to users, and
- Specify identity mapping information.
In general, Globus tools will look for a configuration file in a user-specific location first, and in a system-wide location if no user-specific file was found. The configuration commands described here may be run by administrators to create system-wide defaults and by individuals to override those defaults.
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 Credentials in Pre-WS A&A 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:
Table 1. CA files
| The trusted CA certificate. |
| A configuration file defining the distinguished names of certificates signed by the CA. |
Pre-WS Globus components will honor a certificate only if:
- its CA certificate exists (with the appropriate name) in the TRUSTED_CA directory, and
- the certificate's distinguished name matches the pattern described in the signing policy file.
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:
Table 2. Certificate request configuration files
globus-user-ssl.conf
| Defines the distinguished name to use for a user's certificate request. The format is described here. |
globus-host-ssl.conf
| Defines the distinguished name for a host (or service) certificate request. The format is described here. |
grid-security.conf
| A base configuration file that contains the name and email address for the CA. |
directions
| An optional file that may contain directions on using the CA. |
Many CAs provide tools to install configuration files called
globus-user-ssl.conf.
,
cert_hash
globus-host-ssl.conf.
,
cert_hash
grid_security.conf.
, and
cert_hash
directions.
in the trusted certificates directory. The command:
cert_hash
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 CA 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:
- REQUEST HEADER, printed to a certificate request file,
- USER INSTRUCTIONS, printed on the screen when one requests a user certificate,
- NONUSER INSTRUCTIONS, printed on the screen when one requests a certificate for a service.
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:
Table 3. Certificate request files
| An empty file. When you receive your actual service certificate from your CA, you should place it in this file. |
| The certificate request, which you should send to your CA. |
| The private key associated with your certificate request, encrypted with the pass phrase that you entered when prompted by grid-cert-request. |
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 Credentials in Pre-WS A&A. 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
" \ -lnlocal_name
To delete an entry from the gridmap
file, run:
$GLOBUS_LOCATION/sbin/grid-mapfile-delete-entry \ -dn "Distinguished Name
" \ -lnlocal_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:
- If the
GRIDMAP
environment variable is set, thegridmap
file location is the value of the environment variable. Otherwise:
- If the user is root (uid 0), then the
gridmap
file is/etc/grid-security/grid-mapfile
. - Otherwise, the
gridmap
file is$HOME/.gridmap
.
- If the user is root (uid 0), then the
The Globus Toolkit supports CRLs on both the client and server side. CRL support is optional, however if a CRL file is present it must be correctly formatted or it will cause an error to be raised and certificates from CA the CRL is associated with, will not be honored.
A CRL file should be stored in the trusted certificates directory alongside the file containing the trusted CA certificated it is associated with (normally this is /etc/grid-security/certificates). The filename of the CRL file should be the same basename of the associated CA certificate file, but with a ".r0" extension.
For example if a CA certificate was stored in 42864e48.0 the CRL for that CA should be stored in 42864e48.r0.
Globus treats the "Next Update" field of the CRL as an expiration field. If the time in the Next Update field has past Globus will treat the CRL as invalid and cease to accept certificates issued by the CA associated with the CRL in question.
The CRL should be stored in base-64 encoded PEM. The file should look like the example below. Note that the BEGIN and END lines are significant and must appear exactly as shown. Any text before the BEGIN line or after the END line ignored.
-----BEGIN X509 CRL----- MIIDQTCCAikwDQYJKoZIhvcNAQEFBQAwdTETMBEGCgmSJomT8ixkARkWA25ldDESMBAGCgmSJomT 8ixkARkWAmVzMSAwHgYDVQQLExdDZXJ0aWZpY2F0ZSBBdXRob3JpdGllczEZMBcGA1UECxMQRE9F IFNjaWVuY2UgR3JpZDENMAsGA1UEAxMEcGtpMRcNMDIwNTA5MjAwMjM2WhcNMDIwNjA4MjAwMjM2 WjCCAYEwEgIBXBcNMDIwMzE5MTcyNjI4WjASAgFbFw0wMjAzMTkwMDA0NDJaMBICASUXDTAyMDIx MjIwMTkzMVowEwICAK8XDTAyMDUwNzIzMzAxNFowEgIBUBcNMDIwMzEyMjAzMjM4WjATAgIArhcN MDIwNTA3MjMyMjM5WjASAgFPFw0wMjAzMjcxNDQxMTJaMBICAR4XDTAyMDIwNDIxNTc1MVowEgIB SRcNMDIwMzE0MjI0OTQzWjASAgF2Fw0wMjA0MDgxOTMwMzNaMBMCAgChFw0wMjA0MzAyMDQwMjVa MBICARMXDTAyMDEyOTIwMTQwOFowEwICAKAXDTAyMDQzMDIwNDAyNVowEgIBEhcNMDIwMTI5MTk1 NDIzWjATAgIAmhcNMDIwNTA5MjAwMjM2WjASAgENFw0wMjAxMjgyMzE0NDZaMBICATwXDTAyMDMw NTE5NDExM1owEgIBOBcNMDIwMzE5MjMxOTI5WjASAgE3Fw0wMjAzMDgyMDE4NDhaMA0GCSqGSIb3 DQEBBQUAA4IBAQBWt6fD7AsvcmuTsSx9GWPbFIR3CCG7yIQUDiBSOOJi3guKh4tLqiCIQeIkGbMp 7XeEk+5oKRcuwZdMQpseKO6GYVVACEkqDczk2L62kMiE/7cTbXryKJRg87fGF6MC+uXcU0bTCtpC tByQ82yaKuPw/C+JYOurMzhyc8ZSxzJxz7WKYEiCzig5ZiVBvqO7ksSJGUy08ABWSmPBIL3u3CG6 Lz7aV/GiME20eXQRW++9256NhkT2P2IYETa5c/UFWlwyAFLq23C5u/R5e1sqpK5BcmAPqId957b9 +g7I9/ZsXj1ZRNlEPZ3wu6XHwVpC2TSLG95B+rl0TDNzxEKho1Rc -----END X509 CRL-----
End Entity (User, Host and Service) Certificates and the GSI Authorization Callout Configuration File:
- May not be executable
- May not be writable by group and other
- Must be either regular files or soft links
Private Keys and Proxy Credentials:
- Must be owned by the current (effective) user
- May not be executable
- May not be readable by group and other
- May not be writable by group and other
- Must be either regular files or soft links
CA Certificates, CA Signing Policy Files, the Grid Map File and the GAA Configuration File:
- Must be either regular files or soft links
GSI Authorization callout configuration files
- Must exist
- Should be world readable
- Should not be writable by group and other
- Should be either a regular file or a soft link
GSI GAA configuration files
- Must exist
- Should be world readable
- Should not be writable by group and other
- Should be either a regular file or a soft link
Credentials are looked for in the following order:
service credential
host credential
proxy credential
user credential
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:
- If
X509_USER_CERT
andX509_USER_KEY
exist and contain a valid certificate and key, those files are used. - Otherwise, if the files
/etc/grid-security/
andservice/service
cert/etc/grid-security/
exist and contain a valid certificate and key, those files are used.service/service
key - Otherwise, if the files
$GLOBUS_LOCATION/etc/grid-security/
andservice/service
cert$GLOBUS_LOCATION/etc/grid-security/
exist and contain a valid certificate and key, those files are used.service/service
key - Otherwise, if the files
andservice/service
cert
in the user'sservice/service
key.globus
directory exist and contain a valid certificate and key, those files are used.
For host credentials:
- If
X509_USER_CERT
andX509_USER_CERT
exist and contain a valid certificate and key, those files are used. - Otherwise, if the files
/etc/grid-security/hostcert.pem
and/etc/grid-security/hostkey.pem
exist and contain a valid certificate and key, those files are used. - Otherwise, if the files
$GLOBUS_LOCATION/etc/grid-security/hostcert.pem
and$GLOBUS_LOCATION/etc/grid-security/hostkey.pem
exist and contain a valid certificate and key, those files are used. - Otherwise, if the files
hostcert.pem
andhostkey.pem
in the user's.globus
directory, exist and contain a valid certificate and key, those files are used.
For user credentials:
- If
X509_USER_CERT
andX509_USER_KEY
exist and contain a valid certificate and key, those files are used. - Otherwise, if the files
usercert.pem
anduserkey.pem
exist in the user's.globus
directory, those files are used. - Otherwise, if a PKCS-12 file called
usercred.p12
exists in the user's.globus
directory, the certificate and key are read from that file.
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:
- If the
GRIDMAP
environment variable is set, the grid map file location is the value of that environment variable. Otherwise:
- If the user is root (uid 0), then the grid map file is
/etc/grid-security/grid-mapfile
. - Otherwise, the grid map file is
$HOME/.gridmap
.
- If the user is root (uid 0), then the grid map file is
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:
- If the
X509_CERT_DIR
environment variable is set, the trusted certificates directory is the value of that environment variable. - Otherwise, if
$HOME/.globus/certificates
exists, that directory is the trusted certificates directory. - Otherwise, if
/etc/grid-security/certificates
exists, that directory is the trusted certificates directory. - Finally, if
$GLOBUS_LOCATION/share/certificates
exists, then it is the trusted certificates directory.
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:
- If the
GSI_AUTHZ_CONF
environment variable is set, the authorization callout configuration file location is the value of this environment variable. - Otherwise, if
/etc/grid-security/gsi-authz.conf
exists, then this file is used. - Otherwise, if
$GLOBUS_LOCATION/etc/gsi-authz.conf
exists, then this file is used. - Finally, if
$HOME/.gsi-authz.conf
exists, then this file is used.
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:
- If the
GSI_GAA_CONF
environment variable is set, the GAA configuration file location is the value of this environment variable. - Otherwise, if
/etc/grid-security/gsi-gaa.conf
exists, then this file is used. - Otherwise, if
$GLOBUS_LOCATION/etc/gsi-gaa.conf
exists, then this file is used. - Finally, if
$HOME/.gsi-gaa.conf
exists, then this file is used.
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:
- If the
GRID_SECURITY_DIR
environment variable is set, the grid security directory is the value of that environment variable. - If the configuration files exist in
/etc/grid-security
, the grid security directory is that directory. - if the configuration files exist in
$GLOBUS_LOCATION/etc
, the grid security directory is that directory.