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.
- 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
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 |
- 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
- 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, or
- Sufficient authority to the appropriate resources in the RDATALIB class, as shown in Table 2, if Granular Authority Checking has been enabled by defining the IRR.RACDCERT.GRANULAR resource in the RDATALIB class.
- 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.
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. |
READ access to the resource based on cert owner and cert label * | Purpose |
---|---|
IRR.DIGTCERT.<cert owner>.<cert label>.UPD.GENREQ | Generate a request based on a certificate with specified <cert label> owned by <cert owner> |
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')) |
|
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 | Activity label | Description |
---|---|---|
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 |
|
|
Output | None. |