Software Links

Usage Statistics
Release Notes
Versioning
Downloads
Advisories
Licenses
CVS & Dev Tools

Getting Started

Globus Is Modular!
Installing GT
Quickstart
Platform Notes
GT Developer's Guide
GT User's Guide
Migrating Guides

Components

Data Mgt: GridFTP; RLS
Execution Mgt: GRAM5
Security: GSI C; MyProxy; GSI-OpenSSH; SimpleCA
Common Runtime: XIO; C Common Libs

Reference

Coding Guidelines
API docs
GT Commands
Public Interfaces
Glossary

GT5: Security: GSI C User's Guide

Introduction

Authentication in the Globus Toolkit is based on X.509 certificates. This document describes how to acquire and use the certificates that you will need to authenticate yourself to Globus services.

Table of Contents

1. Usage scenarios

1. Basic procedure for using GSI C

GSI Commands

globus-update-certificate-dir - Update symlinks in the trusted CA directory
grid-cert-diagnostics - Print diagnostic information about certificates and keys
grid-cert-info - Display information about a certificate
grid-cert-request - Generate a X.509 certificate request and corresponding private key
grid-default-ca - Select default CA for certificate requests
grid-change-pass-phrase - Change the passphrase of a private key
grid-proxy-init - Generate a new proxy certificate
grid-proxy-destroy - Destroy the default proxy certificate
grid-proxy-info - Display information about a proxy certificate
grid-mapfile-add-entry - Add an entry to a gridmap file
grid-mapfile-check-consistency - Add an entry to a grid map file
grid-mapfile-delete-entry - Remove entries from a gridmap file

2. Troubleshooting

1. Credential Troubleshooting

1.1. Credential Errors

1.2. Some tools to validate certificate setup

1.2.1. grid-cert-diagnostics
1.2.2. Check that the user certificate is valid
1.2.3. Connect to the server using s_client
1.2.4. Check that the server certificate is valid

2. Grid map Troubleshooting

2.1. Grid map errors

Glossary

Chapter 1. Usage scenarios

Table of Contents

1. Basic procedure for using GSI C

1. Basic procedure for using GSI C

In most cases, an individual will do the following:

Acquire a user certificate from a certification authority (CA) with grid-cert-request. This certificate will typically be valid for a year or more and will be stored in a file in the individual's home directory.
It is important to keep in mind when your cert will expire - after your user certificate expires, you may not be able to use secure services in GT!
Use the end-user certificate to create a proxy certificate using grid-proxy-init. This will be used to authenticate the individual to grid services. Proxy certificates typically have a much shorter lifetime than end-user certificates (usually 12 hours). Once your proxy certificate expires, simply rerun grid-proxy-init.

GSI Commands

Table of Contents

globus-update-certificate-dir - Update symlinks in the trusted CA directory
grid-cert-diagnostics - Print diagnostic information about certificates and keys
grid-cert-info - Display information about a certificate
grid-cert-request - Generate a X.509 certificate request and corresponding private key
grid-default-ca - Select default CA for certificate requests
grid-change-pass-phrase - Change the passphrase of a private key
grid-proxy-init - Generate a new proxy certificate
grid-proxy-destroy - Destroy the default proxy certificate
grid-proxy-info - Display information about a proxy certificate
grid-mapfile-add-entry - Add an entry to a gridmap file
grid-mapfile-check-consistency - Add an entry to a grid map file
grid-mapfile-delete-entry - Remove entries from a gridmap file

Name

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

Synopsis

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

Description

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.

	Note
To run globus-update-certificate-dir on Linux, modify that script so that the first line is #! /usr/bin/env perl instead of #! /usr/bin/env perl -w

Note

To run globus-update-certificate-dir on Linux, modify that script so that the first line is

#! /usr/bin/env perl

instead of

#! /usr/bin/env perl -w

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

-help: Display a help message to standard output and exit
-d DIRECTORY: Create links in the trusted CA directory DIRECTORY instead of using the default search path.

Environment

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

X509_CERT_DIR: Default trusted certificate directory.
HOME: Path to the current user's home directory.
GLOBUS_LOCATION: Path to the Globus installation.

