'\" t
.\"     Title: grid-cert-request
.\"    Author: University of Chicago
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 03/22/2010
.\"    Manual: Globus Commands
.\"    Source: Globus Toolkit 5.0.1
.\"  Language: English
.\"
.TH "GRID\-CERT\-REQUEST" "1" "03/22/2010" "Globus Toolkit 5.0.1" "Globus Commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
grid-cert-request \- Generate a X\&.509 certificate request and corresponding private key
.SH "SYNOPSIS"
.HP \w'\fBgrid\-cert\-request\fR\ 'u
\fBgrid\-cert\-request\fR [\-help] [\-h] [\-?] [\-usage]
.br
[\-version] [\-versions]
.HP \w'\fBgrid\-cert\-request\fR\ 'u
\fBgrid\-cert\-request\fR [\-cn\ \fINAME\fR | \-commonname\ \fINAME\fR]
.br
[\-dir\ \fIDIRECTORY\fR] [\-prefix\ \fIPREFIX\fR]
.br
[\-nopw | \-nodes | \-nopassphrase]
.br
[\-nopw | \-nodes | \-nopassphrase]
.br
[\-ca\ [\fIHASH\fR]] [\-verbose] [\-interactive | \-int] [\-force]
.HP \w'\fBgrid\-cert\-request\fR\ 'u
\fBgrid\-cert\-request\fR \-host\ \fIFQDN\fR [\-service\ \fISERVICE\fR] [\-dns\ \fIFQDN\fR...] [\-ip\ \fIIP\-ADDRESS\fR...]
.br
[\-dir\ \fIDIRECTORY\fR] [\-prefix\ \fIPREFIX\fR]
.br
[\-ca\ [\fIHASH\fR]] [\-verbose] [\-interactive | \-int] [\-force]
.SH "DESCRIPTION"
.PP
The
\fBgrid\-cert\-request\fR
program generates an X\&.509 Certificate Request and corresponding private key for the specified name, host, or service\&. It is intended to be used with a CA implemented using the
globus_simple_ca
package\&.
.PP
The default behavior of
\fBgrid\-cert\-request\fR
is to generate a certificate request and private key for the user running the command\&. The subject name is derived from the gecos information in the local system\'s password database, unless the
\fB\-commonname\fR,
\fB\-cn\fR, or
\fB\-host\fR
command\-line options are used\&.
.PP
By default,
\fBgrid\-cert\-request\fR
writes user certificate requests and keys to the
\fB$HOME\fR/\&.globus
directory, and host and service certificate requests and keys to
/etc/grid\-security\&. This can be overridden by using the
\fB\-dir\fR
command\-line option\&.
.PP
The full set of command\-line options to
\fBgrid\-cert\-request\fR
are:
.PP
\fB\-help\fR, \fB\-h\fR, \fB\-?\fR, \fB\-usage\fR
.RS 4
Display the command\-line options to
\fBgrid\-cert\-request\fR
and exit\&.
.RE
.PP
\fB\-version\fR, \fB\-versions\fR
.RS 4
Display the version number of the
\fBgrid\-cert\-request\fR
command\&. The second form includes more details\&.
.RE
.PP
\fB\-cn \fR\fB\fINAME\fR\fR, \fB\-commonname \fR\fB\fINAME\fR\fR
.RS 4
Create a certificate request with the common name component of the subject set to
\fINAME\fR\&. This is used to create user identity certificates\&.
.RE
.PP
\fB\-dir \fR\fB\fIDIRECTORY\fR\fR
.RS 4
Write the certificate request and key to files in the directory specified by
\fIDIRECTORY\fR\&.
.RE
.PP
\fB\-prefix \fR\fB\fIPREFIX\fR\fR
.RS 4
Use the string
\fIPREFIX\fR
as the base name of the certificate, certificate_request, and key files instead of the default\&. For a user certificate request, this would mean creating files
\fB$HOME\fR/\&.globus/\fIPREFIX\fRcert_request\&.pem,
\fB$HOME\fR/\&.globus/\fIPREFIX\fRcert\&.pem, and
\fB$HOME\fR/\&.globus/\fIPREFIX\fRkey\&.pem\&.
.RE
.PP
\fB\-ca \fR\fB\fICA\-HASH\fR\fR
.RS 4
Use the certificate request configuration for the CA with the name hash
\fICA\-HASH\fR
instead of the default CA chosen by running
\fBgrid\-default\-ca\fR\&.
.RE
.PP
\fB\-verbose\fR
.RS 4
Keep the output from the OpenSSL certificate request command visible after it completes, instead of clearing the screen\&.\&.
.RE
.PP
\fB\-interactive\fR, \fB\-int\fR
.RS 4
Prompt for each component of the subject name of the request, instead of generating the common name from other command\-line options\&. Note that CAs may not sign certificates for subject names that don\'t match their signing policies\&.
.RE
.PP
\fB\-force\fR
.RS 4
Overwrite any existing certificate request and private key with a new one\&.
.RE
.PP
\fB\-nopw\fR, \fB\-nodes\fR, \fB\-nopassphrase\fR
.RS 4
Create an unencrypted private key for the certificate instead of prompting for a passphrase\&. This is the default behavior for host or service certificates, but not recommended for user certificates\&.
.RE
.PP
\fB\-host \fR\fB\fIFQDN\fR\fR
.RS 4
Create a certificate request for use on a particular host\&. This option also causes the private key assoicated with the certificate request to be unencrypted\&. The
\fIFQDN\fR
argument to this option should be the fully qualified domain name of the host that will use this certificate\&. The subject name of the certificate will be derived from the
\fIFQDN\fR
and the service option if specified by the
\fB\-service\fR
command\-line option\&. If the host for the certificate has multiple names, then use either the
\fB\-dns\fR
or
\fB\-ip\fR
command\-line options to add alternate names or addresses to the certificates\&.
.RE
.PP
\fB\-service \fR\fB\fISERVICE\fR\fR
.RS 4
Create a certificate request for a particular service on a host\&. The subject name of the certificate will be derived from the
\fIFQDN\fR
passed as the argument to the
\fB\-host\fR
command\-line option and the
\fISERVICE\fR
string\&.
.RE
.PP
\fB\-dns \fR\fB\fIFQDN,\&.\&.\&.\fR\fR
.RS 4
Create a certificate request containing a
subjectAltName
extension containing one or more host names\&. This is used when a certificate may be used by multiple virtual servers or if a host has different names when contacted within or outside a private network\&. Multiple DNS names can be included in the extension by separating then with a comma\&.
.RE
.PP
\fB\-ip \fR\fB\fIIP\-ADDRESS,\&.\&.\&.\fR\fR
.RS 4
Create a certificate request containing a
subjectAltName
extension containing the IP addresses named by the
\fIIP\-ADDRESS\fR
strings\&. This is used when a certificate may be used by services listening on multiple networks\&. Multiple IP addresses can be included in the extension by separating then with a comma\&.
.RE
.SH "EXAMPLES"
.PP
Create a user certificate request:
.sp
.if n \{\
.RS 4
.\}
.nf
%  \fBgrid\-cert\-request\fR
A certificate request and private key is being created\&.
You will be asked to enter a PEM pass phrase\&.
This pass phrase is akin to your account password, 
and is used to protect your key file\&.
If you forget your pass phrase, you will need to
obtain a new certificate\&.
A private key and a certificate request has been generated with the subject:

/O=org/OU=example/OU=grid/CN=Joe User

If the CN=Joe User is not appropriate, rerun this
script with the \-force \-cn "Common Name" options\&.

Your private key is stored in /home/juser/\&.globus/userkey\&.pem
Your request is stored in /home/juser/\&.globus/usercert_request\&.pem

Please e\-mail the request to the Example CA ca@grid\&.example\&.org
You may use a command similar to the following:

  cat /home/juser/\&.globus/usercert_request\&.pem | mail ca@grid\&.example\&.org

Only use the above if this machine can send AND receive e\-mail\&. if not, please
mail using some other method\&.

Your certificate will be mailed to you within two working days\&.
If you receive no response, contact Example CA at ca@grid\&.example\&.org
.fi
.if n \{\
.RE
.\}
.PP
Create a host certificate for a host with two names\&.
.sp
.if n \{\
.RS 4
.\}
.nf
%  \fBgrid\-cert\-request\fR \fB\-host grid\&.example\&.org\fR \fB\-dns grid\&.example\&.org,grid\-internal\&.example\&.org\fR

A private host key and a certificate request has been generated
with the subject:

/O=org/OU=example/OU=grid/CN=host/grid\&.example\&.org

\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-

The private key is stored in /etc/grid\-security/hostkey\&.pem
The request is stored in /etc/grid\-security/hostcert_request\&.pem

