Features new in GT 6.0

Other Supported Features

Deprecated Features

GSI C has been tested on the following platforms:

Protocol changes in GSI C since GT 5.2

API changes since GT 5.2

Exception changes since GT 5.2

Schema changes since GT 5.2

The GSI C component depends on the following GCT components:

The GSI C component depends on the following 3rd party software:

During host authorization, the toolkit treats host names of the form hostname-ANYTHING.edu as equivalent to hostname.edu. This means that if a service was set up to do host authorization and hence accept the certificate hostname.edu, it would also accept certificates with DNs hostname-ANYTHING.edu.

The feature is in place to allow a multi-homed host following a "hostname-interface" naming convention, to have a single host certificate. For example, host grid.test.edu would also accept the likes of grid-1.test.edu or grid-foo.test.edu.

In GCT or GT 6.0, it is possible to disable this behavior, by setting the enviornment variable GLOBUS_GSSAPI_NAME_COMPATIBILITY to STRICT_RFC2818.

As mentioned in the introduction, the GSI C security framework uses the GSSAPI API and extensions to it to abstract security mechanism specific details. Below the GSSAPI layer there exist multiple APIs for dealing with credential management, X.509 certificates in general and proxy certificates in particular as well as security configuration. Each of these APIs is described in more detail below.

The general design principle guiding these APIs is data encapsulation. Data structures (handles and attributes) capture and encapsulate the state of the system. These data structures are then acted upon by various getters and setters, as well as other functions.

As described in the introduction the GSI C security framework essentially provides two authorization APIs, the generic Authorization API and the Gridmap API. These APIs differ in various ways:

The Authorization API provides a framework that allows callouts to 3rd party authorization solutions, does not provide a default authorization mechanism and is geared to authorizing the subject-action-object tuple.

The Gridmap API on the other hand, while allowing for custom callouts to be plugged in and override the default behavior, provides a default authorization and mapping mechanism based on the grid map file. Also, it only furnishes the callouts with information about the entity to be authorized, i.e. it does not provide information on the action and the object, so it is somewhat simpler in its approach. Finally, it provides the ability to map authorized entities to local system entities, e.g. UNIX user names. More information on the interface used for Gridmap callouts 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.

globus-update-certificate-dir - Update symlinks in the trusted CA directory

globus-update-certificate-dir [-help ] [-d DIRECTORY]

The globus-update-certificate-dir program creates symlinks between files (CA certificates, certificate revocation lists, signing policy, and certificate request configuration files) using the certificate hash the installed version of OpenSSL uses. OpenSSL 1.0.0 uses a different name hashing algorithm than previous versions, so CA distributions created with older versions of OpenSSL might not be able to locate trusted CAs and related files. Running globus-update-certificate-dir against a trusted CA directory will add symlinks to the files to the hash if needed.

The full set of command-line options to globus-update-certificate-dir consists of:

If the following variables affect the execution of globus-update-certificate-dir

grid-cert-diagnostics - Print diagnostic information about certificates and keys

grid-cert-diagnostics [-h ] | [-help ] [-p ] [-n ] [-c CERTIFICATE]

The grid-cert-diagnostics program displays information about the current user’s security environment, including information about security-related environment variables, security directory search path, personal key and certificates, and trusted certificates. It is intended to provide information to help diagnose problems using GSIC.

By default, grid-cert-diagnostics prints out information regarding the environment and trusted certificate directory. If the -p command-line option is used, then additional information about the current user’s default certificate and key will be printed.

The full set of command-line options to grid-cert-diagnostics consists of:

In this example, we see the default mode of checking the default security environment for the system, without processing the user’s key and certificate. Note the user receives a warning about a cog.properties and about an expired CA certificate. and about an expired CA certificate.

In this example, we show a user with a mismatched private key and certificate:

grid-cert-info - Display information about a certificate

grid-cert-info [-help ] [-usage ] [-version ] [-versions ]

The grid-cert-info program displays information contained within a certificate file. By default it shows a text representation of the entire certificate. Specific facts about the certificate can be shown instead by using command-line options. If any of those options are used, then the default display is suppressed. This can be added to the output by using the -all command-line option.

If multiple display options are included on the command-line, the facts related to those will be displayed on separate lines in the order that they occur. If an option is specified multiple time, that fact will be displayed multiple times.