Name

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

Synopsis

grid-cert-diagnostics [-h] | [-help] [-p]

Description

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:

-h, -help: Display a help message and exit.
-p: Display information about the personal certificate and key that is the current user's default credential.

Examples

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.

% grid-cert-diagnostics

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... found
    WARNING: If the cog.properties file contains security properties, 
             Java apps will ignore the security paths described in the GSI
             documentation

Checking trusted certificates...
================================
Getting trusted certificate list...
Checking CA file /etc/grid-security/certificates/1c4f4c48.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/1c3f2ca8.0"... ok
Checking CA file /etc/grid-security/certificates/9d8788eb.0... ok
Verifying certificate chain for "/etc/grid-security/certificates/9d8753eb.0"... failed
    globus_credential: Error verifying credential: Failed to verify credential
    globus_gsi_callback_module: Could not verify credential
    globus_gsi_callback_module: The certificate has expired:
    Credential with subject: /DC=org/DC=example/OU=grid/CN=CA has expired.

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

% grid-cert-diagnostics -p

Checking Environment Variables
==============================
Checking if X509_CERT_DIR is set... no
Checking if X509_USER_CERT is set... no
Checking if X509_USER_KEY is set... no
Checking if X509_USER_PROXY is set... no

Checking Security Directories
=======================
Determining trusted cert path... /etc/grid-security/certificates
Checking for cog.properties... not found

Checking Default Credentials
==============================
Determining certificate and key file names... ok
Certificate Path: "/home/juser/.globus/usercert.pem"
Key Path: "/home/juser/.globus/userkey.pem"
Reading certificate... ok
Reading private key...
ok
Checking Certificate Subject...
"/O=Grid/OU=Example/OU=User/CN=Joe User"
Checking cert... ok
Checking key... ok
Checking that certificate contains an RSA key... ok
Checking that private key is an RSA key... ok
Checking that public and private keys have the same modulus... failed
Private key modulus: D294849E37F048C3B5ACEEF2CCDF97D88B679C361E29D5CB5
219C3E948F3E530CFC609489759E1D751F0ACFF0515A614276A0F4C11A57D92D7165B8
FA64E3140155DE448D45C182F4657DA13EDA288423F5B9D169DFF3822EFD81EB2E6403
CE3CB4CCF96B65284D92592BB1673A18354DA241B9AFD7F494E54F63A93E15DCAE2
Public key modulus : C002C7B329B13BFA87BAF214EACE3DC3D490165ACEB791790
600708C544175D9193C9BAC5AED03B7CB49BB6AE6D29B7E635FAC751E9A6D1CEA98022
6F1B63002902D6623A319E4682E7BFB0968DCE962CF218AAD95FAAD6A0BA5C42AA9AAF
7FDD32B37C6E2B2FF0E311310AA55FFB9EAFDF5B995C7D9EEAD8D5D81F3531E0AE5
Certificate and and private key don't match

Name

grid-cert-info — Display information about a certificate

Synopsis

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

Description

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:

-help, -usage: Display the command-line options to grid-cert-info and exit.
-version, -versions: Display the version number of the grid-cert-info command. The second form includes more details.
-file CERTIFICATE-FILE: Display information about the first certificate contained in the file named by CERTIFICATE-FILE instead of the default user certificate.
-rfc2253: Display X.509 distinguished names using the string representation defined in RFC 2253 instead of the default OpenSSL oneline format.
-all: Display the text representation of the entire certificate in addition to any other facts requested by command-line options. This is the default if no fact-specific command-line options are used.
-subject, -s: Display the subject name of the X.509 certificate.
-issuer, -i: Display the issuer name of the X.509 certificate.
-issuerhash, -ih: Display the default hash of the issuer name of the X.509 certificate. This can be used to locate which CA certificate in the trusted certificate directory issued the certifcate being inspected.
-startdate, -sd: Display a string representation of the date and time when the certificate is valid from. This is displayed in the format used by the OpenSSL x509 command.
-enddate, -dd: Display a string representation of the date and time when the certificate is valid until. This is displayed in the format used by the OpenSSL x509 command.

Examples

Display the validity times for the default certificate

