RACDCERT GENCERT (Generate certificate)

Purpose

Use the RACDCERT GENCERT command to create a digital certificate and potentially a public/private key pair.

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.

Processing details

When you specify an optional request data set containing the PKCS #10 request data, and extensions are present in the request data (not overridden by other keywords specified with the RACDCERT command), they are copied to the certificate being created. These extensions and the logic involved with using them are described in the following tables:

Table 1. Logic for the subjectKeyIdentifier extension for GENCERT
When the request data set is specified When the request data set is not specified
The extension is encoded using the subjectKeyIdentifier value from the request data set if present, if not present the extension is encoded by generating the keyIdentifier according to the Public Key Infrastructure Standards. The extension is encoded by generating the keyIdentifier according to Public Key Infrastructure Standards.
Table 2. Logic for the authorityKeyIdentifier extension for GENCERT
When SIGNWITH is specified When SIGNWITH is not specified
The extension is encoded using the subjectKeyIdentifier value of the signing certificate if present, if not present the extension is not created. The authorityKeyIdentifier extension is not created.
Table 3. Logic for the keyUsage extension for GENCERT
Situation keyUsage is present in the request data set keyUsage is not present in the request data set
When KEYUSAGE is specified and the target ID is CERTAUTH If the certSign bit is turned off in the request data set, the request will fail. Otherwise the extension is encoded as requested by the RACDCERT invoker. Additionally, the certSign and cRLSign bits will be turned on if not already specified by the CERTSIGN keyword. The extension is encoded as requested by the RACDCERT invoker. Additionally, the certSign and cRLSign bits are turned on.
When KEYUSAGE is specified and the target ID is SITE or ID(cert-owner) The extension is encoded as requested by the RACDCERT invoker. The extension is encoded as requested by the RACDCERT invoker.
When KEYUSAGE is not specified and the target ID is CERTAUTH If the certSign bit is turned off this command fails, otherwise the extension is encoded as specified in the request data set. The extension is encoded by turning the certSign and cRLSign bits on.
When KEYUSAGE is not specified and the target ID is SITE or ID(cert-owner) The extension is encoded using the request data set values. The keyUsage extension is not created.
Table 4. Logic for the basicConstraints extension for GENCERT
Situation basicConstraints is present in the request data set basicConstraints is not present in the request data set
When the target ID is CERTAUTH If the cA boolean value is false, the command will fail. Otherwise the extension is encoded turning the cA bit on. The pathLength value is not included. The extension is encoded turning the cA bit on. The pathLength value is not included.
When the target ID is SITE or ID(cert-owner) The extension is encoded using the request data set values, including the pathLength value. The basicConstraints extension is not created.
Table 5. Logic for the subjectAltName extension for GENCERT
Situation subjectAltName is present in the request data set subjectAltName is not present in the request data set
When ALTNAME is specified The extension is encoded as requested by the RACDCERT invoker. The extension is encoded as requested by the RACDCERT invoker.
When ALTNAME is not specified The extension is encoded using the request data set values. The subjectAltName extension is not created.
Table 6. Logic for the issuerAltName extension for GENCERT
When SIGNWITH is specified When SIGNWITH is not specified
The extension is encoded using the subjectAltName value of the signing certificate if the extension is present. Otherwise, the issuerAltName extension is not created. The IssuerAltName extension is not created.

Issuing options

The following table identifies the eligible options for issuing the RACDCERT GENCERT 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 GENCERT command, you must have the following authorizations:
  • The SPECIAL attribute, or
  • Sufficient authority to the IRR.DIGTCERT.ADD and IRR.DIGTCERT.GENCERT resource in the FACILITY class,based on the certificate owner and the SIGNWITH value, as shown in Table 7, or
  • Sufficient authority to the appropriate resources in the RDATALIB class, as shown in Table 8, if Granular Authority Checking has been enabled by defining the IRR.RACDCERT.GRANULAR resource in the RDATALIB class.

When you specify the name of the request data set that contains the PKCS #10 request data, you must also have READ access to the specified data set.

