'\" t
.\"___INFO__MARK_BEGIN__
.\"
.\" Copyright: 2004 by Sun Microsystems, Inc.
.\" Copyright 2012, 2013 Dave Love, University of Liverpool
.\"
.\"___INFO__MARK_END__
.\"
.\" Some handy macro definitions [from Tom Christensen's man(1) manual page].
.\"
.de SB		\" small and bold
.if !"\\$1"" \\s-2\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
..
.\" "
.de T		\" switch to typewriter font
.ft CW		\" probably want CW if you don't have TA font
..
.\"
.de TY		\" put $1 in typewriter font
.if t .T
.if n ``\c
\\$1\c
.if t .ft P
.if n \&''\c
\\$2
..
.\"
.de M		\" man page reference
\\fI\\$1\\fR\\|(\\$2)\\$3
..
.TH SGE_CA 8 "2011-05-19" "xxRELxx" "xxQS_NAMExx Administrative Commands"
.SH NAME
util/sgeCA/sge_ca \- xxQS_NAMExx CSP Support control command
.\"
.\"
.SH SYNTAX
.B sge_ca
.I command
.RI [ "command options" ]
.\"
.\"
.SH DESCRIPTION
.I "\fBsge_ca\fP" 
controls a simple xxQS_NAMExx Certificate Authority that is used for the special Certificate Security Protocol (CSP) mode.
CSP mode improves the security behavior of xxQS_NAMExx by enabling OpenSSL secured communication channels and X509v3 certificates for authentication. In addition it is possible to export the key material or to create JKS keystores for the JMX connector.
There follows a list of possible commands and command options to give
an overview of what functionality is available. For further details about every command refer to the COMMAND DETAILS section.
.SH COMMAND OVERVIEW
.IP "\fB\-help\fP"
Show usage.
.IP "\fB\-init \fP[\fIcommand options\fP]"
Create the infrastructure for a new xxQS_NAMExx Certificate Authority
with its corresponding files and directories, and a set of keys and
certificates for the xxQS_NAMExx daemon, root and admin user.
.IP "\fB\-req \fP|\fB \-verify \fP\fIcert\fP |\fB \-sign \fP|\fB \-copy \fP[\fIcommand options\fP]"
Manipulate individual keys and certificates.
.IP "\fB\-print \fP\fIcert\fP |\fB \-printkey\fP \fIkey\fP |\fB \-printcrl\fP \fIcrl\fP"
Print out certificates, keys and certificate revocation lists in human readable form. 
.IP "\fB\-showCaTop \fP|\fB \-showCaLocalTop \fP[\fIcommand options\fP]"
Echo the $CATOP or $CALOCALTOP directory. This command is usually run as root on the qmaster host after a CA infrastructure has been created. If "\fB\-cadir\fP", "\fB\-catop\fP" or "\fB\-calocaltop\fP" are set, the corresponding directories are printed.
.IP "\fB\-usercert\fP \fIuser file\fP |\fB \-user\fP \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP |\fB \-sdm_daemon\fP \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP [\fIcommand options\fP]"
Create certificates and keys for a bunch of users contained in \fIuser
file\fP, a single user, or SDM daemon
in the form \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP.
.IP "\fB\-pkcs12\fP \fIuser\fP |\fB \-sdm_pkcs12\fP \fIg\fP |\fB \-sys_pkcs12 \fP[\fIcommand options\fP]"
Export the certificate and key for user \fIuser\fP or SDM daemon \fIg\fP in PKCS12 format and to export the xxQS_NAMExx daemon certificate and key in PKCS12 format.
.IP "\fB\-userks \fP|\fB \-ks\fP \fIuser\fP |\fB \-sysks \fP[\fIcommand options\fP]"
Create keystore for all users with a certificate and key, the keystore
for a single user \fIuser\fP, or the keystore containing the xxQS_NAMExx daemon certificate and key.
.IP "\fB\-renew\fP \fIuser\fP |\fB \-renew_ca \fP|\fB \-renew_sys \fP|\fB \-renew_sdm\fP \fIg\fP [\fIcommand options\fP]"
Renew the certificate for user \fIuser\fP, for the CA,
for the xxQS_NAMExx daemon, or the SDM daemon with common name
\fIg\fP.  The old certificate remains valid until it expires.
NB. The option of this name was re-named to \fB\-rrenew\fP in
xxQS_NAMExx 8.1.9.
.IP "\fB\-rrenew\fP \fIuser\fP |\fB \-rrenew_ca \fP|\fB \-rrenew_sys \fP|\fB \-rrenew_sdm\fP \fIg\fP [\fIcommand options\fP]"
Renew the certificate for user \fIuser\fP, for the CA,
for the xxQS_NAMExx daemon, or the SDM daemon with common name
\fIg\fP, and revoke the old ones (updating the revocation list).
NB. This requires \fBunique_subject=no\fP in \fIsge_ssl_template.cnf\fP,
which is the default for new installations, but might not be set for
old ones.
.IP "\fB\-revoke\fP \fIcert\fP"
Revoke the certificate \fIcert\fP, which should be an actual PEM file,
updating the revocation list.
.PP
In the above, "\fIcommand options\fP" is a combination of the following
options depending on the command. The COMMAND DETAILS section explains
which options are usable for each command.
.IP "\fB\-days\fP \fIdays\fP"
days of validity of the certificate
.IP "\fB\-sha1\fP"
Use SHA-1 instead of MD5 as message digest
.IP "\fB\-encryptkey\fP"
Use DES to encrypt the generated private key with a passphrase. The passphrase is requested when a key is created or used.
.IP "\fB\-outdir\fP \fIdir\fP"
Write to directory \fIdir\fP
.IP "\fB\-cahost\fP \fIhost\fP"
Define CA hostname (CA master host)
.IP "\fB\-cadir\fP \fIdir\fP"
Define $CALOCALTOP and $CATOP settings as
.IR dir .
.IP "\fB\-calocaltop \fIdir\fP"
Define $CALOCALTOP setting
.IP "\fB\-catop\fP \fIdir\fP"
Define $CATOP setting
.IP "\fB\-kspwf\fP \fIfile\fP"
Define a keystore password file that contains a password that is used to encrypt the keystore and the keys contained therein
.IP "\fB\-ksout\fP \fIfile\fP"
Define output file to write the keystore to
.IP "\fB\-pkcs12pwf\fP \fIfile\fP"
Define a PKCS12 password file that contains a password that is used to encrypt the PKCS12 export file and the keys contained therein
.IP "\fB\-pkcs12dir\fP \fIdir\fP"
Define the output directory \fIdir\fP to write the exported PKCS12 format file to. Otherwise the current working directory is used.
.\"
.\"
.SH COMMAND DETAILS
.\"
.IP "\fBsge_ca \-init \fP[\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fInum days\fP]"
.br
The \fB\-init\fP command creates a new xxQS_NAMExx certificate authority and its corresponding files. Usually "\fBsge_ca \-init\fP" is run by user root on the master host.
If the options
.BR \-adminuser ,
.BR \-cadir ,
.BR \-calocaltop ,
and
.B \-catop
are not used, and the xxQS_NAMExx environment variables SGE_ROOT,
SGE_CELL and SGE_QMASTER_PORT are set, the CA directories are created
in the following locations:
.I $SGE_ROOT/$SGE_CELL/common/sgeCA
(can be overruled by \fB\-catop\fP \fIdir\fP or \fB\-cadir\fP \fIdir\fP)
.br
.I /var/lib/sgeCA/port$SGE_QMASTER_PORT/$SGE_CELL
or
.I /var/lib/sgeCA/sge_qmaster/$SGE_CELL
(can be overruled by \fB\-calocaltop\fP \fIdir\fP or \fB\-cadir\fP \fIdir\fP).
.br
The following information must be delivered for the site:
two letter country code, state, location, e.g. city or your building
code, organization (e.g. your company name), organizational unit,
e.g. your department, and email address of the CA administrator (you!).
.PP
Certificates and keys are generated for the CA itself, the xxQS_NAMExx
daemon, installation user (usually root), and finally for the admin
user.
.PP
How and where the certificates and keys are created can be influenced additionally by:
.IP "\fB\-days\fP \fIdays\fP"
Change the time of validity of the certificates to number of \fIdays\fP instead of 365 days
.IP "\fB\-sha1\fP"
Change the message digest algorithm from MD5 to SHA-1
.IP "\fB\-encryptkey\fP"
Encrypt the generated keys with a passphrase
.IP "\fB\-adminuser\fP \fIuser\fP"
Use \fIuser\fP as admin user
.IP "\fB\-cahost\fP \fIhost\fP"
Use \fIhost\fP as the CA master host
.IP "[\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP]"
Set $CATOP and $CALOCALTOP to \fIdir\fP to use something other than
the xxQS_NAMExx default directories.  Either \fB\-cadir\fP \fIdir\fP
has to be specified to replace $CATOP and $CALOCALTOP by the same
directory or \fB\-catop\fP \fIdir\fP for $CATOP and \fB\-calocaltop\fP
\fIdir\fP for $CALOCALTOP.
.\"
.IP "\fBsge_ca \-user\fP \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP]"
Generate user certificate and keys for \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP,
where
.I u
is the user id,
.I g
is the "common name" (real name of the user), and
.I e
is the user's email address.  By default the certificate is valid for
365 days or for \fIdays\fP, as specified with \fB\-days\fP \fIdays\fP.
This command is usually run as user root on the qmaster host. $CATOP
and $CALOCALTOP may be overruled by \fB\-cadir\fP, \fB\-catop\fP, and
\fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-sdm_daemon\fP \fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP"
Generate daemon certificate and keys for
\fIu\fP\fB:\fP\fIg\fP\fB:\fP\fIe\fP with parameters and lifetime as for
.BR \-user .
This command is usually run as user root on the qmaster host.
.\"
.IP "\fBsge_ca \-usercert\fP \fIuser file\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP] [\fB\-encryptkey\fP] [\fB\-sha1\fP]"
Usually \fBsge_ca\fP \fB\-usercert\fP \fIuser file\fP is run as user root on the master host. The argument \fIuser file\fP contains a list of users in the following format:

.RS 0
         eddy:Eddy Smith:eddy@griders.org
.RS 0
         sarah:Sarah Miller:sarah@griders.org
.RS 0
         leo:Leo Lion:leo@griders.org
.IP
where the fields separated by colon are:
.RS 0
         Unix user:Gecos field:email address
.\"
.IP "\fBsge_ca \-renew\fP \fIuser\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP]"
Renew the certificate for \fIuser\fP. By default the certificate is extended for 365 days or for \fIdays\fP specified
with \fB\-days\fP \fIdays\fP. If the value is negative the certificate becomes invalid.
This command is usually run as user root on the qmaster host. $CATOP
and $CALOCALTOP may be overruled by \fB\-cadir\fP, \fB\-catop\fP, and
\fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-renew_ca\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP]"
Renew the CA certificate, similarly to
.BR \-renew .
.\"
.IP "\fBsge_ca \-renew_sys\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP]"
Renew the xxQS_NAMExx daemon certificate, similarly to
.BR \-renew .
.\"
.IP "\fBsge_ca \-renew_sdm\fP \fIg\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP]"
Renew the SDM daemon certificate of \fIg\fP, where \fIg\fP is the common name of the daemon, similarly to
.BR \-renew .
.\"
.IP "\fBsge_ca \-pkcs12\fP \fIuser\fP [\fB\-pkcs12pwf\fP \fIfile\fP] [\fB\-pkcs12dir\fP \fIdir\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Export certificate and key of user \fIuser\fP (Unix user name) in
PKCS12 format. This command is usually run as user root on the qmaster
host. If \fB\-pkcs12pwf\fP \fIfile\fP is used, the file and the
corresponding key will be encrypted with the password in
\fIfile\fP. If \fB\-pkcs12dir\fP \fIdir\fP is used, the output file is
written into \fIdir\fP/\fIuser\fP.p12 instead
of ./\fIuser\fP.p12. $CATOP and $CALOCALTOP may be overruled by
\fB\-cadir\fP, \fB\-catop\fP, and \fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-sys_pkcs12\fP [\fB\-pkcs12pwf\fP \fIfile\fP] [\fB\-pkcs12dir\fP \fIdir\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Export certificate and key of xxQS_NAMExx daemon in PKCS12 format,
similarly to
.BR \-pkcs12 .
.\"
.IP "\fBsge_ca \-sdm_pkcs12\fP \fIg\fP [\fB\-pkcs12pwf\fP \fIfile\fP] [\fB\-pkcs12dir\fP \fIdir\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Export certificate and key of SDM daemon with common name \fIg\fP in PKCS12 format,, similarly to
.BR \-renew .
.\"
.IP "\fBsge_ca \-ks\fP \fIuser\fP [\fB\-ksout\fP \fIfile\fP] [\fB\-kspwf\fP \fIfile\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Create a keystore containing certificate and key of user \fIuser\fP in
JKS format where \fIuser\fP is the Unix user name. This command is
usually run as user root on the qmaster host. If \fB\-kspwf\fP
\fIfile\fP is used the keystore and the corresponding key will be
encrypted with the password in \fIfile\fP. The \fB\-ksout\fP
\fIfile\fP option specifies the keystore file that is created. If the
\fB\-ksout\fP \fIfile\fP option is missing the default location for
the keystore is $CALOCALTOP/userkeys/\fIuser\fP/keystore. This command
is usually invoked by \fBsge_ca \-userks\fP. A prerequisite is a valid
JAVA_HOME environment variable setting. $CATOP and $CALOCALTOP may be
overruled by \fB\-cadir\fP, \fB\-catop\fP and \fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-userks\fP [\fB\-kspwf\fP \fIfile\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Generate a keystore in JKS format for all users having a key and certificate.
This command is usually run as user root on the qmaster host.
If \fB\-kspwf\fP \fIfile\fP is used, the keystore and the corresponding key will be encrypted with the password in \fIfile\fP.
The keystore files are created in $CALOCALTOP/userkeys/\fIuser\fP/keystore. This command is run after user certificates and keys have been created with \Bsge_ca \-usercert\fP \fIuserfile\fP or if any of the certificates have been renewed. $CATOP and $CALOCALTOP may be overruled by \fB\-cadir\fP, \fB\-catop\fP and \fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-sysks\fP [\fB\-kspwf\fP \fIfile\fP] [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Generate a keystore containing the xxQS_NAMExx daemon certificate and key in JKS format.
This command is usually run as user root on the qmaster host.
If \fB\-kspwf\fP \fIfile\fP is used the keystore and the corresponding key will be encrypted with the password in \fIfile\fP.
The keystore file is created in $CALOCALTOP/private/keystore. $CATOP and $CALOCALTOP may be overruled by \fB\-cadir\fP, \fB\-catop\fP and \fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-print\fP \fIcert\fP"
Print a PEM-format certificate \fIcert\fP.
.\"
.IP "\fBsge_ca \-printkey\fP \fIkey\fP"
Print a PEM-format key \fIkey\fP.
.\"
.IP "\fBsge_ca \-printcrl\fP \fIcrl\fP"
Print a PEM-format certificate revocation list \fIcrl\fP.
.\"
.IP "\fBsge_ca \-req\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP] [\fB\-encryptkey\fP] [\fB\-sha1\fP] [\fB\-outdir\fP \fIdir\fP]"
Create a private key and a certificate request for the calling user. These are created as newkey.pem and newreq.pem in the current working directory.
If the option \fP\-outdir\fP \fIdir\fP is specified in addition the files are created in \fIdir\fP.
.\"
.IP "\fBsge_ca \-sign\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP] [\fB\-days\fP \fIdays\fP] [\fB\-encryptkey\fP] [\fB\-sha1\fP] [\fB\-outdir\fP \fIdir\fP]"
Sign a certificate request. The CA certificate under $CATOP (default
$SGE_ROOT/$SGE_CELL/common/sgeCA), and CA key from
$CALOCALTOP (default /var/sgaCA/{port$SGE_QMASTER_PORT|sge_qmaster}/$SGE_CELL) are used for the signature.
If $CATOP and $CALOCALTOP are set to a different directory the information there is used. The certificate is created as newcert.pem in the current working directory or
in \fIdir\fP if the option \fB\-outdir\fP \fIdir\fP has been specified. In addition the option "\fB\-days\fP \fInumber of days\fP" can be specified to change the default validity from 365 to
number of days.
.\"
.IP "\fBsge_ca \-verify\fP \fIcert\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP] [\fB\-adminuser\fP \fIadmin\fP]"
Verify a certificate's validity where \fIcert\fP is the certificate in pem format. $CATOP and $CALOCALTOP can be overruled by \fB\-cadir\fP, \fB\-catop\fP and \fB\-calocaltop\fP.
.\"
.IP "\fBsge_ca \-copy\fP [\fB\-cadir\fP \fIdir\fP] [\fB\-catop\fP \fIdir\fP] [\fB\-calocaltop\fP \fIdir\fP]"
Run by a user to copy their certificate and key on the master host to
$HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/certs/cert.pem and the
corresponding private key to
$HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/private/key.pem, which are
used instead of the files in $CATOP and $CALOCALTOP. The command is
only recommended for testing purposes, or where $HOME is on a secure
shared file system.
.\" 
.br
.br
.SH EXAMPLES
.IP "# sge_ca \-init \-cadir /tmp \-sha1 \-encryptkey \-days 31"
Create a CA infrastructure in /tmp with a certificate validity of 31
days using SHA-1 instead of MD5 as message digest. The keys are encrypted and a passphrase has to be entered during the creation of the different keys or during signing a certificate with the created CA key.
.IP "# sge_ca \-usercert /tmp/myusers.txt \-cadir /tmp"
/tmp/myusers.txt contains
.br
user1:My User:user1@myorg.org
.br
and user1 is a valid Unix user account. Create a key and certificate for user1.
.IP "# sge_ca \-userks \-cadir /tmp"
Create a keystore for all users of the simple CA. The keystore is stored under /tmp/userkeys/\fIuser\fP/keystore.
.IP "# sge_ca \-renew root \-cadir /tmp \-days \-1"
Make the root certificate temporarily invalid.
.IP "# sge_ca \-renew_ca \-days 365 \-cadir /tmp"
Renew the CA certificate for 365 days.
.SH "ENVIRONMENT VARIABLES"
.\" 
.IP "\fBSGE_ROOT\fP" 1.5i
Specifies the location of the xxQS_NAMExx standard configuration
files.
.\"
.IP "\fBSGE_CELL\fP" 1.5i
If set, specifies the default xxQS_NAMExx cell.
.\"
.\"
.SH RESTRICTIONS
The command must usually be called with xxQS_NAMExx root permissions on the master host.
For more details on the permission requirements consult the detailed description for the different commands above.
.\"
.\"
.SH FILES
\fBsge_ca\fP creates a file tree starting in \fB$CATOP\fP and \fB$CALOCALTOP\fP. The default for \fB$CATOP\fP is usually $SGE_ROOT/$SGE_CELL/common/sgeCA and for \fB$CALOCALTOP\fP /var/lib/sgeCA/{port$SGE_QMASTER_PORT|sge_qmaster}/$SGE_CELL where the subpaths beginning with $ expand to the content of the corresponding environment variable.
.PP
In addition there may optionally exist the user certificate in $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/certs/cert.pem and the corresponding private key in $HOME/.sge/port$SGE_QMASTER_PORT/$SGE_CELL/private/key.pem which are used instead of the files in $CATOP and $CALOCALTOP. (See \fBsge_ca \-copy\fP above.) 
.PP
.IR SGE_ROOT/util/sgeCA/sge_ssl_template.cnf :
OpenSSL configuration file.
.PP
.IR SGE_ROOT/util/sgeCA/sge_ssl.cnf :
OpenSSL configuration file used for signing.
.\"
.\"
.SH "SEE ALSO"
.M xxqs_name_sxx_qmaster 8 .
.\"
.SH "COPYRIGHT"
See
.M xxqs_name_sxx_intro 1
for a full statement of rights and permissions.