% grid-cert-info -sd -ed
Aug 31 12:33:47 2009 GMT
Aug 31 12:33:47 2010 GMT

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

% grid-cert-info -sd -ed -f /etc/grid-security/hostcert.pem
Jan 21 12:24:48 2003 GMT
Jul 15 11:30:57 2020 GMT

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

% grid-cert-info -subject
/DC=org/DC=example/DC=grid/CN=Joe User
% grid-cert-info -subject -rfc2253
CN=Joe User,DC=grid,DC=example,DC=org

Environment Variables

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

X509_USER_CERT: Path to the default certificate file to inspect.

Name

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

Synopsis

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

grid-cert-request -host FQDN [-service SERVICE] [-dns FQDN...] [-ip IP-ADDRESS...]
[-dir DIRECTORY] [-prefix PREFIX]
[-ca [HASH]] [-verbose] [ -interactive | -int ] [-force]

Description

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 /etc/grid-security. This can be overridden by using the -dir command-line option.

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

-help, -h, -?, -usage: Display the command-line options to grid-cert-request and exit.
-version, -versions: Display the version number of the grid-cert-request command. The second form includes more details.
-cn NAME, -commonname NAME: Create a certificate request with the common name component of the subject set to NAME. This is used to create user identity certificates.
-dir DIRECTORY: Write the certificate request and key to files in the directory specified by DIRECTORY.
-prefix PREFIX: Use the string PREFIX as the base name of the certificate, certificate_request, and key files instead of the default. For a user certificate request, this would mean creating files $HOME/.globus/PREFIXcert_request.pem, $HOME/.globus/PREFIXcert.pem, and $HOME/.globus/PREFIXkey.pem.
-ca CA-HASH: Use the certificate request configuration for the CA with the name hash CA-HASH instead of the default CA chosen by running grid-default-ca.
-verbose: Keep the output from the OpenSSL certificate request command visible after it completes, instead of clearing the screen..
-interactive, -int: Prompt for each component of the subject name of the request, instead of generating the common name from other command-line options. Note that CAs may not sign certificates for subject names that don't match their signing policies.
-force: Overwrite any existing certificate request and private key with a new one.
-nopw, -nodes, -nopassphrase: Create an unencrypted private key for the certificate instead of prompting for a passphrase. This is the default behavior for host or service certificates, but not recommended for user certificates.
-host FQDN: Create a certificate request for use on a particular host. This option also causes the private key assoicated with the certificate request to be unencrypted. The FQDN argument to this option should be the fully qualified domain name of the host that will use this certificate. The subject name of the certificate will be derived from the FQDN and the service option if specified by the -service command-line option. If the host for the certificate has multiple names, then use either the -dns or -ip command-line options to add alternate names or addresses to the certificates.
-service SERVICE: Create a certificate request for a particular service on a host. The subject name of the certificate will be derived from the FQDN passed as the argument to the -host command-line option and the SERVICE string.
-dns FQDN,...: Create a certificate request containing a subjectAltName extension containing one or more host names. This is used when a certificate may be used by multiple virtual servers or if a host has different names when contacted within or outside a private network. Multiple DNS names can be included in the extension by separating then with a comma.
-ip IP-ADDRESS,...: Create a certificate request containing a subjectAltName extension containing the IP addresses named by the IP-ADDRESS strings. This is used when a certificate may be used by services listening on multiple networks. Multiple IP addresses can be included in the extension by separating then with a comma.

Examples

Create a user certificate request:

%  grid-cert-request
A certificate request and private key is being created.
You will be asked to enter a PEM pass phrase.
This pass phrase is akin to your account password, 
and is used to protect your key file.
If you forget your pass phrase, you will need to
obtain a new certificate.
A private key and a certificate request has been generated with the subject:

/O=org/OU=example/OU=grid/CN=Joe User

If the CN=Joe User is not appropriate, rerun this
script with the -force -cn "Common Name" options.

Your private key is stored in /home/juser/.globus/userkey.pem
Your request is stored in /home/juser/.globus/usercert_request.pem

Please e-mail the request to the Example CA ca@grid.example.org
You may use a command similar to the following:

  cat /home/juser/.globus/usercert_request.pem | mail ca@grid.example.org

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Example CA at ca@grid.example.org