When your installation controls access to ICSF services and the CSFSERV class is active, additional access to CSFSERV resources might be required as follows:
  • When you specify RSA(PKDS), you must have READ authority to the CSFDSG, CSFIQF, CSFPKG, CSFPKRC, and CSFPKX resources.
  • When you specify RSA(TOKEN(token-name)), you must have READ authority to the CSF1GAV, CSF1GKP, CSF1TRD, CSFDSG, and CSFIQF resources.
  • When you specify RSA (or omit key type) and omit PKDS and TOKEN, you must have READ authority to the CSFIQF resource.
  • When you specify NISTECC or BPECC, you must have the following access authorities:
    • When you specify PKDS, you must have READ access to the CSFDSG, CSFDSV, CSFOWH, CSFPKG, CSFPKRC, and CSFPKX resources.
    • When you specify TOKEN, you must have READ access to the CSF1GAV, CSF1GKP, CSF1PKV, CSF1TRC, CSF1TRD, CSFDSG, and CSFOWH resources.
    • When you omit PKDS and TOKEN, you must have READ access to the CSF1GAV, CSF1GKP, CSF1PKS, CSF1PKV, CSF1TRC, CSF1TRD, and CSFOWH resources.
  • When you specify ICSF, you must have READ authority to the CSFIQF, CSFPKI, and CSFPKRC resources.
  • When you specify FROMICSF, you must have READ authority to the CSFIQF and CSFPKX resources.
  • When you specify SIGNWITH, you must have the following access authorities:
    • If the private key of the signing certificate is an ECC key that is stored in the RACF data base, you must have READ authority to the CSF1PKS, CSF1PKV, CSF1TRC, CSF1TRD, and CSFOWH resources.
    • If the private key of the signing certificate is stored in the ICSF PKA key data set (PKDS) or in the ICSF Token Data Set (TKDS), you require additional access based on the key type, as follows:
      • When the key is an RSA type, you must have READ authority to the CSFDSG resource.
      • When the key is an ECC type, you must have READ authority to the CSF1PKV, CSF1TRC, CSF1TRD, CSFDSG, and CSFOWH resources.

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

Important: The GENCERT function allows a user to generate and sign a certificate. Carefully consider which users are authorized to use GENCERT, which user ID is associated with the generated certificate, and which certificate is used to sign the generated certificate.

Table 7. Authority required for the RACDCERT GENCERT function under the FACILITY class
SIGNWITH Your own certificate Another user's certificate SITE or CERTAUTH certificate
SIGNWITH your own certificate READ authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.GENCERT UPDATE authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.GENCERT CONTROL authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.GENCERT
SIGNWITH a SITE or CERTAUTH certificate READ authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.GENCERT UPDATE authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.GENCERT CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.GENCERT
SIGNWITH not specified READ authority to IRR.DIGTCERT.ADD and READ authority to IRR.DIGTCERT.GENCERT UPDATE authority to IRR.DIGTCERT.ADD and UPDATE authority to IRR.DIGTCERT.GENCERT CONTROL authority to IRR.DIGTCERT.ADD and CONTROL authority to IRR.DIGTCERT.GENCERT
Table 8. Authority required for the RACDCERT GENCERT function under the RDATALIB class when IRR.RACDCERT.GRANULAR is defined
READ access to the resource based on cert owner and cert label * Purpose
IRR.DIGTCERT.<cert owner>.<cert label>.UPD.GENCERT Create a certificate under <cert owner> with specified <cert label>
IRR.DIGTCERT.<cert owner>.LABEL*.UPD.GENCERT Create a certificate under <cert owner> with no label specified.
IRR.DIGTCERT.<cert owner>.<cert label>.UPD.GENCERT
and
IRR.DIGTCERT.<signer id>.<signer cert label> .UPD.GENCERT
 Create a certificate under <cert owner> with specified <cert label> signed by <signer cert label> owned by <signer id>