The full set of command-line options to grid-cert-info are:

Display the validity times for the default certificate

Display the same information about a different certificate specified on the command-line

Display the subject of a certificate in both the default and the RFC 2253 forms.

The following environment variables affect the execution of grid-cert-info:

grid-cert-request - Generate a X.509 certificate request and corresponding private key

grid-cert-request [-help ] [-h ] [-? ] [-usage ]

[-version ] [-versions ]

The grid-cert-request program generates an X.509 Certificate Request and corresponding private key for the specified name, host, or service. It is intended to be used with a CA implemented using the globus_simple_ca package.

The default behavior of grid-cert-request is to generate a certificate request and private key for the user running the command. The subject name is derived from the gecos information in the local system’s password database, unless the -commonname, -cn, or -host command-line options are used.

By default, grid-cert-request writes user certificate requests and keys to the $HOME/.globus directory, and host and service certificate requests and keys to directory, and host and service certificate requests and keys to /etc/grid-security. This can be overridden by using the . This can be overridden by using the -dir command-line option.

The full set of command-line options to grid-cert-request are:

Create a user certificate request:

Create a host certificate for a host with two names.

The following environment variables affect the execution of grid-cert-request:

grid-default-ca - Select default CA for certificate requests

grid-default-ca [-help ] [-h ] [-usage ] [-u ] [-version ] [-versions ]

The grid-default-ca program sets the default certificate authority to use when the grid-cert-request script is run. The CA’s certificate, configuration, and signing policy must be installed in the trusted certificate directory to be able to request certificates from that CA. Note that some CAs have different policies and use other tools to handle certificate requests. Please consult your CA’s support staff if you unsure. The grid-default-ca is designed to work with CAs implemented using the globus_simple_ca package.

By default, the grid-default-ca program displays a list of installed CA certificates and the prompts the user for which one to set as the default. If invoked with the -list command-line option, grid-default-ca will print the list and not prompt nor set the default CA. If invoked with the -ca option, it will not list or prompt, but set the default CA to the one with the hash that matches the CA-HASH argument to that option. If grid-default-ca is used to set the default CA, the caller of this program must have write permissions to the trusted certificate directory.

The grid-default-ca program sets the CA in the one of the grid security directories. It looks in the directory named by the GRID_SECURITY_DIR environment, the X509_CERT_DIR, /etc/grid-security, and , and $GLOBUS_LOCATION/share/certificates. .

The full set of command-line options to grid-default-ca are:

List the contents of the trusted certificate directory that contain the string Example:

Choose that CA as the default:

The following environment variables affect the execution of grid-default-ca:

The grid-default-ca program displays CAs from all of the directories in its search list; however, grid-cert-request only uses the first which contains a grid security configuration.

The grid-default-ca program may display the same CA multiple times if it is located in multiple directories in its search path. However, it does not provide any information about which one would actually be used by the grid-cert-request command.

grid-cert-request(1)

grid-change-pass-phrase - Change the passphrase of a private key

grid-change-pass-phrase [-help ] [-usage ] [-version ] [-versions ]

The grid-change-pass-phrase program changes the passphrase protecting a private key or PKCS12 bundle containing a private key and certificate. By default, grid-change-pass-phrase uses the X509_USER_KEY environment variable to locate the private key. If that is not set, then it looks for $HOME/.globus/userkey.pem and and $HOME/.globus/usercred.p12 in succession. The path to a key can be specified by using the in succession. The path to a key can be specified by using the -file command-line option.

The full set of command-line options to grid-change-pass-phrase are:

Change the passphrase of the default private key:

The following environment variables affect the execution of grid-change-pass-phrase:

grid-proxy-init - Generate a new proxy certificate

grid-proxy-init [-help ] [-usage ] [-version ]

The grid-proxy-init program generates X.509 proxy certificates derived from the currently available certificate files. By default, this command generates a RFC 3820 Proxy Certificate with a 512 bit key valid for 12 hours in a file named /tmp/x509up_uUID. Command-line options and variables can modify the format, strength, lifetime, and location of the generated proxy certificate. . Command-line options and variables can modify the format, strength, lifetime, and location of the generated proxy certificate.