Create a host certificate for a host with two names.

%  grid-cert-request -host grid.example.org -dns grid.example.org,grid-internal.example.org

A private host key and a certificate request has been generated
with the subject:

/O=org/OU=example/OU=grid/CN=host/grid.example.org

----------------------------------------------------------

The private key is stored in /etc/grid-security/hostkey.pem
The request is stored in /etc/grid-security/hostcert_request.pem

Please e-mail the request to the Example CA ca@grid.example.org
You may use a command similar to the following:

 cat /etc/grid-security/hostcert_request.pem | mail ca@grid.example.org

Only use the above if this machine can send AND receive e-mail. if not, please
mail using some other method.

Your certificate will be mailed to you within two working days.
If you receive no response, contact Example CA at
ca@grid.example.org

Environment Variables

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

X509_CERT_DIR: Path to the directory containing SSL configuration files for generating certificate requests.
GRID_SECURITY_DIR: Path to the directory containing SSL configuration files for generating certificate requests. This value is used if X509_CERT_DIR is not set.
GLOBUS_LOCATION: Path to the directory containing the Globus Toolkit. This is searched if neither the X509_CERT_DIR nor the GRID_SECURITY_DIR environment variables are set.

Files

$HOME/.globus/usercert_request.pem: Default path to write a user certificate request.
$HOME/.globus/usercert.pem: Default path to write a user certificate.
$HOME/.globus/userkey.pem: Default path to write a user private key.
/etc/grid-security/hostcert_request.pem: Default path to write a host certificate request.
/etc/grid-security/hostcert.pem: Default path to write a host certificate.
/etc/grid-security/hostkey.pem: Default path to write a host private key.
TRUSTED-CERT-DIR/globus-user-ssl.conf, TRUSTED-CERT-DIR/globus-user-ssl.conf.CA-HASH: SSL configuration file for requesting a user certificate. The first form is the default location, the second form is used when the -ca command-line option is specified.
TRUSTED-CERT-DIR/globus-host-ssl.conf, TRUSTED-CERT-DIR/globus-host-ssl.conf.CA-HASH: SSL configuration file for requesting a host or service certificate. The first form is the default location, the second form is used when the -ca command-line option is specified.

Name

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

Synopsis

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

grid-default-ca -list [-dir CA-DIRECTORY]

grid-default-ca [-ca CA-HASH] [-dir CA-DIRECTORY]

Description

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 $GLOBUS_LOCATION/share/certificates.

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

-help, -h, -usage, -u: Display the command-line options to grid-default-ca and exit.
-version, -versions: Display the version number of the grid-default-ca command. The second form includes more details.
-dir CA-DIRECTORY: Use the trusted certificate directory named by CA-DIRECTORY instead of the default.
-list: Instead of changing the default CA, print out a list of all available CA certificates in the trusted certificate directory
-ca CA-HASH: Set the default CA without displaying the list of choices or prompting. The CA file named by CA-HASH must exist.

Examples

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

% grid-default-ca | grep Example
15) cd1186ff -  /DC=org/DC=Example/DC=Grid/CN=Example CA

Choose that CA as the default:

% grid-default-ca -ca cd1186ff

setting the default CA to: /DC=org/DC=Example/DC=Grid/CN=Example CA

linking /etc/grid-security/certificates/grid-security.conf.cd1186ff to
        /etc/grid-security/certificates/grid-security.conf

linking /etc/grid-security/certificates/grid-host-ssl.conf.cd1186ff  to
        /etc/grid-security/certificates/grid-host-ssl.conf

linking /etc/grid-security/certificates/grid-user-ssl.conf.cd1186ff  to
        /etc/grid-security/certificates/grid-user-ssl.conf

...done.

Environment Variables

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

GRID_SECURITY_DIRECTORY: Path to the default trusted certificate directory.
X509_CERT_DIR: Path to the default trusted certificate directory.
GLOBUS_LOCATION: Path to the Globus Toolkit installation directory.

Bugs

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.

Name

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

Synopsis

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

grid-change-pass-phrase [-file PRIVATE-KEY]

