NAME

gx-map cadesc - The cadesc file format used by gx-map

DESCRIPTION

A cadesc file is a plain text file containing the information needed for the gx-ca-update command to work with a CA (Certificate Authority).

The cadesc files are installed under the etc/gx-map/ca-config directory of the gx-map installation directory. A number of these files are provided with the gx-map distribution. Users can also create their own cadesc files (and are encouraged to send them to the author for inclusion in future gx-map releases).

The name of each file is of the form <hash>.<name>.cadesc, where <hash> is the 8-digit hexadecimal hash value that identifies the CA's signing certificate, and <name> is a brief name for the CA. For example, the description file for the SDSC Certificate Authority is 3deda549.sdsc.cadesc.

A cadesc file is a plain text file where each line contains an attribute name followed by the corresponding attribute value. Blank lines are ignored. Comments are introduced by the '#' character.

ATTRIBUTES

This is a list of the allowed attributes in a cadesc file. Attributes marked as ``(required)'' must be specified, and must have a valid value. Attributes marked as ``(doc)'' are provided only for documentation; gx-ca-update ignores their values.

CA_NAME (required)
The name of the CA. This is a brief informal name, such as ``SDSC CA''; it needn't match the name included in the name of the cadesc file. This is included as a comment in the generated signing_policy file.

HOMEPAGE (doc)
The URL for the web page associated with the CA.

CONTACT (doc)
An e-mail address for the CA.

HASH (required)
The 8-digit hexadecimal hash for the certificate's subject name.

It can be computed by openssl x509 -hash -in FILENAME -noout

The hash is incorporated into the names of the certificate, CRL, and signing_policy files (xxxxxxxx.0, xxxxxxxx.r0, and xxxxxxxx.signing_policy, respectively). The specified hash is checked against the downloaded certificate.

SIGNED_BY
If provided, this specifies the subject name of the signer of the CA certificate. This is mandatory if the certificate is not self-signed. If the certificate is self-signed, the SIGNED_BY attribute should be omitted. The value is checked against the actual issuer of the certificate. gx-ca-update also checks whether the issuing certificate is installed.

SUBJECT (required)
The subject name of the signing certificate. This is checked against the actual subject name of the downloaded certificate.

MAY_SIGN (required)
A pattern (either a wildcard or a single subject name) used to construct the signing_policy file. More than one MAY_SIGN attribute may be specified. This is used to construct the signing_policy file.

CERTIFICATE_MD5 (required)
The MD5 fingerprint of the signing certificate. This can be determined by openssl x509 -md5 -fingerprint -in FILENAME -noout

This is checked against the actual fingerprint of the downloaded certificate.

CERTIFICATE_SHA1 (required)
The SHA1 fingerprint of the signing certificate. This can be determined by openssl x509 -sha1 -fingerprint -in FILENAME -noout

This is checked against the actual fingerprint of the downloaded certificate.

The MD5 and SHA1 algorithms have been demonstrated to have some weaknesses. It is hoped that checking both will provide some better level of security than checking just one. If future releases of OpenSSL provide more secure hash functions, future releases of gx-map will use them.

CERTIFICATE_URL (required)
A URL from which the signing certificate, in PEM format, can be downloaded. This must be a URL; it cannot be the name of a local file.

SIGNING_POLICY_URL (doc)
A URL from which a signing_policy file can be downloaded. This must be a URL; it cannot be the name of a local file. This is included for reference; gx-ca-update doesn't use it. Instead, the signing_policy file is constructed from the SUBJECT and MAY_SIGN attributes. This allows a site to impose a stricter policy than the one suggested by the CA's owner (or a looser policy, but that's seldom a good idea). It also ensures that the signing_policy reflects both GT2-compatible and GT4-compatible forms (e.g., both ``/USERID='' and ``/UID=''); see below.

CRL_URL
A URL from which the certificate revocation list, in PEM format, can be downloaded. This must be a URL; it cannot be the name of a local file. A missing CRL_URL is normally treated as an error; see the -allow-missing-crl command-line option and the ALLOW_MISSING_CRL attributes for ways to override this.

ALLOW_MISSING_CRL
This is similar to the gx-ca-update's -allow-missing-crl command line option, but it applies only to a single CA, generally one like the PSC or USC Kerberos CA that only issues short-term certificates. If this attribute is set to ``yes'', an unspecified, missing, or expired CRL is not a fatal error.

Recognizing a CA that doesn't provide a CRL is normally not recommended. The PSC and USC Kerberos CAs are exceptions to this, since they don't issue long-term certificates.

CERT_EXPIRES (doc)
This is the expiration date for the certificate. It can be determined by openssl x509 -in FILENAME -noout -enddate

DISABLE
If set to ``yes'', this indicates that the CA files are not to be installed. Note that setting DISABLE to ``no'', or omitting it, doesn't mean that the CA files will be installed. The set of CAs to be recognized is specified by the -ca or -ca-list option to the gx-ca-update program.

For consistency, the SIGNED_BY, SUBJECT, and MAY_SIGN attributes should use forms compatible with GT3/GT4 or higher and OpenSSL 0.9.7 or higher:

    Use "/UID=...", not "/USERID=..." or "/0.9.2342.19200300.100.1.1=..."
    Use "/emailAddress=...", not "/Email=...".

though gx-ca-update will translate to this form if necessary.

See http://bugzilla.globus.org/bugzilla/show_bug.cgi?id=575> for more information about this issue.

URLs with a prefix of either ``http://'', ``https://'', or ``ftp://'' are accepted. Files specified by URLs are downloaded using the ``curl'' command.

SEE ALSO

gx-map(8), gx-ca-update(8), gx-map-security(7)

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.