* 'cert owner' is the RACF user ID, or CERTIFAUTH (for CERTAUTH), or SITECERTIF (for SITE); 'signer id' is CERTIFAUTH or SITECERTIF
Authority processing details under the Facility class: RACF performs two checks that determine the authority required for the GENCERT command:
  1. How the certificate is being signed, specified with the SIGNWITH keyword.

    Users with SPECIAL authority can use the SIGNWITH keyword with any value. Users without SPECIAL authority must have authority to the IRR.DIGTCERT.GENCERT resource in the FACILITY class. If SIGNWITH is specified without the CERTAUTH or SITE keyword, the certificate is signed with the certificate identified with the LABEL keyword for the user who is issuing the RACDCERT command. This requires READ access to the resource IRR.DIGTCERT.GENCERT in the FACILITY class. If either SIGNWITH(CERTAUTH...) or SIGNWITH(SITE) is specified, CONTROL authority is required to the resource IRR.DIGTCERT.GENCERT in the FACILITY class.

    Not specifying SIGNWITH indicates that the certificate is to be self-signed. The signing key is owned by the certificate itself. Thus the authority needed for signing is determined by the owner of the generated certificate.

  2. What type of certificate is being generated, which is specified with the ID(), SITE or CERTAUTH keywords.

    Users with SPECIAL authority can generate a digital certificate for any RACF-defined user or for any certificate-authority or site certificate. Users without SPECIAL authority can generate certificate authority or site certificates if they have CONTROL authority to the resource IRR.DIGTCERT.ADD in the FACILITY class. Users without SPECIAL authority can generate certificates for other users if they have UPDATE authority to the resource IRR.DIGTCERT.ADD in the FACILITY class. Users without SPECIAL authority can generate certificates for themselves if they have READ authority to the resource IRR.DIGTCERT.ADD in the FACILITY class.

Activating your changes

If the DIGTCERT class is RACLISTed, refresh the class to activate your changes.

Example: 
SETROPTS RACLIST(DIGTCERT) REFRESH

Related commands

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 GENCERT command is:

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

GENCERT
GENCERT(request-data-set-name)
Request-data-set-name is the name of an optional data set that contains the PKCS #10 certificate request data. The request data contains the user's generated public key and X.509 distinguished name. The request data must be signed, DER-encoded, and then Base64 encoded according to the PKCS #10 standard.

The subkeywords of the GENCERT function specify the information that is to be contained within the certificate that is being created.

Request-data-set-name has characteristics (for example, RECFM) identical to the data set that can be specified with the ADD and CHECKCERT keywords. If request-data-set-name is specified, SIGNWITH must also be specified because the request-data-set-name data set does not contain a private key. If SIGNWITH is not specified, an informational message is issued. Note that the issuer of the RACDCERT command must have READ access to the request-data-set-name data set to prevent an authorization abend from occurring when the data set is read.

When GENCERT is issued with a request data set: The following conditions apply:
  • No key-pair is generated. This is because the request data set contains the user's public key.
  • The public key from the request data set is used in the generated certificate.
  • If FROMICSF is specified, the GENCERT command fails.
  • If the RSA, NISTECC, BPECC, or DSA keyword is specified, it is ignored.
  • If the RSA(PKDS), NISTECC(PKDS), or BPECC(PKDS) keyword is specified, it is ignored unless one of the following conditions is true:
    • The certificate profile (containing the private key of the corresponding public key) in the request data set already exists and the private key is not yet stored in the PKDS. When this occurs, RACF stores the private key in the ICSF PKDS.
    • There is no corresponding private key profile and you specified a PKDS label value. When this occurs, RACF stores the public key in the ICSF PKDS.
ID(certificate-owner) | SITE | CERTAUTH
Specifies that the new 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.
SUBJECTSDN
Specifies the subject's X.509 distinguished name, which consists of the following components:
  • CommonName - specified with the CN subkeyword.
  • Title - specified with the T subkeyword.
  • Organizational Unit - specified with the OU subkeyword. Multiple values can be specified for the organizational unit.
  • Organization - specified with the O subkeyword.
  • Locality - specified with the L subkeyword.
  • State/Province - specified with the SP subkeyword.
  • Country - specified with the C subkeyword.
SUBJECTSDN completely overrides the values contained in the certificate request in the data set specified with the GENCERT function.