X.509 proxy certificates are short-lived certificates, signed usually by a user’s identity certificate or another proxy certificate. The key associated with a proxy certificate is unencrypted, so applications can authenticate using a proxy identity without providing a passphrase.

Proxy certificates provide a convenient alternative to constantly entering passwords, but are also less secure than the user’s normal security credential. Therefore, they should always be user-readable only (this is enforced by the GSI libraries), and should be deleted after they are no longer needed.

This version of grid-proxy-init supports three different proxy formats: the old proxy format used in early releases of the Globus Toolkit up to version 2.4.x, an IETF draft version of X.509 Proxy Certificate profile used in Globus Toolkit 3.0.x and 3.2.x, and the RFC 3820 profile used in Globus Toolkit Version 4.0.x and 4.2.x. By default, this version of grid-proxy-init creates an RFC 3820 compliant proxy. To create a proxy compatible with older versions of the Globus Toolkit, use the -old or -draft command-line options.

The full set of command-line options to grid-proxy-init are:

To create a proxy with the default lifetime and format, run the grid-proxy-init program with no arguments. For example:

To create a stronger proxy that lasts for only 8 hours, use the -hours and -bits command-line options to grid-proxy-init. For example:

The following environment variables affect the execution of grid-proxy-init:

The following files affect the execution of grid-proxy-init:

For more information about proxy certificate types and their compatibility in GT and GCT, see http://dev.globus.org/wiki/Security/ProxyCertTypes.

grid-proxy-destroy(1), grid-proxy-info(1)

grid-proxy-destroy - Destroy the default proxy certificate

grid-proxy-destroy [-help ] [-usage ] [-version ]

The grid-proxy-destroy program removes X.509 proxy files from the local filesystem. It overwrites the data in the files and removes the files from the filesystem. By default, it removes the current user’s default proxy (either /tmp/x509up_uUID where where UID is the current POSIX user id, or the file pointed to by the X509_USER_PROXY environment variable) unless a list of proxy file paths are included as part of the command line.

Use the -- command-line option to separate a list of proxy paths from command line options if the proxy file begins with the - character.

The full list of command-line options to grid-proxy-destroy are:

The following environment variables affect the execution of grid-proxy-destroy:

grid-proxy-init(1), grid-proxy-info(1)

grid-proxy-info - Display information about a proxy certificate

grid-proxy-info [-help ] [-usage ] [-version ]

The grid-proxy-info program extracts information from an X.509 proxy certificates, and optionally displays or returns an exit code based on that information.

The default mode of operation is to print the following facts about the current user’s default proxy: subject, issuer, identity, type, strength, path, and time left. If the command-line option -exists or -e is included in the command-line, nothing is printed unless one of the print options is specified. Instead, grid-proxy-info determines if a valid proxy exists and, if so, exits with the exit code 0; if a proxy does not exist or is not valid, grid-proxy-info exits with the exit code 1. Additional validity criteria can be added by using the -valid, -v, -hours, -h, -bits, or -b command-line options. If used, these options must occur after the -e or -exists command-line options. Those options are only valid if one of the -e or -exists command-line options is used.

The complete set of command-line options to grid-proxy-info are:

The following environment variables affect the execution of grid-proxy-info:

grid-proxy-init(1), grid-proxy-destroy(1)

grid-mapfile-add-entry - Add an entry to a gridmap file

grid-mapfile-add-entry [-help ] [-usage ] [-version ] [-versions ]

The grid-mapfile-add-entry program adds a new mapping from an X.509 distinguished name to a local POSIX user name to a gridmap file. Gridmap files are used as a simple authorization method for services such as GRAM5 or GridFTP.

The grid-mapfile-add-entry program verifies that the LOCAL-NAME is a valid user name on the system on which it was run, and that the mapping between DISTINGUISHED-NAME and LOCAL-NAME does not already exist in the gridmap file.

By default, grid-mapfile-add-entry will modify the gridmap file named by the GRIDMAP environment variable if present, or the file /etc/grid-security/grid-mapfile if not. This can be changed by the use of the if not. This can be changed by the use of the -mapfile or -f command-line options.

If the gridmap file does not exist, grid-mapfile-add-entry will create it. If it already exists, grid-mapfile-add-entry will save the current contents of the file to a new file with the string .old appended to the file name.