Description

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 $HOME/.globus/usercred.p12 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:

-help, -usage: Display the command-line options to grid-change-pass-phrase and exit.
-version, -versions: Display the version number of the grid-change-pass-phrase command. The second form includes more details.
-file PRIVATE-KEY: Change the passphrase of the private key named by PRIVATE-KEY instead of the default.

Examples

Change the passphrase of the default private key:

% grid-change-pass-phrase 

Enter pass phrase for /home/juser/.globus/userkey.pem:
writing RSA key
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:

Environment Variables

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

X509_USER_KEY: Path to the default private key file.

Name

grid-proxy-init — Generate a new proxy certificate

Synopsis

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

grid-proxy-init [-debug] [-q] [-verify]
[[-valid HOURS:MINUTES] | [-hours HOURS]] [-cert CERTFILE] [-key KEYFILE] [-certdir CERTDIR] [-out PROXYPATH] [-bits BITS]
[-policy POLICYFILE]
[[-pl POLICY-OID] | [-policy-language POLICY-OID]] [-path-length MAXIMUM] [-pwstdin] [-limited] [-independent] [[-draft] | [-old] | [-rfc]]

Description

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.

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:

-help, -usage: Display the command-line options to grid-proxy-init.
-version: Display the version number of the grid-proxy-init command
-debug: Display information about the path to the certificate and key used to generate the proxy certificate, the path to the trusted certificate directory, and verbose error messages
-q: Suppress all output from grid-proxy-init except for passphrase prompts.
-verify: Perform certificate chain validity checks on the generated proxy.
-valid HOURS:MINUTES, -hours HOURS: Create a certificate that is valid for HOURS hours and MINUTES minutes. If not specified, the default of twelve hours and no minutes is used.
-cert CERTFILE, -key KEYFILE: Create a proxy certificate signed by the certificate located in CERTFILE using the key located in KEYFILE. If not specified the default certificate and key will be used. This overrides the values of environment variables described below.
-certdir CERTDIR: Search CERTDIR for trusted certificates if verifying the proxy certificate. If not specified, the default trusted certificate search path is used. This overrides the value of the X509_CERT_DIR environment variable
-out PROXYPATH: Write the generated proxy certificate file to PROXYPATH instead of the default path of /tmp/x509up_uUID.
-bits BITS: When creating the proxy certificate, use a BITS bit key instead of the default 512 bit keys.
-policy POLICYFILE: Add the certificate policy data described in POLICYFILE as the ProxyCertInfo X.509 extension to the generated proxy certificate.
-pl POLICY-OID, -policy-language POLICY-OID: Set the policy language identifier of the policy data specified by the -policy command-line option to the oid specified by the POLICY-OID string.
-path-length MAXIMUM: Set the maximum length of the chain of proxies that can be created by the generated proxy to MAXIMUM. If not set, the default of an unlimited proxy chain length is used.
-pwstdin: Read the private key's passphrase from stdin instead of reading input from the controlling tty. This is useful when scripting grid-proxy-init.
-limited: Create a limited proxy. Limited proxies are generally refused by process-creating services, but may be used to authorize with other services.
-independent: Create an independent proxy. An independent proxy is not treated as an impersonation proxy but as a separate identity for authorization purposes.
-draft: Create a IETF draft proxy instead of the default RFC 3280-compliant proxy. This type of proxy uses a non-standard proxy policy identifier. This might be useful for authenticating with older versions of the Globus Toolkit.
-old: Create a legacy proxy instead of the default RFC 3280-compliant proxy. This type of proxy uses a non-standard method of indicating that the certificate is a proxy and whether it is limited. This might be useful for authenticating with older versions of the Globus Toolkit.
-rfc: Create an RFC 3820-compliant proxy certificate. This is the default for this version of grid-proxy-init.

Examples

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

% grid-proxy-init
Your identity: /DC=org/DC=example/CN=Joe User
Enter GRID pass phrase for this identity:
Creating proxy .................................. Done
Your proxy is valid until: Thu Mar 18 03:48:05 2010

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:

% grid-proxy-init -hours 8 -bits 1024
Your identity: /DC=org/DC=example/CN=Joe User
Enter GRID pass phrase for this identity:
Creating proxy .................................. Done
Your proxy is valid until: Thu Mar 17 23:48:05 2010

Environment Variables

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

X509_USER_CERT: Path to the certificate to use as issuer of the new proxy.
X509_USER_KEY: Path to the key to use to sign the new proxy.
X509_CERT_DIR: Path to the directory containing trusted certifiate certificates and signing policies.

Files

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

$HOME/.globus/usercert.pem: Default path to the certificate to use as issuer of the new proxy.
$HOME/.globus/userkey.pem: Default path to the key to use to sign the new proxy.

Compatibility

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

Name

grid-proxy-destroy — Destroy the default proxy certificate

Synopsis

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

grid-proxy-destroy [-debug] [-dryrun] [-default] [-all] [--] [FILENAME...]

Description

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

-help, -usage: Display the command-line options to grid-proxy-destroy.
-version: Display the version number of the grid-proxy-destroy command
-debug: Display verbose error messages.
-dryrun: Do not remove the proxy, but display the path of the files that would have been removed, or the directory where they would have been removed from if the -all command-line option is used.
-default: Remove the default proxy in addition to the files included on the command-line. Only needed if other paths are included on the command-line.
-all: Remove the default proxy and all delegated proxies in the temporary file directory.

Environment Variables

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

X509_USER_PROXY: Path to the default user proxy.

Name

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

Synopsis

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

grid-proxy-info [[-subject] | [-s]]
[[-issuer] | [-i]]
[-identity] [-type] [-timeleft] [-strength] [-all] [-text] [-path] [-rfc2253]
[{ -exists | -e }
[[-valid HOURS:MINUTES] | [-v HOURS:MINUTES]]
[[-hours HOURS] | [-h HOURS]]
[[-bits BITS] | [-b BITS]]]

Description

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:

-help, -usage: Display the command-line options to grid-proxy-info.
-version: Display the version number of the grid-proxy-info command
-debug: Display verbose error messages.
-file PROXYFILE, -f PROXYFILE: Read the proxy located in the file PROXYFILE instead of using the default proxy.
-subject, -s: Display the proxy certificate's subject distinguished name.
-issuer, -i: Display the proxy certificate issuer's distinguished name.
-identity: Display the proxy certificate's identity. For non-independent proxies, the identity is the subject of the certificate which issued the first proxy in the proxy chain.
-type: Display the type of proxy certificate. The type string includes the format ("legacy", "draft", or RFC 3280 compliant), identity type ("impersonation" or "independent"), and policy ("limited" or "full"). See grid-proxy-init(1) for information about how to create different types of proxies.
-timeleft: Display the number of seconds remaining until the proxy certificate expires.
-strength: Display the strength (in bits) of the key associated with the proxy certificate.
-all: Display the default information for the proxy when also using the -e or -exists command-line option.
-text: Display the proxy certificate contents to standard output, including policy information, issuer, public key, and modulus.
-path: Display the path to the file containing the default proxy certificate.
-rfc2253: Display distinguished names for the subject, issuer, and identity using the string representation described in RFC 2253, instead of the legacy format.
-exists, -e: Perform an existence and validity check for the proxy. If a valid proxy exists and matches the criteria described by other command-line options (if any), exit with 0; otherwise, exit with 1. This option must be before other validity check predicate in the command-line options. If this option is specified, the output of the default facts about the proxy is disabled. Use the -all option to have the information displayed as well as the exit code set.
-valid HOURS:MINUTES, -v HOURS:MINUTES, -hours HOURS, -h HOURS: Check that the proxy certificate is valid for at least HOURS hours and MINUTES minutes. If it is not, grid-proxy-info will exit with exit code 1.
-bits BITS, -b BITS: Check that the proxy certificate key strength is at least BITS bits.

Environment Variables

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

X509_USER_PROXY: Path to the default user proxy.

Name

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

Synopsis

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

grid-mapfile-add-entry {-dn DISTINGUISHED-NAME} {-ln LOCAL-NAME... }
[[-d] | [-dryrun]]
[[-mapfile MAPFILE] | [-f MAPFILE]]