The length of the value you specify for each component of the SUBJECTSDN is limited to 64 characters. Each SUBJECTSDN subkeyword can be specified only once. The total length of the subject's distinguished name is limited to 1024 characters, including the X.509 identifiers (such as C= and CN=) and the dot qualifiers.

If the SUBJECTSDN name is too long, an informational message is issued and the certificate is not added.

Any printable character that can be mapped to an ASCII character can be specified. Characters that cannot be mapped, such as X'4A' (¢) and X'00' are shown by RACDCERT LIST as blanks.

If SUBJECTSDN and request-data-set-name are not specified, the programmer name data from the ID() user (either specified or defaulted), or the programmer name from the SITE or CERTAUTH anchor user IDs (irrsitec or irrcerta) is used as the common name (CN). If the programmer name is all blanks (X'40'), nulls (X'00'), # characters (X'7B'), or X'FF' characters, the common name is set to the user ID that is to be associated with this certificate.

SIZE(key-size)
Specifies the size of the private key expressed in decimal bits. This keyword is ignored if GENCERT is specified with request-data-set-name.

If SIZE is not specified, it defaults to 2048 for RSA and DSA keys, or 192 for NISTECC and BPECC keys.

For NISTECC keys, valid key sizes are 192, 224, 256, 384, and 521 bits. For BPECC keys, valid key sizes are 160, 192, 224, 256, 320, 384, and 512 bits.

For DSA keys, the minimum key size is 512.

For RSA keys, the minimum key size for clear keys and secure keys in the PKDS (PKA key data set) is 512; the minimum key size for secure keys in the TKDS (token key data set) is 1024 and the size must be a multiple of 256.

  • The maximum key size for RSA and DSA keys is determined by United States export regulations and is controlled by RACF and non-RACF code in z/OS. Depending on the installation, non-RACF code may enforce a lower maximum size.
  • Rounding up to the next appropriate key size might occur. Therefore, the key size of the generated key might be longer than the value you specify with SIZE but the generated key is never shorter than requested.
Maximum key sizes: The maximum key size for a private key depends on key type, as follows:
Private key type Maximum key size
RSA key stored in the RACF database 4096 bits
RSA key stored in the ICSF TKDS as secure key 4096 bits
RSA key stored in the ICSF PKDS as a CRT key token 4096 bits
DSA key 2048 bits
RSA key stored in the ICSF PKDS as an ME key token 1024 bits
NISTECC key 521 bits
BPECC key 512 bits

Note: To generate an RSA key that is longer than 1024 bits and is to be stored in the RACF database, the CP Assist for Cryptographic Function (CPACF) must be enabled.

Standard key sizes: Currently, standard sizes for RSA keys are as follows:

Key size Key strength
 512 bits Low-strength key
1024 bits Medium-strength key
2048 bits High-strength key
4096 bits Very high-strength key

Key strength considerations: Shorter keys of the ECC type, which are generated when you specify NISTECC or BPECC, achieve comparable key strengths when compared with longer RSA keys.

RSA, NISTECC, and BPECC keys of the following sizes are comparable in strength:
RSA key size NISTECC key size BPECC key size
 1024 bits 192 bits 160 or 192 bits
 2048 bits 224 bits 224 bits
 3072 bits 256 bits 256 or 320 bits
 7680 bits 384 bits 384 bits
15360 bits 521 bits 512 bits
Hashing algorithm used for signing: RACF signs certificates using a set of secure hash algorithms based on the SHA-1 or SHA-2 hash functions. The size of the signing key determines the hashing algorithm used for signing, as follows:
Hashing algorithm
used for signing
 Signing key size
RSA / DSA RSAPSS for RSA signing key NISTECC BPECC
SHA-1 Less than 2048 bits — — —
SHA-256
2048 bits or
longer
2048 bits or
longer and less than 3072 bits
192, 224,
or 256 bits
160, 192, 224,
256, or 320 bits
SHA-384 —
3072 bits or
longer and less than 4096 bits
 384 bits 384 bits
SHA-512 — 4096 bits 521 bits 512 bits
NOTBEFORE(DATE(yyyy-mm-dd) TIME(hh:mm:ss))
Specifies the local date and time from which the certificate is valid. If DATE is not specified, it defaults to the current local date. If TIME is not specified, it defaults to TIME(00:00:00).

