GCT 6.2: GSI C Admin Guide

Note	The Grid Community Toolkit documentation was taken from the Globus Toolkit 6.0 documentation. As a result, there may be inaccuracies and outdated information. Please report any problems to the Grid Community Forums as GitHub issues.

GCT → GSI C → GCT 6.2: GSI C Admin Guide

Introduction

This guide contains advanced configuration information for system administrators working with GSI C. It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation.

The security tools are installed as part of the Grid Community Toolkit installation process. For instructions on basic installation of the Grid Community Toolkit, see the Grid Community Toolkit Installation Guide.

Authentication in the Grid Community Toolkit is based on X.509 certificates. This document 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.

Configuring GSI

This section describes the configuration steps required to:

Configure SSL/TLS security parameters

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, GCT 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.

Configuring Global Security Parameters

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

Table 1. GSI Configuration Values
Configuration Entry	Description	Environment Override	Default Value
`FORCE_TLS`	A flag to choose whether to force TLS or to allow SSLv3 as well. Set this to `true` to disable SSLv3, or `false` to allow either to be negotiated.	`GLOBUS_GSSAPI_FORCE_TLS`	`false`
`NAME_COMPATIBILITY`	GSSAPI Name compatibility mode when trying to determine if a host certificate is legitimate. GSI predates RFC2818, so old versions of GSI use some old, less-secure, practices. The possible values are described in GLOBUS_GSSAPI_NAME_COMPATIBILITY	`GLOBUS_GSSAPI_NAME_COMPATIBILITY`	`HYBRID`
`CIPHERS`	OpenSSL Cipher List. This is an preference-ordered list of OpenSSL cipher names. See the OpenSSL cipher documentation for information on the syntax of this string.	`GLOBUS_GSSAPI_CIPHERS`	`HIGH`

Configuring GCT to Trust a Particular Certificate Authority

Trusted certificates directory

The GCT 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 below and exists either on a per-machine or on a per-installation basis.

X509_CERT_DIR is the environment variable 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 looked for in the following order: . value of the X509_CERT_DIR environment variable

$HOME/.globus/certificates
/etc/grid-security/certificates exists exists
$GLOBUS_LOCATION/share/certificates

Trusted certificates files

The following two files must exist in the directory for each trusted CA:

cert_hash.0: The trusted CA Certificate.
cert_hash.signing_policy: A configuration file defining the distinguished names of certificates signed by the CA.

GCT 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.

Hash of the CA certificate

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:

openssl x509 -hash -noout < ca_certificate

Creating a signing policy by hand

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.

Repository of CAs

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

Configuring GCT to Create Appropriate Certificate Requests

The grid-cert-request command, which is used to create certificates, uses the following 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 with the following names in the Trusted Certificates directory:

globus-user-ssl.conf.cert_hash
globus-host-ssl.conf.cert_hash
grid_security.conf.cert_hash
directions.cert_hash

Creating a certificate request for a specific CA

The command:

grid-cert-request -ca cert_hash

will create a certificate request based on the specified CA’s configuration files.

Listing available CAs

The command:

grid-cert-request -ca

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

Specifying a default CA for certificate requests

The default CA is the CA that will be used for certificate requests if grid-cert-request is invoked without the -ca flag.

You can specify a default CA by invoking the grid-default-ca command (follow the link for examples of using the command).

`directions` file file

The directions file may contain specific directions on how to use the CA. There are three types of printed messages: 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: 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.

Requesting Service Certificates

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:

GRID_SECURITY/service_name/service_namecert.pem: An empty file. When you receive your actual service certificate from your CA, you should place it in this file.
GRID_SECURITY/service_name/service_namecert_request.pem: The certificate request, which you should send to your CA.
GRID_SECURITY/service_name/service_namekey.pem: 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

Configuring Credential Mappings

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.

Configuring Identity Mappings Using `gridmap` Files Files

Gridmap files contain a database of entries mapping distinguished names to local user names. These may be manipulated by using the following tools.

Adding an entry to a gridmap file

To add an entry to the gridmap file, run:

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

Deleting an entry from a gridmap file

To delete an entry from the gridmap file, run:

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

Checking consistency of a gridmap file

To check the consistency of the gridmap file, run

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

Configuring per-service gridmap files

To configure a service to use a particular gridmap file, set the GRIDMAP variable in the service’s environment to the path of the gridmap file. In this way, you can grant different access rights to different certificate identities on a per-service basis by setting the GRIDMAP variable in different service environments.

You can use tools described above to operate on different gridmap files by either setting the GRIDMAP environment variable prior to invoking them, or by using the -mapfile command-line option.

For reference, the GSI C code looks for the gridmap in these locations:

GRIDMAP environment variable: Default
/etc/grid-security/grid-mapfile: For services running as root. </simpara> HOME/.gridmap: For services not running as root.

Gridmap formats

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.

For more detailed information about the gridmap file see the file description and grammars on dev.globus.org.

Configuring Alternate Credential Mappings

To use an alternative credential mapping, you create a gsi-authz.conf file containing information about how the mapping functions are called from the authorization library. file containing information about how the mapping functions are called from the authorization library.

To configure a per-service authorization configuration file, set the GSI_AUTHZ_CONF variable to the path to the configuration file in the environment of the service.

For reference, the GSI C code looks for the authorization configuration file in these locations (in the given order):

GSI_AUTHZ_CONF environment variable
/etc/grid-security/gsi-authz.conf
GLOBUS_LOCATION/etc/gsi-authz.conf
HOME/.gsi-authz.conf

Callout File Format

The authorization file defines a set of callouts, one per line. Each callout is defined by an abstract type, library, and symbol separated by whitespace. Comments begin with the # character and continue to the end of line.

