GT 3.9.3 Component Guide to Public Interfaces: Pre-WS Authentication & Authorization

Semantics and syntax of APIs

Documentation for the APIs in this component can be found here:

For information on the internationalization API, see the C Common Libraries Public Interface.

Semantics and syntax of the WSDL

This component has no WSDL interfaces.

Protocol Specifications

The GSSAPI implementation contained in this component produces security tokens that follow a extended version of the SSL/TLS protocol. More information about the protocol can be found here.

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

Overview of Graphical User Interfaces

This component does not have any GUIs.

Semantics and syntax of domain-specific interface

Interface introduction

[provide an overview of the purpose and structure of the domain-specific interface]

Syntax of the interface

[list and describe detailed information here]

Configuration interface

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 systemwide location if no user-specific file was found. The configuration commands described here may be run by administrators to create systemwide defaults, and by individuals to override those defaults. [TODO: Add a reference to an overview document]

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 that CA in the trusted certificate directory. [TODO: link to the environment fragment, which explains where the trusted certificates directory is] The following two files must exist in that directory for each trusted CA:

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

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.

WSRF-based components ignore the signing policy file and will honor all valid certificates issued by trusted CAs.

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.

Configuring Globus to Create Appropriate Certificate Requests

The grid-cert-request command, which is used to create certificates, uses the following configuration files:

globus-user-ssl.conf defines the distinguished name to use for a user's certificate request. The format is described here.
globus-host-ssl.conf defines the distinguished name for a host (or service) certificate request. The format is described here.
grid-security.conf a base configuration file that contains the name and email address for the CA.

Many CAs provide tools to install configuration files called globus-user-ssl.conf.cert_hash, globus-host-ssl.conf.cert_hash, and grid_security.conf.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 [TODO: link to environment fragment] and TRUSTED_CA is the trusted CA directory: 

   ln -s GRID_SECURITY/globus-user-ssl.conf \
         TRUSTED_CA/globus-user-ssl.conf.cert_hash
   ln -s GRID_SECURITY/globus-host-ssl.conf \
         TRUSTED_CA/globus-host-ssl.conf.cert_hash
   ln -s GRID_SECURITY/grid_security.conf \
         TRUSTED_CA/grid_security.conf.cert_hash

Requesting Service Certificates

Different CAs use different mechanisms for issuing end-user certificates; some use mechanisms that are entirely web-based, while others require you to generate a certificate request and send it to the CA. If you need to create a certificate request for a service certificate, you can do so by running: 

    grid-cert-request -host hostname -service service_name

where hostname is the fully-qualified name of the host on which the service will be running, and service_name is the name of the service. This will create the following three files:

GRID_SECURITY/service_name/service_namecert.pem An empty file. When you receive your actual service certificate from your CA, you should place it in this file.
GRID_SECURITY/service_name/service_namecert_request.pem The certificate request, which you should send to your CA.
GRID_SECURITY/service_name/service_namekey.pem The private key associated with your certificate request, encrypted with the pass phrase that you entered when prompted by grid-cert-request.

The grid-cert-request command recognizes several other useful options; you can list these with: 

    grid-cert-request -help

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. [TODO: link to the environment fragment, which tells how to find the gridmap file] 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 gridmap files. To add an entry to the gridmap 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 that 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.

GSI File Permissions Requirements

Environment variable interface

  • X509_USER_PROXY specifies the path to the proxy credential. If X509_USER_PROXY is not set, the proxy credential is created (by grid-proxy-init) and searched for (by client programs) in an operating-system-dependent local temporary file.
  • X509_USER_CERT and X509_USER_KEY specify the path to the end entity (user, service, or host) certificate and corresponding private key. The paths to the certificate and key files are determined as follows:
    • For user credentials:
      1. If X509_USER_CERT and X509_USER_KEY exist and contain a valid certificate and key, those files are used.
      2. Otherwise, if the files usercert.pem and userkey.pem exist in the user's .globus directory, those files are used.
      3. Otherwise, if a PKCS-12 file called usercred.p12 exists in the user's .globus directory, the certificate and key are read from that file.
    • For service credentials:
      1. If X509_USER_CERT and X509_USER_KEY exist and contain a valid certificate and key, those files are used.
      2. Otherwise, if the files /etc/grid-security/service/servicecert and /etc/grid-security/service/servicekey exist and contain a valid certificate and key, those files are used.
      3. Otherwise, if the files $GLOBUS_LOCATION/etc/grid-security/service/servicecert and $GLOBUS_LOCATION/etc/grid-security/service/servicekey exist and contain a valid certificate and key, those files are used.
      4. Otherwise, if the files service/servicecert and service/servicekey in the user's .globus directory, exist and contain a valid certificate and key, those files are used.
    • For host credentials:
      1. If X509_USER_CERT and X509_USER_CERT exist and contain a valid certificate and key, those files are used.
      2. Otherwise, if the files /etc/grid-security/hostcert and /etc/grid-security/hostkey exist and contain a valid certificate and key, those files are used.
      3. Otherwise, if the files $GLOBUS_LOCATION/etc/grid-security/hostcert and $GLOBUS_LOCATION/etc/grid-security/hostkey exist and contain a valid certificate and key, those files are used.
      4. Otherwise, if the files hostcert and hostkey in the user's .globus directory, exist and contain a valid certificate and key, those files are used.
  • GRIDMAP specifies the path to the gridmap file, which is used to map distinguished names (found in certificates) to local names (such as login accounts). 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 that 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.
  • X509_CERT_DIR is used to specify the path to the trusted certificates directory; this directory contains information about which CAs are trusted (including the CA certificates themselves) and, in some cases, configuration information used by grid-cert-request to formulate certificate requests. The location of the trusted certificates directory is determined as follows:
    1. If the X509_CERT_DIR environment variable is set, the trusted certificates directory is the value of that environment variable.
    2. Otherwise, if $HOME/.globus/certificates exists, that directory is the trusted certificates directory.
    3. Otherwise, if /etc/grid-security/certificates exists, that directory is the trusted certificates directory.
    4. Finally, if $GLOBUS_LOCATION/share/certificates exists, then it is the trusted certificates directory.
  • GRID_SECURITY_DIR specifies a path to a directory containing configuration files that specify default values to be placed in certificate requests; this environment variable is used only by the grid-cert-request and grid-default-ca commands.
    • The location of the grid security directory is determined as follows:
    1. If the GRID_SECURITY_DIR environment variable is set, the grid security directory is the value of that environment variable.
    2. If the configuration files exist in /etc/grid-security, the grid security directory is that directory.
    3. if the configuration files exist in $GLOBUS_LOCATION/etc, the grid security directory is that directory.