If DATE is specified, the value of yyyy must be 1950 - 9997.

Note that the use of the date format yyyy-mm-dd is valid. However, to aid installations familiar with the RACF date format, the value can be specified in the format yyyy/mm/dd.

The time and date values are stored in the certificate as a universal time coordinated (UTC) value. The calculated UTC value might be incorrect if the date and time values for NOTBEFORE and NOTAFTER represent a time that has a different local offset from UTC.

NOTAFTER(DATE(yyyy-mm-dd) TIME(hh:mm:ss))
Specifies the local date and time after which the certificate is no longer valid. If DATE is not specified, it defaults to one year from the NOTBEFORE date value. If TIME is not specified, it defaults to TIME(23:59:59).

If DATE is specified, the value of yyyy must be 1950 - 9997. If DATE is defaulted, the value must be 1951 - 9998.

The NOTBEFORE value must be earlier than the NOTAFTER value or an informational message is issued.

Note the use of the date format yyyy-mm-dd is valid. However, to aid installations familiar with the RACF date format, the value can be specified as yyyy/mm/dd.

The time and date values are stored in the certificate as a universal time coordinated (UTC) value. The calculated UTC value might be incorrect if the date and time values for NOTBEFORE and NOTAFTER represent a time that has a different local offset from UTC.

WITHLABEL('label-name')
Specifies the label assigned to this certificate. If specified, this must be unique to the user ID with which the certificate is associated. If not specified, it defaults in the same manner as the WITHLABEL keyword on the RACDCERT ADD command.

The label-name is stripped of leading and trailing blanks. If a single quotation mark is intended to be part of the label-name, use two single quotation marks together for each single quotation mark within the string, and enclose the entire string within single quotation marks.

See the WITHLABEL keyword for RACDCERT ADD for information on label rules.

SIGNWITH(CERTAUTH LABEL('label-name'))
SIGNWITH(SITE LABEL('label-name'))
SIGNWITH(LABEL('label-name'))
Specifies the certificate with a private key that is signing the certificate. If not specified, the default is to sign the certificate with the private key of the certificate that is being generated. This creates a self-signed certificate. The signing certificate must belong to the user ID executing the command, or SITE or CERTAUTH. If SITE and CERTAUTH keywords are omitted, the signing certificate owner defaults to the user ID of the command issuer.

If SIGNWITH is specified, it must refer to a certificate that has a private key associated with it. If no private key is associated with the certificate, an informational message is issued and processing stops.

If you specify either request-data-set-name or FROMICSF, you must specify SIGNWITH.

Note that self-signed certificates are always trusted, while all other certificates are created with the trust status of the certificate specified in the SIGNWITH keyword. If the certificate specified in the SIGNWITH keyword is not trusted, an informational message is issued but the certificate is still generated.

Note: Prior to z/OS V2R4, the RSA private key was stored in the PKDS under the RSA master key. This key can not be used to sign with the RSAPSS algorithm without converting it to be a ECC master key protected key. You may use this conversion tool to convert it: Translate and replace an RSA key for RSA PSS.
RSA | PCICC | ICSF | DSA | NISTECC | BPECC | FROMICSF
Specifies if RACF should generate a new key pair, and if so, how to generate the key pair and where to store the private key for future use. The default action for a new key is to store it as a software key. If no keyword is specified, the key pair is generated using software with the RSA algorithm and the private key is stored in the RACF database as an RSA key.

Guidelines:

The PCICC and ICSF keywords are deprecated. IBM discourages the use of these parameters.