Description

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

-help, -usage: Display the command-line options to grid-mapfile-add-entry.
-version, -versions: Display the version number of the grid-mapfile-add-entry command. The second form includes more details.
-dn DISTINGUISHED-NAME: The X.509 distinguished name to add a mapping for. The name should be in OpenSSL's oneline format.
-ln LOCAL-NAME...: The POSIX user name to map the distinguished name to. This name must be a valid username. Add multiple LOCAL-NAME strings after the -ln command-line option. If any of the local names are invalid, no changes will be made to the gridmap file. Note that if multiple occurances of the -ln command-line option are present, only the the last one will be added.
-d, -dryrun: Verify local names and display diagnostics about what would be added to the gridmap file, but don't actually modify the file.
-mapfile MAPFILE, -f MAPFILE: Modify the gridmap file named by MAPFILE instead of the default.

Examples

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

% grid-mapfile-add-entry -f $HOME/.gridmap -dn "`grid-cert-info -subject`" -ln "`id -un`"
Modifying /home/juser/.gridmap ...
/home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
New entry:
"/DC=org/DC=example/DC=grid/CN=Joe User" juser
(1) entry added

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

% grid-mapfile-add-entry -dn "/DC=org/DC=example/DC=grid/CN=Joe User" juser" local1 local2
Modifying /home/juser/.gridmap ...
/home/juser/.gridmap does not exist... Attempting to create /home/juser/.gridmap
New entry:
"/DC=org/DC=example/DC=grid/CN=Joe User" local1,local2
(1) entry added

Environment Variables

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

GRIDMAP: Path to the default gridmap to modify.

Files

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

/etc/grid-security/grid-mapfile: Path to the default gridmap to modify if GRIDMAP environment variable is not set.

Name

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

Synopsis

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

grid-mapfile-check-consistency [-mapfile MAPFILE] | [-f MAPFILE]

Description

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 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 -mapfile or -f command-line options.

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

-help, -h, -usage: Display the command-line options to grid-mapfile-check-consistency.
-version: Display the version number of the grid-mapfile-check-consistency command.
-mapfile MAPFILE, -f MAPFILE: Check the gridmap file named by MAPFILE instead of the default.

Examples

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

% grid-mapfile-check-consistency -f /etc/grid-security/grid-mapfile
Checking /etc/grid-security/grid-mapfile
Verifying grid mapfile existence...OK
Checking for duplicate entries...OK
Checking for valid user names...OK

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

% grid-mapfile-check-consistency -f /etc/grid-security/grid-mapfile
Checking /etc/grid-security/grid-mapfile
Verifying grid mapfile existence...OK
Checking for duplicate entries...OK
ERROR: baduser is not a valid local username
ERROR: Found 1 invalid username(s)

Environment Variables

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

GRIDMAP: Path to the default gridmap to check.

Files

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

$HOME/.gridmap: Path to the default gridmap to check if the GRIDMAP environment variable is not set for non-root users.
/etc/grid-security/grid-mapfile: Path to the default gridmap to check if GRIDMAP environment variable is not set and the above file does not exist.

Name

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

Synopsis

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

grid-mapfile-delete-entry {-dn DISTINGUISHED-NAME} {-ln LOCAL-NAME... }
[[-d] | [-dryrun]]
[[-mapfile MAPFILE] | [-f MAPFILE]]

Description

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

-help, -usage: Display the command-line options to grid-mapfile-delete-entry.
-version, -versions: Display the version number of the grid-mapfile-delete-entry command. The second form includes more details.
-dn DISTINGUISHED-NAME: The X.509 distinguished name to remove from the gridmap file. If the -ln option is not specified, remove all entries for this name; otherwise, remove entries that match both this name and the local name. The name should be in OpenSSL's oneline format.
-ln LOCAL-NAME...: The POSIX user name to remove from the gridmap file. Include multiple LOCAL-NAME strings after the -ln command-line option to remove multiple names from the gridmap. If the -dn option is not specifeid, remove all entries for these names; otherwise, remove entries that match the DISTINGUISHED-NAME and any of the LOCAL-NAME values.
-d, -dryrun: Display diagnostics about what would be removed from the gridmap file, but don't actually modify the file.
-mapfile MAPFILE, -f MAPFILE: Modify the gridmap file named by MAPFILE instead of the default.

