RACDCERT GENREQ (Generate request)

Purpose

Use the RACDCERT GENREQ command to create a PKCS #10 Base64-encoded certificate request based on the specified certificate and write the request to a data set.

The specified certificate must have a private key associated with it. Otherwise an informational message is issued and processing stops.

The GENREQ syntax is RACDCERT GENREQ(LABEL('label-name')) DSN('output-data-set-name'), where label-name is the name of the certificate the request is based on. The generated request does not have a name. No key pair is generated during the GENREQ processing. It takes the subject's distinguished name, some of the extensions (indicated below) and the public key from the specified certificate and signed with the private key associated with the specified certificate to form the certificate request.

GENREQ requires that the certificate have a private key associated with it. If no private key is associated with the certificate, an informational message is issued and processing stops.

The certificate request contains the subject's distinguished name and public key, and is signed with the private key associated with the specified certificate. These are the extensions copied to the certificate request if they are present in the specified certificate:

subjectAltName
subjectKeyIdentifier
authorityKeyIdentifier
basicConstraints
keyUsage
extKeyUsage

Typically, these requests are sent to a certificate authority; however, they can also be imported into and signed by RACF® using the GENCERT function with a request-data-set-name.

See UTF-8 and BMP character restrictions for information about how UTF-8 and BMP characters in certificate names and labels are processed by RACDCERT functions.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT GENREQ command:

As a RACF TSO command?	As a RACF operator command?	With command direction?	With automatic command direction?	From the RACF parameter library?
Yes	No	No. (See rules.)	No. (See rules.)	No
Rules: The following rules apply when issuing this command. The RACDCERT command cannot be directed to a remote system using the AT or ONLYAT keyword. The updates made to the RACF database by RACDCERT are eligible for propagation with automatic direction of application updates based on the RRSFDATA profiles AUTODIRECT.target-node.DIGTCERT.APPL and AUTODIRECT.target-node.DIGTRING.APPL, where target-node is the remote node to which the update is to be propagated.

Authorization required

To issue the RACDCERT GENREQ command, you must have the SPECIAL attribute or sufficient authority to the IRR.DIGTCERT.GENREQ resource in the FACILITY class for your intended purpose, as shown in Table 1.

When your installation controls access to ICSF services and the CSFSERV class is active, additional access to CSFSERV resources might be required as follows:

If the certificate that the request is based upon has a private key stored in the ICSF PKA key data set (PKDS) or in the ICSF Token Data Set (TKDS), you must have READ access to the CSFDSG resource.
If the certificate that the request is based upon has an ECC private key stored in the RACF database, you must have READ access to the CSF1PKS, CSF1TRC, CSF1TRD, and CSFOWH resources.

For details about the CSFSERV resources, see z/OS Cryptographic Services ICSF Administrator's Guide.

Table 1. Authority required for the RACDCERT GENREQ function
IRR.DIGTCERT.GENREQ
Access level	Purpose
READ	Generate a request based on your own certificate.
UPDATE	Generate a request based on another user's certificate.
CONTROL	Generate a request based on a SITE or CERTAUTH certificate.

Related commands

To add a certificate, see RACDCERT ADD (Add certificate).
To generate a certificate, see RACDCERT GENCERT (Generate certificate).

Syntax

For the key to the symbols used in the command syntax diagrams, see Syntax of RACF commands and operands. The complete syntax of the RACDCERT GENREQ command is:


RACDCERT GENREQ(LABEL('label-name'))
[ ID(certificate-owner) \| SITE \| CERTAUTH ] DSN(output-data-set-name)

If you specify more than one RACDCERT function, only the last specified function is processed. Extraneous keywords that are not related to the function being performed are ignored.

If you do not specify a RACDCERT function, LIST is the default function.

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

Parameters

GENREQ(LABEL('label-name'))

Specifies the label of the certificate used to build the certificate request.

If the certificate has an associated ECC private key:

The ICSF subsystem must be operational and configured for PKCS #11 operations.
When keyAgreement is the only key usage, the certificate cannot be used for signing. Therefore, you cannot use GENREQ to create a certificate request based on the certificate nor create a self-signed certificate.

Restriction: When ICSF is operating in FIPS mode, you cannot use a certificate that has an associated Brainpool ECC private key.

ID(certificate-owner) | SITE | CERTAUTH

Specifies that the specified certificate is either a user certificate associated with the specified user ID, a site certificate, or a certificate-authority certificate. If you do not specify ID, SITE, or CERTAUTH, the default is ID, and certificate-owner defaults to the user ID of the command issuer. If more than one keyword is specified, the last specified keyword is processed and the others are ignored by TSO command parse processing.

DSN(output-data-set-name)

Specifies the data set that is to contain the certificate request. The data set output-data-set-name is deleted and reallocated if it exists. If you specify GENREQ, DSN must be specified.

Examples


Example 1	Operation	User WEBADM needs to create a certificate request based on the expiring certificate for a Web server application, and store it in an MVS data set called `'SYSADM.CERT.REQ'`. The user ID of the application is WEBSERV01 and its expiring certificate is labeled `'My Web Server Cert'`.
	Known	User WEBADM has UPDATE access authority to the IRR.DIGTCERT.GENREQ resource in the FACILITY class.
	Command	`RACDCERT GENREQ(LABEL('My Web Server Cert')) ID(WEBSRV01) DSN('SYSADM.CERT.REQ')`
	Output	None.