The following guidelines apply when choosing key options:
  • Choose RSA(PKDS), ICSF, PCICC or RSA(TOKEN) when the private key to be generated is an RSA type and you need hardware protection for the key.
    • The RSA(PKDS) keyword is equivalent to the PCICC keyword and stores the key as an RSA Chinese Remainder Theorem (CRT) key token. RACDCERT LIST will display this key with key type RSA along with a PKDS label.
    • The ICSF keyword stores the key as an RSA Modulus-Exponent (ME) key token. RACDCERT LIST will display this key with key type RSA Mod-Exp along with a PKDS label.
  • Specify RSA when the key to be generated is an RSA type but no hardware protection is needed. Such software keys can be up to 4096 bits in size.
  • Choose NISTECC or BPECC when the key to be generated is an ECC type.
  • Specify NISTECC(PKDS), BPECC(PKDS),NISTECC(TOKEN) or BPECC(TOKEN) when hardware protection is needed.
  • Choose DSA when the key to be generated is a DSA type. Note that no hardware protection is available for DSA keys.
When you issue GENCERT with a request data set: If the certificate you are generating is associated with a public or private key that is already stored in the PKDS, the following restriction applies:
  • Restriction: Respecifying the PKDS label with the RSA(PKDS), ICSF, PCICC, NISTECC(PKDS), or BPECC(PKDS) keyword does not change the existing PKDS label or key type. For example:
    • If the private key already exists in the PKDS as an RSA Modulus-Exponent (ME) key token, specifying RSA(PKDS) or PCICC does not convert the key to an RSA Chinese Remainder Theorem (CRT) key token.
    • If the private key already exists in the PKDS as an RSA Chinese Remainder Theorem (CRT) key token, specifying ICSF does not convert the key to an RSA Modulus-Exponent (ME) key token.

For details about specifying or allowing RACF to generate the PKDS label, see PKDS label considerations.

For the hardware requirements for storing or accessing a key in the ICSF PKA key data set (PKDS), see Hardware requirements.

RSA
Specifies that the key pair is to be generated using software with the RSA algorithm and the private key is to be stored in the RACF database as an RSA key. RSA is the default key type.

When you specify RSA without the PKDS option or accept RSA as the default key type, the CP Assist for Cryptographic Function (CPACF) must be enabled to generate a key that is longer than 1024 bits.

PKDS[(pkds-label | *)]
Specifies that the key pair is to be generated using a a CCA cryptographic coprocessor. The resulting private key is stored in the ICSF PKA key data set (PKDS) as an RSA Chinese Remainder Theorem (CRT) key token with either a system-generated label, a label specfied by pkds-label, or a label copied from the certificate label.
TOKEN (token-name)
Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS) as an RSA Chinese Remainder Theorem (CRT) key token.
PCICC[(pkds-label | *)]

This parameter is deprecated. IBM recommends that you use RSA(PKDS[pkds-label | *)]) instead of PCICC[(pkds-label | *)].

It specifies the same function as the PKDS suboperand of the RSA operand. See the RSA operand of GENCERT for details.
ICSF[(pkds-label | *)]

This parameter is deprecated. IBM discourages the use of this parameter, as it is only applicable to RSA keys that are limited to 1024 bits.

It specifies that the key pair is to be generated using software. The resulting private key is generated with the RSA algorithm and stored in the ICSF PKA key data set (PKDS) as an RSA Modulus-Exponent (ME) key token.
DSA
Specifies that the key pair is to be generated using software with the DSA algorithm. The resulting private key is stored in the RACF database as a DSA key. Note: DSA key generation can be very slow, especially for keys longer than 1024 bits.
NISTECC
Specifies that the key pair is to be generated using software if clear key is not restricted in the system, with the elliptic curve cryptography (ECC) algorithm in accordance with the standard proposed by the National Institute of Standards and Technology (NIST). The resulting private key is stored in the RACF database as an ECC key.

When specifying NISTECC, the ICSF subsystem must be operational and configured for PKCS #11 operations.

PKDS[(pkds-label | *)]
Specifies that the key pair is to be generated using a CCA cryptographic coprocessor. The resulting private key is stored in the ICSF PKA data set (PKDS) in the PKA token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
TOKEN (token-name)
Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS) as an RSA Chinese Remainder Theorem (CRT) key token.
BPECC
Specifies that the key pair is to be generated using software, if clear key is not restricted in the system, with the elliptic curve cryptography (ECC) algorithm in accordance with the standard proposed by the ECC Brainpool working group of the Internet Engineering Task Force (IETF). The resulting private key is stored in the RACF database as an ECC key.

