GT 3.9.5 Pre-WS Authentication & Authorization: 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.

In most cases, an individual will do the following:

  • Acquire an end-user certificate from a certificate authority (CA). This certificate will typically be valid for a year or more and will be stored in a file in the individual's home directory.
  • Use the end-user certificate to create a proxy certificate, which will be used to authenticate the individual to grid services. Proxy certificates typically have a much shorter lifetime than end-user certificates.

[TODO: Add a reference to the general GSI introduction, and make sure there's a reference to something that explains why we use proxy certs. Maybe add a reference to MyProxy?]

Command-line tools

grid-cert-info

Tool description

grid-cert-info displays information contained in a X.509 certificate.

Command syntax

grid-cert-info [-help] [-file certfile] [-all] [-subject] [...]

Displays certificate information. Unless the optional -file argument is given, the default location of the file containing the certficate is assumed:

  • The location pointed to by the X509_USER_CERT.
  • If X509_USER_CERT not set, /home/meder/.globus/usercert.pem.

Several options can be given. The output of

grid-cert-info -subject -issuer

is equivalent to that of

grid-cert-info -subject ; grid-cert-info -issuer

Options

General options:

-help, -usage
Display usage
-version
Display version
-file certfile |-f
Use 'certfile' at non-default location

Options determining what to print from certificate:

-all
Whole certificate
-subject |-s
Subject string of the cert
-issuer |-i
Issuer
-startdate  |-sd
Validity of cert: start date
-enddate |-ed
Validity of cert: end date

Limitations

Nothing applicable

grid-cert-request

Tool description

grid-cert-request generates a X.509 certificate request.

Command syntax

grid-cert-request [-help] [ options ...]

Example Usage:

Creating a user certificate:

 grid-cert-request

Creating a host or gatekeeper certifcate:

 grid-cert-request -host [my.host.fqdn]

Creating a LDAP server certificate:

 grid-cert-request -service ldap -host [my.host.fqdn]

Options:

-version
Display version
-?, -h, -help
Display help.
-usage
Display usage
-cn <name>, -commonname <name>
Common name of the user
-service <service>
Create certificate for a service. Requires the -host option and implies that the generated key will not be password protected (ie implies -nopw).
-host <FQDN>
Create certificate for a host named <FQDN>
-dir <dir_name>
Changes the directory the private key and certificate request will be placed in. By default user certificates are placed in home/meder/.globus, host certificates are placed in /etc/grid-security and service certificates are place in /etc/grid-security/<service>.
-prefix <prefix>
Causes the generated files to be named <prefix>cert.pem, <prefix>key.pem and <prefix>cert_request.pem
-nopw, -nodes, -nopassphrase
Create certificate without a passwd
-verbose
Don't clear the screen
-int[eractive]
Prompt user for each component of the DN
-force
Overwrites preexisting certificates
-ca
Will ask which CA is to be used (interactive)
-ca <hash>
Will use the CA with hash value <hash>

Limitations

Nothing applicable

grid-default-ca

Tool description

grid-default-ca allows the setting of the default CA to be used by tools such as grid-cert-request.

Command syntax

grid-default-ca [-help] [ options ...]

Options:

-help
Display this message.
-dir <dir_name>
The security config directory (defaults to /etc/grid-security/).
-list
List the available CAs to use and the current default.
-ca <ca hash>
Set the default CA non-interactively.

Limitations

Nothing applicable

grid-change-pass-phrase

Tool description

grid-change-pass-phrase allows one to change the passphrase that protects the private key.

Command syntax

grid-change-pass-phrase [-help] [-version] [-file private_key_file]

Changes the passphrase that protects the private key. Note that this command will work even if the original key is not password protected. If the -file argument is not given, the default location of the file containing the private key is assumed:

  • The location pointed to by X509_USER_KEY
  • If X509_USER_KEY not set, /home/meder/.globus/userkey.pem

Options

help, -usage
Displays usage
-version
Displays version
-file location
Change passphrase on key stored in the file at the non-standard location 'location'.

Limitations

Nothing applicable

grid-proxy-init

Tool description

grid-proxy-init generates X.509 proxy certificates.

Command syntax

 grid-proxy-init [-help][-pwstdin][-limited][-valid H:M] ...

Options

-help, -usage
Displays usage.
-version
Displays version.
-debug
Enables extra debug output.
-q
Quiet mode, minimal output.
-verify
Verifies certificate to make proxy for.
-pwstdin
Allows passphrase from stdin.
-limited
Creates a limited globus proxy.
-independent
Creates a independent globus proxy.
-old
Creates a legacy globus proxy.
-valid <h:m>
Proxy is valid for h hours and m minutes (default:12:00).
-hours <hours>
Deprecated support of hours option.
-bits  <bits>
Number of bits in key {512|1024|2048|4096}
-policy <policyfile>
File containing policy to store in the ProxyCertInfo extension.
-pl <oid>, -policy-language <oid>
OID string for the policy language used in the policy file.
-path-length <l>
Allow a chain of at most l proxies to be generated from this one.
-cert <certfile>
Non-standard location of user certificate.
-key <keyfile>
Non-standard location of user key.
-certdir <certdir>
Non-standard location of trusted cert directory.
-out <proxyfile>
Non-standard location of new proxy cert.

Limitations

Nothing applicable

grid-proxy-destroy

Tool description

grid-proxy-destroy removes X.509 proxy certificates.

Command syntax

grid-proxy-destroy [-help][-dryrun][-default][-all][--] [file1...]

Options

-help, -usage
Displays usage.
-version
Displays version.
-debug
Display debugging information.
-dryrun
Prints what files would have been destroyed.
-default
Destroys file at default proxy location.
-all
Destroys any user (default) and delegated proxies that are found.
--
Ends processing of options.
file1 file2 ...
Destroys files listed.

Limitations

Nothing applicable

grid-proxy-info

Tool description

grid-proxy-info extracts information from X.509 proxy certificates.

Command syntax

grid-proxy-info [-help][-f proxyfile][-subject][...][-e [-h H][-b B]]

Options

-help, -usage
Displays usage.
-version
Displays version.
-debug
Displays debugging output.
-file <proxyfile> (-f)
Non-standard location of proxy.
[printoptions]
Use the following options to print information about proxy:
-subject (-s)
Distinguished name (DN) of subject.
-issuer (-i)
DN of issuer (certificate signer).
-identity
DN of the identity represented by the proxy.
-type
Type of proxy (full or limited).
-timeleft
Time (in seconds) until proxy expires.
-strength
Key size (in bits).
-all
All above options in a human readable format.
-text
All of the certificate.
-path
Pathname of proxy file.
-exists [options] (-e)
Returns 0 if valid proxy exists, 1 otherwise. If none of the following options are given, H = B = 0 are assumed:
-valid H:M (-v)
Time requirement for proxy to be valid.
-hours H (-h)
Time requirement for proxy to be valid (deprecated, use -valid instead).
-bits B (-b)
Strength requirement for proxy to be valid.

Limitations

Nothing applicable

grid-mapfile-add-entry

Tool description

grid-mapfile-add-entry adds entries to grid mapfiles.

Command syntax

grid-mapfile-add-entry -dn DN -ln LN  [-help] [-d] [-f mapfile FILE]

Options:

-help, -usage
Displays help.
-version
Displays version.
-dn DN
Distinguished Name (DN) to add. Remember to quote the DN if it contains spaces.
-ln LN1 [LN2...]
Local login name(s) to which the DN is mapped.
-dryrun, -d
Shows what would be done but will not add the entry.
-mapfile FILE, -f FILE
Path of Grid map file to be used.

Limitations

Nothing applicable.

grid-mapfile-check-consistency

Tool description

grid-mapfile-check-consistency checks that the given grid mapfile conforms to the expected format as well as checking for common subject name problems.

Command syntax

grid-mapfile-check-consistency [-help] [-mapfile FILE]

Options:

-help, -usage
Displays help.
-version
Displays version.
-mapfile FILE, -f FILE
Path of gridmap to be used.

Limitations

Nothing applicable

grid-mapfile-delete-entry

Tool description

grid-mapfile-delete entry deletes a grid mapfile entry from the given file.

Command syntax

grid-mapfile-delete-entry [-help] [-dn <DN>] [-ln <local name>] [-d] [-f file]

Options:

-help, -usage
Displays help.
-version
Displays version.
-dn <DN>
Distinguished Name (DN) to delete.
-ln <local name>
Local Login Name (LN) to delete.
-dryrun, -d
Shows what would be done but will not delete the entry.
-mapfile file, -f file
Path of gridmap file to be used.

Limitations

Nothing applicable.

Graphical user interfaces

This component does not have any GUIs.

Troubleshooting

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

Your proxy credential may have expired

Use grid-proxy-info to check whether the proxy 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.

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

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 [TODO: add admin guide link] for details.

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 [TODO: add admin guide link] for details.

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.

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

The content of the gridmap file does not conform to the expected format

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

The gridmap file does not contain a entry for your DN

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