NAME

gx-ca-update - Maintain certificate authority files

SYNOPSIS

gx-ca-update -help

gx-ca-update [options]

DESCRIPTION

gx-ca-update is part of the gx-map system. It is used to maintain the CA (Certificate Authority) files (signing certificates, signing_policy files, and CRLs (Certificate Revocation Lists)) used by Globus.

gx-ca-update is normally run from a cron job. It attempts to update the files for a specified set of certificate authorities.

It uses a caching mechanism to avoid downloading files unless they've been updated.

EXAMPLES

A typical cron job entry might look something like this:

    0,30 * * * * [...]/sbin/gx-ca-update
                 -target-dir [...]/certificates
                 -ca-list [...]/certificates/.list

In real life, the entire cron job entry has to be on a single line, and the ``[...]''s need to be replaced with actual directory names.

This cron job runs every 30 minutes. It maintains the *.0, *.signing_policy, and *.r0 files for the CAs listed in the .list file.

OPTIONS

Option processing is done using the Perl Getopt::Long module.

Options may be specified with a single or double leading '-' character. Option names may be abbreviated to whatever is unique. Arguments may be separated either by a blank or by an '=' character. For example, ``-foobar 42'', ``--foobar=42'', and ``-foob 42'' would all be equivalent.

-help
Display a usage message and exit. The usage message contains descriptions of all command-line options, and is likely to be more correct than this man page.

-version
Display the software version number and exit.

-UNSAFE
Enable options that can create potential security problems. The -UNSAFE option must be in all-caps, and it may not be abbreviated.

-ca name
Name of a certificate authority. Normally this is given as the 8-digit hexadecimal hash value, but a brief name can also be used; use -list-cas to see a list. This option may be given multiple times, and/or the argument may be a list of CA names separated by commas or blanks (in the latter case, the argument must be quoted).

-ca-list file
Name of a text file containing a list of CAs. This option may be given multiple times.

-list-cas
Show a list of available CAs and exit.

-list-all-cas
Like -list-cas, but include disabled CAs as well.

-target-dir dir
Specify the target directory. Typically this will be either /etc/grid-security/certificates or a directory to which /etc/grid-security/certificates is a symbolic link.

-[no]download
By default, gx-ca-update attempts to download files as needed. With -nodownload, use only existing files in the cache directory.

This can be useful if multiple instances of gx-map are being used on several systems with a shared data directory. One instance can run in the default -download mode, and all the others can depend on the cache files, saving time and network traffic.

-permissions perm
Specify the permissions, in octal, for the installed files. The default is 444; there is rarely any reason to use a different value.

-gt3-compatible
Generate *.signing_policy files compatible with GT3 web services tools. This should rarely be necessary or useful. By default, generated *.signing_policy files are compatible with both GT2 and GT4, and with GT3 pre-WS (so no -gt2-compatible option is needed).

-allow-missing-crl
Allow a CA with no CRL to be installed. Some Certificate Authorities don't provide Certificate Revocation Lists. This creates a potential security hole, since there's no way to revoke a compromised certificate. This requires the -UNSAFE option.

If a CA issues only short-term certificates, the lack of a CRL isn't necessarily a problem. For these CAs, the -allow-missing-crl option isn't required. These CAs are indicated by the ALLOW_MISSING_CRL option in the *.cadesc file.

-expire-crl time
Remove a CRL that will expire within time. The time is expressed as a number followed by 's' (seconds), 'm' (minutes), 'h' (hours), or 'd' (days); it should be slightly longer than the interval of the cron job. By default, expiring CRLs are left in place.

Removing an expiring CRL means that all certificates issued by the CA will potentially be accepted, even if they've been revoked; this is a potential security issue. Leaving an expired CRL in place causes all certificates issued by the CA to be rejected. The proper solution is to make sure that a current CRL is always available; this is the responsibility of the CA administrators.

This option requires the b<-UNSAFE> option.

-warn-crl time
Issue an e-mail warning message if the CRL will expire within the specified time. Regardless of this option, a warning will also be issued if the CRL has used more than 90% of its lifetime.

-force
Force file updates. This applies to certificates, signing_policy files, and CRLs.

-ignore-disable
Certain CAs are disabled by default, as indicated by the DISABLE attribute in the *.cadesc file. This option overrides that attribute and allows the CA to be used. This requires the -UNSAFE option.

-email
Send e-mail to the configured ADMIN_EMAIL address on errors. This is set by default; use -noemail to disable e-mail messages.

-verbose
Print verbose messages.

-debugging
Enable debugging output. Not recommended.

FILES

The gx-ca-update command uses information in a set of CA description files installed in the etc/gx-map/ca-config subdirectory under the gx-map installation directory. Currently, there are configuration files for 88 different CAs.

Each CA certificate has an 8-digit hexadecimal hash value associated with it. The files maintained by gx-ca-update have names based on this hash value. For example, the SDSC CA's hash value is 3deda549; the corresponding files are:

3deda549.0, the signing certificate

3deda549.signing_policy, the signing policy file.

3deda549.r0, the certificate revocation list

Since the certificate is updated only rarely, gx-ca-update normally only installs it once; it doesn't attempt to re-install it unless the -force option is specified.

The signing_policy file is generated by gx-ca-update, even if a copy is available from the CA's web site. This allows for a consistent format for all installed signing_policy files. There are also some changes that need to be made for some files for compatibility with different versions of Globus; the files distributed by the CAs don't always have these changes.

Typically, the CRL has a relatively short lifetime; it's re-issued both periodically and immediately when a certificate is revoked. gx-ca-update checks the CRL each time it runs, and downloads and installs it if it's been updated.

SECURITY

Incorrectly installed CA files can open serious security holes. For example, an attacker could create a fake signing certificate with the same hash and subject name as an existing CA certificate, and then sign a user certificate matching an existing one, giving the attacker access to the target user's account. (The 8-digit hash is computed from the certificate's subject name; it's a convenient way to identify the certificate, but it's not secure.)

To prevent this, gx-ca-update confirms the MD5 and SHA1 checksums of any downloaded certificate before installing it. The checksums are compared to the ones specified in the corresponding *.cadesc file, which are based on my own download and manual check of the file. To get past this check, an attacker would have to have taken control of the CA web site both when I checked the certificate and when gx-ca-update attempts to download it.

Before each CRL is installed, gx-ca-update confirms that it was cryptographically signed by the corresponding certificate.

I've done my best to make the entire gx-map system as secure as possible. Nevertheless, ...

GUARANTEES

None. If you install this software and it breaks your system, it's your own fault for trusting me.

SEE ALSO

gx-map(7), gx-map-security(7), gx-map-cadesc(5)

AUTHOR

Keith Thompson, San Diego Supercomputer Center, <kst@sdsc.edu>

COPYRIGHT AND LICENSE

See the file LICENSE in the gx-map distribution, installed in the etc/gx-map subdirectory.