When specifying BPECC, the ICSF subsystem must be operational and configured for PKCS #11 operations.

Restriction: When ICSF is operating in FIPS mode, you cannot generate a Brainpool ECC private key.

PKDS[(pkds-label | *)]
Specifies that the key pair is to be generated using a CCA cryptographic coprocessor. The resulting private key is stored in the ICSF PKA data set (PKDS) as an ECC key in the PKA token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
TOKEN (token-name)
Specifies that the key pair is to be generated using an Enterprise PKCS#11 cryptographic coprocessor. The resulting private key is stored in the specified existing token-name token in the ICSF token key data set (TKDS) as an RSA Chinese Remainder Theorem (CRT) key token.
FROMICSF(pkds-label)
Specifies that no new key pair is to be generated for this new certificate. Instead, RACF uses an existing public key specified by its PKDS label. The public key must reside in the ICSF PKA key data set (PKDS).

When you specify FROMICSF, you must also specify SIGNWITH to sign the new certificate with an existing certificate. The new certificate will contain no private key and therefore cannot be self-signed.

You cannot specify both request-data-set-name and FROMICSF.

Start of changeSIGATTR(attribute)End of change
Start of changeSpecifies the signing attribute if the signing key is an RSA key. The only valid value for attribute is RSAPSS. If attribute is not specified, the default value is RSAPSS.End of change
KEYUSAGE
Specifies the appropriate values for the keyUsage certificate extension, of which one or more of the values might be coded. For certificate authority certificates, the default is CERTSIGN and is always set. There is no default for certificates that are not certificate-authority certificates.
HANDSHAKE
Facilitates identification and key exchange during security handshakes, such as SSL, which set the digitalSignature and keyEncipherment indicators if the key algorithm is RSA. If key type is DSA, NISTECC, or BPECC, this usage sets only the digitalSignature indicator.
DATAENCRYPT
Encrypts data, which sets the dataEncipherment indicator. This usage is not valid for DSA, NISTECC, or BPECC keys.
DOCSIGN
Specifies a legally binding signature, which sets the nonRepudiation indicator.
CERTSIGN
Specifies a signature for other digital certificates and CRLs, which sets the keyCertSign and cRLSign indicators.
KEYAGREE
Facilitates key exchange, which sets the keyAgreement indicator. This usage is valid only for NISTECC and BPECC keys.

A certificate with no keyUsage value other than keyAgreement cannot be used for signing.

ALTNAME
Specifies the appropriate values for the subjectAltName extension, of which one or more of the values might be coded. If required for the extension, RACF converts the entered values to ASCII.
Note: RACF assumes the terminal code page is IBM-1047 and translates to ASCII accordingly.
IP(numeric-IP-address)
Specifies a fully qualified numeric IP address in IPv4 or IPv6 form.

IPv4 dotted decimal form consists of four decimal numbers (each number must be a value from 0 - 255) separated by periods:

Example: 9.117.2.45

IPv6 form consists of eight 16-bit blocks of hexadecimal characters separated by colons:

Example: ABCD:EF01:2345:6789:ABCD:EF01:2345:6789

In IPv6 form, leading zeros in each block are optional. Successive blocks of zeros can be represented by a single occurrence of ::.

Example: 2001:DB8::8:800:200C:417A

An IPv6 address can contain an IPv4 address:

Example: 0:0:0:0:0:ABCD:1.2.3.4

DOMAIN('internet-domain-name')
Specifies a quoted string containing a fully qualified 'internet-domain-name' (such as 'www.widgits.com'). RACF does not check this value's validity.
EMAIL('email-address')
Specifies a quoted string containing a fully qualified 'email-address', such as 'jasper at moes.bar.com'. RACF replaces the word at with the @ symbol (X'7C') to conform with RFC822. If RACF cannot locate the word at it assumes the address is already in RFC822 form and makes no attempt to alter it other than converting it to ASCII.
URI('universal-resource-identifier')
Specifies the 'universal-resource-identifier' (such as 'http://www.widgits.com'). RACF does not check the validity of this value.

Examples

