GT 3.9.4 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
- grid-cert-request
- grid-default-ca
- grid-change-pass-phrase
- grid-proxy-init
- grid-proxy-destroy
- grid-proxy-info
- grid-mapfile-add-entry
- grid-mapfile-check-consistency
- grid-mapfile-delete-entry
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
-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-info generates a X.509 certificate request.
Command syntax
grid-cert-request [-help] [ options ...]Example Usage:
Creating a user certifcate:
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 usage
-usage
-cn <name>, : Common name of the user
-commonname <name>
-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, : Create certificate without a passwd
-nodes,
-nopassphrase,
-verbose : Don't clear the screen
-int[eractive] : Prompt user for each component of the DN
-force : Overwrites preexisting certifictes
-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
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>, OID string for the policy language
-policy-language <oid> 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 dir
-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
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
-- End 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
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] Prints information about proxy
-exists [options] (-e) Returns 0 if valid proxy exists, 1 otherwise
[printoptions]
-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
[options to -exists] (if none 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]
grid-mapfile-add-entry adds an entry to a Grid mapfile.
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 map DN to
-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]grid-mapfile-check-consistency checks the consistency of the Grid mapfile.
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]grid-mapfile-delete-entry deletes one or more matching entries from the Grid mapfile.
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
Usegrid-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
Usegrid-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 (withgrid-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
Usegrid-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
Usegrid-mapfile-add-entry to add the relevant entry.