The full set of command-line options to grid-mapfile-add-entry are:

Add a mapping between the current user’s certificate to the current user id to a gridmap file in $HOME/.gridmap: :

Add a mapping between the a distinguished name and multiple local names:

The following environment variables affect the execution of grid-mapfile-add-entry:

The following files affect the execution of grid-mapfile-add-entry:

grid-mapfile-check-consistency(8), grid-mapfile-delete-entry(8)

grid-mapfile-check-consistency - Add an entry to a grid map file

grid-mapfile-check-consistency [-h ] [-help ] [-usage ] [-version ]

The grid-mapfile-check-consistency program performs basic checks for validity of a gridmap file. These checks include checks for existence, duplication of entries, and valid local user names. If the gridmap file is valid, grid-mapfile-check-consistency exits with a zero exit code, otherwise it exits with a non-zero exit code. In either case, it displays information about its progress as it parses and validates the gridmap file.

By default, grid-mapfile-check-consistency will check the gridmap file named by the GRIDMAP environment variable if present. If that variable is not set, it will check the file $HOME/.gridmap for non-root users if present. If that doesn’t exist or for non-root users if present. If that doesn’t exist or grid-mapfile-check-consistency is run as root, it will then check /etc/grid-security/grid-mapfile. This can be changed by the use of the . This can be changed by the use of the -mapfile or -f command-line options.

The full set of command-line options to grid-mapfile-check-consistency are:

Check that the gridmap file in /etc/grid-security is valid: is valid:

Check a gridmap file that has an invalid local user name:

The following environment variables affect the execution of grid-mapfile-check-consistency:

The following files affect the execution of grid-mapfile-check-consistency:

grid-mapfile-add-entry(8), grid-mapfile-delete-entry(8)

grid-mapfile-delete-entry - Remove entries from a gridmap file

grid-mapfile-delete-entry [-help ] [-usage ] [-version ] [-versions ]

The grid-mapfile-delete-entry program deletes mappings from a gridmap file. If both the -dn and -ln> options are specified, grid-mapfile-delete-entry removes entries which meet both criteria (remove entries mapping DISTINGUISHED-NAME to LOCAL-NAME for each LOCAL-NAME specified). If only -dn or -ln is specified all entries for that DISTINGUISHED-NAME or LOCAL-NAME are removed.

By default, grid-mapfile-delete-entry will modify the gridmap file named by the GRIDMAP environment variable if present, or the file /etc/grid-security/grid-mapfile if not. This can be changed by the use of the if not. This can be changed by the use of the -mapfile or -f command-line options.

Prior to modifying a gridmap file, grid-mapfile-delete-entry saves its current contents to a file with the string .old appended to the original file name.

The full set of command-line options to grid-mapfile-delete-entry are:

Remove all mappings for a distinguished name:

Remove the mapping between a distinguished name and a single local username:

The following environment variables affect the execution of grid-mapfile-delete-entry:

The following files affect the execution of grid-mapfile-delete-entry:

grid-mapfile-add-entry(8), grid-mapfile-check-consistency(8)

The configuration file described here was added with the package globus-gssapi-gsi-11.16 and the toolkit binary package version 6.0.1430141288.

The global security parameters for GSIC are included in the file /etc/grid-security/gsi.conf. This file contains the default values used by all GSI-enabled servers and clients. The format of the file is a sequence of lines containing a single NAME=VALUE pair, with comments beginning with the # character. All values in the default configuration file may be overridden by setting the corresponding environment variable for a particular process.

The NAME strings that are currently understood are

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

Many CAs provide tools to install configuration files with the following names in the Trusted Certificates directory:

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:

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:

Several GCT services map certificates to local unix usernames to be used with unix services. The default implementation uses a gridmap file to map the distinguished name of the identity of the client’s certificate to a local login name. Administrators can modify the contents of the gridmap file to control what certificate identities are allowed to access GCT services, as well as configure, via an environment variable, what gridmap file a particular service uses.

In addition to the identity-based mapping done via the gridmap file, administrators can configure GCT services to to use arbitrary mapping functions. These may use other criteria, such as SAML assertions, to map a certificate to a local account, or may map certificates to temporary accounts. Administrators can install different mapping implementations and configure services to use them by creating appropriate configuration files and setting environment variables.