abstract type: Type of the callout: globus_mapping is used for credential mapping callouts
library: Path to the shared object containing the callout implementation. The library name may be a literal filename, or a partial filename to which the compilation flavor of the service is appended to the filename before its extension.
symbol: The exported symbol containing the entry point to the callout implementation.

Here is a sample gsi-authz.conf file that configures a file that configures a globus_mapping callout to use the globus_gridmap_callout function in the /usr/local/globus/lib/libglobus_gridmap_callout shared object: shared object:

# abstract-type     library                                            symbol

globus_mapping      /opt/globus/lib/libglobus_gridmap_callout globus_gridmap_callout

GSI File Permissions Requirements

End Entity Certificate (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

Testing

There is no content available at this time.

Security Considerations

Security considerations for GSI C

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.

Note

The string ANYTHING matches only the name of the host and not domain components. This means that hostname.edu will not match hostname-foo.sub.edu, but will match host-foo.edu.

If a host was set up to accept hostname-1.edu, it will not accept hostname-ANYTHING.edu but will accept hostname.edu. That is, only one of the names being compared may contain the hyphen character in the host name.

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

Debugging

Logging

N/A

Troubleshooting

Credential Troubleshooting

Credential Errors

The following are some common problems that may cause clients or servers to report that credentials are invalid:

Table 2. Credential Errors
Error Code	Definition	Possible Solutions
`Your proxy credential may have expired`	Your proxy credential may have expired.	Use grid-proxy-info to check whether the proxy credential has actually expired. If it has, generate a new proxy with grid-proxy-init.
`The system clock on either the local or remote system is wrong.`	This may cause the server or client to conclude that a credential has expired.	Check the system clocks on the local and remote system.
`Your end-user certificate may have expired`	Your end-user certificate may have expired	Use grid-cert-info to check your certificate’s expiration date. If it has expired, follow your CA’s procedures to get a new one.
`The permissions may be wrong on your proxy file`	If the permissions on your proxy file are too lax (for example, if others can read your proxy file), Grid Community Toolkit clients will not use that file to authenticate.	You can "fix" this problem by changing the permissions on the file or by destroying it (with grid-proxy-destroy) and creating a new one (with grid-proxy-init). [IMPORTANT] However, it is still possible that someone else has made a copy of that file during the time that the permissions were wrong. In that case, they will be able to impersonate you until the proxy file expires or your permissions or end-user certificate are revoked, whichever happens first.
`The permissions may be wrong on your private key file`	If the permissions on your end user certificate private key file are too lax (for example, if others can read the file), grid-proxy-init will refuse to create a proxy certificate.	You can "fix" this by changing the permissions on the private key file. [IMPORTANT] However, you will still have a much more serious problem: it is possible that someone has made a copy of your private key file. Although this file is encrypted, it is possible that someone will be able to decrypt the private key, at which point they will be able to impersonate you as long as your end user certificate is valid. You should contact your CA to have your end-user certificate revoked and get a new one.
`The remote system may not trust your CA`	The remote system may not trust your CA	Verify that the remote system is configured to trust the CA that issued your end-entity certificate. See link:admin/install/index.html for details.
`You may not trust the remote system’s CA`	You may not trust the remote system’s CA	Verify that your system is configured to trust the remote CA (or that your environment is set up to trust the remote CA). See admin/install/index.html for details.
`There may be something wrong with the remote service’s credentials`	There may be something wrong with the remote service’s credentials	It is sometimes difficult to distinguish between errors reported by the remote service regarding your credentials and errors reported by the client interface regarding the remote service’s credentials. If you cannot find anything wrong with your credentials, check for the same conditions on the remote system (or ask a remote administrator to do so) .

Some tools to validate certificate setup

grid-cert-diagnostics

The grid-cert-diagnostics program checks prints diagnostics about the user’s certificates, and host security environment.

%  grid-cert-diagnostics -p

Check that the user certificate is valid

openssl verify -CApath /etc/grid-security/certificates
  -purpose sslclient ~/.globus/usercert.pem

Connect to the server using s_client

openssl s_client -ssl3 -cert ~/.globus/usercert.pem -key
  ~/.globus/userkey.pem -CApath /etc/grid-security/certificates
  -connect <host:port>

Here <host:port> denotes the server and port you connect to.

If it prints an error and puts you back at the command prompt, then it typically means that the server has closed the connection, i.e. that the server was not happy with the client’s certificate and verification. Check the SSL log on the server.

If the command "hangs" then it has actually opened a telnet style (but secure) socket, and you can "talk" to the server.

You should be able to scroll up and see the subject names of the server’s verification chain:

depth=2 /DC=net/DC=ES/O=ESnet/OU=Certificate Authorities/CN=ESnet Root CA 1
verify return:1
depth=1 /DC=org/DC=DOEGrids/OU=Certificate Authorities/CN=DOEGrids CA 1
verify return:1
depth=0 /DC=org/DC=doegrids/OU=Services/CN=wiggum.mcs.anl.gov
verify return:1

In this case, there were no errors. Errors would give you an extra line next to the subject name of the certificate that caused the error.

Check that the server certificate is valid

Requires root login on server:

    openssl verify -CApath /etc/grid-security/certificates -purpose sslserver
     /etc/grid-security/hostcert.pem

Grid map Troubleshooting

Grid map errors

The following are some common problems that may cause clients or servers to report that user are not authorized:

Table 3. Gridmap Errors
Error Code	Definition	Possible Solutions
`The content of the grid map file does not conform to the expected format`	The content of the grid map file does not conform to the expected format	Run `grid-mapfile-check-consistency` to make sure that your gridmap file conforms to the expected format.
`The grid map file does not contain a entry for your DN`	The grid map file does not contain a entry for your DN	Use `grid-mapfile-add-entry` to add the relevant entry.