|
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 GENCERTWhen 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 GENCERTWhen 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 GENCERTSituation |
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 GENCERTSituation |
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 GENCERTSituation |
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 GENCERTWhen 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 SPECIAL attribute,
or sufficient authority to the IRR.DIGTCERT.ADD and IRR.DIGTCERT.GENCERT
resources in the FACILITY class based on the certificate owner and
the SIGNWITH value, as shown in Table 7.
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) or PCICC, 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 functionSIGNWITH |
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 |
Authority processing details: RACF performs two checks that determine the
authority required for the GENCERT command: - 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.
- 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
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:
|
---|
RACDCERT GENCERT [ (request-data-set-name) ]
[ ID(certificate-owner) | SITE | CERTAUTH ]
[ SUBJECTSDN(
[ CN('common-name') ]
[ T('title') ] [ OU('organizational-unit-name1'
, 'organizational-unit-name2', …)
[ O('organization-name') ]
[ L('locality') ]
[ SP('state-or-province') ]
[ C('country') ]
) ]
[ SIZE(key-size) ]
[ NOTBEFORE( [ DATE(yyyy-mm-dd) ] [ TIME(hh:mm:ss) ] ) ]
[ NOTAFTER( [ DATE(yyyy-mm-dd) ] [ TIME(hh:mm:ss) ] ) ]
[ WITHLABEL('label-name') ]
[ SIGNWITH( [ CERTAUTH | SITE ] LABEL('label-name') ) ] [ { RSA [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) ) ] | NISTECC [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) ) ] | BPECC [ (PKDS [ (pkds-label | * ) ] | TOKEN(token-name) })
| DSA
| FROMICSF(pkds-label)
| PCICC [ (pkds-label | * ) ]
| ICSF [ (pkds-label | * ) ] } ]
[ KEYUSAGE(
[ CERTSIGN ]
[ DATAENCRYPT ]
[ DOCSIGN ]
[ HANDSHAKE ]
[ KEYAGREE ]
) ]
[ ALTNAME(
IP(numeric-IP-address)
DOMAIN('internet-domain-name')
EMAIL('email-address')
URI('universal-resource-identifier')
) ]
|
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), BPECC(PKDS), ICSF, or PCICC 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 1024 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. When the signing key is a DSA type, the SHA-1
algorithm is used for keys of all sizes. When the signing key is an
RSA, NISTECC, or BPECC type, the size of the signing key determines
the hashing algorithm used for signing, as follows: Hashing algorithm
used for signing
|
Signing key
size |
---|
RSA |
NISTECC |
BPECC |
---|
SHA-1 |
Less than 2048 bits |
— |
— |
SHA-256 |
2048 bits or
longer
|
192, 224,
or 256 bits
|
160, 192, 224,
256, or 320 bits
|
SHA-384 |
— |
384 bits |
384 bits |
SHA-512 |
— |
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.
- 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 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.
- The RSA(PKDS), PCICC or RSA(TOKEN) keywords provide
the best performance and support RSA key sizes up to 4096 bits. RSA(PKDS)or
PCICC require a PCI-class cryptographic coprocessor; RSA(TOKEN) requires
Enterprise PKCS#11 cryptographic coprocessor.
- The ICSF keyword can be used on a PCI-class cryptographic coprocessor
or the older cryptographic coprocessor. However, the key size is limited
to 1024 bits.
- 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 | *)]
- Specifies the same function as the PKDS suboperand of the RSA
operand. See the RSA operand of GENCERT for details.
Note: IBM
Recommends that you use RSA (PKDS[(pkds-label | *)]
in lieu of PCICC[(pkds-label | *)].
- ICSF[(pkds-label | *)]
- 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.
- 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 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. |
|
Example 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(2020/08/10))
|
Output |
None. (See the PKDS label generated by RACF using the RACDCERT LIST command
in Figure 1.) |
|
Example 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. |
|
Example 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. |
|
Example 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.) |
|
Example 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 |
|