GT4: Security: Pre-WS Authentication & Authorization Admin Guide

1. Introduction

This guide contains advanced configuration information for system administrators working with Pre-WS Authentication & Authorization. It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation.

[Important]Important

This information is in addition to the basic Globus Toolkit prerequisite, overview, installation, security configuration instructions in the GT 4.0 System Administrator's Guide. Read through this guide before continuing!

2. Building and Installing

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

3. Configuring

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.

3.1. Configuring Globus to Trust a Particular Certificate Authority

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

cert_hash.0 The trusted CA certificate.
cert_hash.signing_policy 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.

In GT 4.0.x releases, up to GT 4.0.6 release, Java-based components ignore the signing policy file and will honor all valid certificates issued by trusted CAs. Since GT 4.0.7 release, Java components enforce signing policy as described in Java CoG Release Notes.

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.

3.2. Configuring Globus to Create Appropriate Certificate Requests

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

3.3. 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:

Table 3. Certificate request 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

3.4. Specifying Identity Mapping Information

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" \
        -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:

  1. If the GRIDMAP environment variable is set, the gridmap file location is the value of the environment variable.
  2. 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.

3.5. Configuring Certificate Revocation Lists (CRLs)

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.

3.5.1. CRL Filename

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.

3.5.2. CRL Expiration

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.

3.5.3. CRL Format

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

3.6. GSI File Permissions Requirements

  • 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

4. Deploying

This section is not applicable.

5. Testing

There is no content available at this time.

6. Security Considerations

During host authorization, the toolkit treats DNs "hostname-*.edu" as equivalent to "hostname.edu". This means that if a service was setup to do host authorization and hence accept the certificate "hostname.edu", it would also accept certificates with DNs "hostname-*.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]Note

The wildcard character "*" matches only the name of the host and not the domain components. This means that "hostname.edu" will not match "hostname-foo.sub.edu" but will match "host-foo.edu".

[Note]Note

If a host was set up to accept "hostname-1.edu", it will not accept any of "hostname-*.edu".

A bug has been opened to see if this feature needs to be modfiied.

7. Troubleshooting

7.1. Credential Errors

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

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

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

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

7.1.4. 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), Globus 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). 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.

7.1.5. 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; however, you will still have a much more serious problem: it's 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.

7.1.6. 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 the Administrator's Guide for details.

7.1.7. 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 the Administrator's Guide for details.

7.1.8. 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 can't find anything wrong with your credentials, check for the same conditions (or ask a remote administrator to do so) on the remote system.

7.2. Some tools to validate certificate setup

7.2.1. Check that the user certificate is valid

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

7.2.2. Connect to the server using s_clien

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

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

7.3. Grid map errors

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

7.3.1. The content of the grid map file does not conform to the expected format

Use grid-mapfile-check-consistency to make sure that your gridmap conforms to the expected format.

7.3.2. The grid map file does not contain a entry for your DN

Use grid-mapfile-add-entry to add the relevant entry.