Example Activity label Description
1 Operation User RACFADM requests the creation of a certificate-authority certificate, with values for the subjectAltName extension and the keyUsage extension, for the local certificate authority. The certificate will be self-signed and a SIGNWITH value need not be specified.
Known User RACFADM has CONTROL access authority to the IRR.DIGTCERT.* resource in the FACILITY class.
Command 
RACDCERT GENCERT 
  CERTAUTH 
  SUBJECTSDN(CN('Local CA')) 
  ALTNAME(IP(9.117.170.150) DOMAIN('www.widgits.com') 
  EMAIL('localca@www.widgits.com') 
  URI('http://www.widgits.com/welcome.html')) 
  KEYUSAGE(HANDSHAKE DATAENCRYPT DOCSIGN CERTSIGN) 
  WITHLABEL('Local PKIX CA')
Output None.
2 Operation User WENTING wants to create a new certificate with a 2048-bit public/private key pair so she can share encrypted data with a business partner. She wants to call her certificate Wen Ting's certificate.
Known IBM® Encryption Facility requires a PKDS label. RACF generates a default PKDS label when no value is specified with the PKDS keyword.
Command 
RACDCERT GENCERT 
  SUBJECTSDN(CN('Wen Ting''s certificate')) 
  WITHLABEL('Wen Ting''s certificate') 
  SIZE(2048) 
  RSA(PKDS) 
  NOTAFTER(DATE(2030/10/10))
Output None. (See the PKDS label generated by RACF using the RACDCERT LIST command in Figure 1.)
3 Operation User RACFADM wants to create a CA certificate that can be used to issue code-signing certificates for users who need to digitally sign programs.
Known User RACFADM has CONTROL access authority to the IRR.DIGTCERT.* resource in the FACILITY class, and appropriate authority in the CSFSERV and CSFKEYS classes to be able to use the PKDS option.
Command 
RACDCERT CERTAUTH GENCERT 
  SUBJECTSDN(OU('MyCompany Code Signing CA') O('MyCompany') C('US')) 
  SIZE(2048) RSA(PKDS) WITHLABEL('MyCompany Code Signing CA')
Output None.
4 Operation User RACFADM wants to issue a code-signing certificate to user RAMOS who needs to digitally sign programs. The new code-signing certificate will be signed by the CA certificate created in Example 3.
Known User RACFADM has CONTROL access authority to the IRR.DIGTCERT.* resource in the FACILITY class.
Command 
RACDCERT ID(RAMOS) GENCERT 
  SUBJECTSDN(CN('Ramos Code Signing Cert') O('MyCompany') C('US')) 
  SIZE(1024) WITHLABEL('Ramos Code Signing Cert') 
  SIGNWITH(CERTAUTH LABEL('MyCompany Code Signing CA')) 
  KEYUSAGE(HANDSHAKE DOCSIGN)
Output None.
5 Operation User ANNA wants to create a new certificate with an ECC private key. The new certificate will be called Anna's certificate. The key requires hardware protection so she will store it in the ICSF PKDS.
Known User ANNA has sufficient authority to the appropriate resources in the FACILITY and CSFSERV classes. The system contains an operational ICSF subsystem and Crypto Express3 coprocessor (CEX3C).
Command 
RACDCERT GENCERT 
  SUBJECTSDN(CN('COMPANY A')) 
  WITHLABEL('Anna''s certificate') 
  BPECC(PKDS(ECCKEY4ANNASCERTIFICATE))
Output None. (See a listing of this certificate in Figure 8.)
6 Operation User CLAUSEN wants to create a new certificate with an RSA private key. The new certificate will be called Christine Clausen's certificate. The key requires secure hardware protection so she will create the key in the ICSF TKDS.
Known User CLAUSEN has sufficient authority to the appropriate resources in the FACILITY, CRYPTOZ and CSFSERV classes. The token labelled COMPANYA.TOKEN has been defined. The system contains an operational ICSF subsystem and Crypto Express4 coprocessor (CEX4X).
Command 
RACDCERT GENCERT 
	SUBJECTSDN(CN('COMPANY A')) 
	WITHLABEL('Christine Clausen''s certificate') 
	RSA(TOKEN(COMPANYA.TOKEN))
Output None