Examples

Remove all mappings for a distinguished name:

% grid-mapfile-delete-entry "/DC=org/DC=example/DC=grid/CN=Joe User"
Modifying /etc/grid-security/grid-mapfile ...
Deleting entry: "/DC=org/DC=example/DC=grid/CN=Joe User" juser,juser2
(1) entry deleted

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

% grid-mapfile-delete-entry "/DC=org/DC=example/DC=grid/CN=Joe User" -ln juser2
Modifying /etc/grid-security/grid-mapfile ...
Current entry: "/DC=org/DC=example/DC=grid/CN=Joe User" juser
(1) mapping removed: (juser2), (0) not present and ignored
(0) entries deleted

Environment Variables

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

GRIDMAP: Path to the default gridmap to modify.

Files

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

/etc/grid-security/grid-mapfile: Path to the default gridmap to modify if GRIDMAP environment variable is not set.

Chapter 2. Troubleshooting

Table of Contents

1. Credential Troubleshooting

1.1. Credential Errors

1.2. Some tools to validate certificate setup

1.2.1. grid-cert-diagnostics
1.2.2. Check that the user certificate is valid
1.2.3. Connect to the server using s_client
1.2.4. Check that the server certificate is valid

2. Grid map Troubleshooting

2.1. Grid map errors

The following includes common errors for credentials and gridmap files. For information about system administrator logs, see Chapter 4, Debugging in the GSI C Admin Guide.

For a list of common errors in GT, see Error Codes.

1. Credential Troubleshooting

1.1. Credential Errors

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

For a list of common errors in GT, see Error Codes.

Table 2.1. 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), 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). 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 Installing GT 5.0.2 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 Installing GT 5.0.2 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) .

1.2. Some tools to validate certificate setup

1.2.1. grid-cert-diagnostics

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

% grid-cert-diagnostics -p

1.2.2. Check that the user certificate is valid

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

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

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

2. Grid map Troubleshooting

2.1. Grid map errors

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

For a list of common errors in GT, see Error Codes.

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

Glossary

P

proxy certificate

A short lived certificate issued using a EEC. A proxy certificate typically has the same effective subject as the EEC that issued it and can thus be used in its place. GSI uses proxy certificates for single sign on and delegation of rights to other entities.

For more information about types of proxy certificates and their compatibility in different versions of GT, see http://dev.globus.org/wiki/Security/ProxyCertTypes.

S

scheduler: Term used to describe a job scheduler mechanism to which GRAM interfaces. It is a networked system for submitting, controlling, and monitoring the workload of batch jobs in one or more computers. The jobs or tasks are scheduled for execution at a time chosen by the subsystem according to an available policy and availability of resources. Popular job schedulers include Portable Batch System (PBS), Platform LSF, and IBM LoadLeveler.

U

user certificate: A EEC belonging to a user. When using GSI, this certificate is typically stored in $HOME/.globus/usercert.pem. For more information on possible user certificate locations, see this.

Software Links

Getting Started

Components

Reference

GT5: Security: GSI C User's Guide

Chapter 1. Usage scenarios

1. Basic procedure for using GSI C

GSI Commands

Name

Synopsis

Description

Environment

Name

Synopsis

Description

Examples

Name

Synopsis

Description

Examples

Environment Variables

Name

Synopsis

Description

Examples

Environment Variables

Files

Name

Synopsis

Description

Examples

Environment Variables

Bugs

See Also

Name

Synopsis

Description

Examples

Environment Variables

Name

Synopsis

Description

Examples

Environment Variables

Files

Compatibility

See Also

Name

Synopsis

Description

Environment Variables

See Also

Name

Synopsis

Description

Environment Variables

See Also

Name

Synopsis

Description

Examples

Environment Variables

Files

See Also

Name

Synopsis

Description

Examples

Environment Variables

Files

See Also

Name

Synopsis

Description

Examples

Environment Variables

Files

See Also

Chapter 2. Troubleshooting

1. Credential Troubleshooting