Please e\-mail the request to the Example CA ca@grid\&.example\&.org
You may use a command similar to the following:

 cat /etc/grid\-security/hostcert_request\&.pem | mail ca@grid\&.example\&.org

Only use the above if this machine can send AND receive e\-mail\&. if not, please
mail using some other method\&.

Your certificate will be mailed to you within two working days\&.
If you receive no response, contact Example CA at
ca@grid\&.example\&.org
.fi
.if n \{\
.RE
.\}
.sp
.SH "ENVIRONMENT VARIABLES"
.PP
The following environment variables affect the execution of
\fBgrid\-cert\-request\fR:
.PP
\fBX509_CERT_DIR\fR
.RS 4
Path to the directory containing SSL configuration files for generating certificate requests\&.
.RE
.PP
\fBGRID_SECURITY_DIR\fR
.RS 4
Path to the directory containing SSL configuration files for generating certificate requests\&. This value is used if
\fBX509_CERT_DIR\fR
is not set\&.
.RE
.PP
\fBGLOBUS_LOCATION\fR
.RS 4
Path to the directory containing the Globus Toolkit\&. This is searched if neither the
\fBX509_CERT_DIR\fR
nor the
\fBGRID_SECURITY_DIR\fR
environment variables are set\&.
.RE
.SH "FILES"
.PP
.PP
\fB$HOME\fR/\&.globus/usercert_request\&.pem
.RS 4
Default path to write a user certificate request\&.
.RE
.PP
\fB$HOME\fR/\&.globus/usercert\&.pem
.RS 4
Default path to write a user certificate\&.
.RE
.PP
\fB$HOME\fR/\&.globus/userkey\&.pem
.RS 4
Default path to write a user private key\&.
.RE
.PP
/etc/grid\-security/hostcert_request\&.pem
.RS 4
Default path to write a host certificate request\&.
.RE
.PP
/etc/grid\-security/hostcert\&.pem
.RS 4
Default path to write a host certificate\&.
.RE
.PP
/etc/grid\-security/hostkey\&.pem
.RS 4
Default path to write a host private key\&.
.RE
.PP
\fITRUSTED\-CERT\-DIR\fR/globus\-user\-ssl\&.conf, \fITRUSTED\-CERT\-DIR\fR/globus\-user\-ssl\&.conf\&.\fICA\-HASH\fR
.RS 4
SSL configuration file for requesting a user certificate\&. The first form is the default location, the second form is used when the
\fI\-ca\fR
command\-line option is specified\&.
.RE
.PP
\fITRUSTED\-CERT\-DIR\fR/globus\-host\-ssl\&.conf, \fITRUSTED\-CERT\-DIR\fR/globus\-host\-ssl\&.conf\&.\fICA\-HASH\fR
.RS 4
SSL configuration file for requesting a host or service certificate\&. The first form is the default location, the second form is used when the
\fI\-ca\fR
command\-line option is specified\&.
.RE
.SH "AUTHOR"
.PP
\fBUniversity of Chicago\fR