RACDCERT IMPORT (Import certificate)

Purpose

Use the RACDCERT IMPORT command to import a digital certificate (with its associated private key, if present) from a z/OS® PKCS #11 token and add it to RACF®.

The IMPORT function processes certificates in the same way as the ADD function with regard to re-adding and renewing certificates, replacing keys, and determining the trust status of certificates. For details, see Processing details in the RACDCERT ADD function.

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 IMPORT 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 IMPORT command, you must have SPECIAL attribute, or sufficient authority to the IRR.DIGTCERT.ADD resource in the FACILITY class based on the certificate owner, as shown in Table 1. You also must have sufficient authority to the appropriate resources in the CRYPTOZ class.

When your installation controls access to ICSF services and the CSFSERV class is active, you must have READ authority to the CSF1GAV and CSF1TRL resources in the CSFSERV class.

Additional access to CSFSERV resources might be required as follows:

If the certificate you are importing has an RSA key, you must also have the following access authorities:
- When you specify PKDS, ICSF, or PCICC, you must have READ access to the CSFIQF, CSFPKI, and CSFPKRC resources.
- When you omit PKDS, ICSF, and PCICC, you must have READ access to the CSFIQF resource.
If the certificate you are importing has an ECC key, you must also have the following access authorities:
- When you specify PKDS, you must have READ access to the CSFDSV, CSFOWH, CSFPKI, and CSFPKRC resources.
- When you omit PKDS, you must have READ access to the CSF1PKV, CSF1TRC, CSF1TRD, and CSFOWH resources.

If you are not authorized by ICSF (through the CRYPTOZ class) to access the specified token or not authorized by RACF (through the FACILITY class) to add the specified RACF certificate, the command stops and an error message is displayed.

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

Table 1. Authority required for the RACDCERT IMPORT function
Your own certificate	Another user's certificate	SITE or CERTAUTH certificate
Sufficient authority to CRYPTOZ resources and READ authority to IRR.DIGTCERT.ADD	Sufficient authority to CRYPTOZ resources and UPDATE authority to IRR.DIGTCERT.ADD	Sufficient authority to CRYPTOZ resources and CONTROL authority to IRR.DIGTCERT.ADD

Activating your changes

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

Example:

SETROPTS RACLIST(DIGTCERT) REFRESH

Related commands

To add a certificate, see RACDCERT ADD (Add 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 IMPORT command is:

RACDCERT IMPORT(TOKEN(token-name) SEQNUM(sequence-number))
[ ID(certificate-owner) \| SITE \| CERTAUTH ] [ WITHLABEL('label-name') ] [ TRUST \| NOTRUST \| HIGHTRUST ] [ PKDS[(pkds-label \| * )] \| PCICC[(pkds-label \| * )] \| ICSF[(pkds-label \| * )] ]

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

IMPORT TOKEN(token-name) SEQNUM(sequence-number)

Specifies the PKCS #11 token from which to import the specified certificate (and its associated private key, if present).

To import a certificate with 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.

If the certificate in the token you are importing has an associated ECC private key, the ICSF subsystem must be operational and configured for PKCS #11 operations.

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

TOKEN(token-name): Specifies the name of the token from which the certificate is being imported. When specifying the IMPORT operand, you must specify the TOKEN operand.
SEQNUM(sequence-number): Specifies the sequence number of the certificate being imported from the token. When specifying the IMPORT operand, you must specify the SEQNUM operand.

ID(certificate-owner) | SITE | CERTAUTH

Specifies that the target owner for the imported certificate is 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.

If the imported certificate has an ECC private key and keyAgreement is the only key usage, the certificate cannot be used for signing. Therefore, you cannot import it as a CERTAUTH certificate.

WITHLABEL('label-name')

Specifies the label to be associated with the imported certificate. Up to 32 characters can be specified. The label-name can contain blanks and mixed-case characters.

This label is used as a handle instead of the serial number and issuer's distinguished name. It can be used to store a descriptive text.

If the value specified in WITHLABEL already exists, RACDCERT returns a message indicating that the label has already been used. The certificate is not added.

If WITHLABEL is not specified, RACDCERT generates a label for the certificate. The generated label is of the form LABELnnnnnnnn, where nnnnnnnn is the first integer value, starting at 00000001 that generates a unique label name.

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.

TRUST | NOTRUST | HIGHTRUST

Specifies whether the status of the imported certificate is trusted, not trusted, or highly trusted.

For a detailed description, see the TRUST, NOTRUST, HIGHTRUST keyword for RACDCERT ADD.

PKDS | PCICC | ICSF

Specifies that RACF should store the public or private key associated with this certificate in the ICSF PKA key data set (PKDS). This applies when the key is introduced to RACF and when an existing certificate profile is replaced.

The default action for a new key is for RACF to store it as a software key in the RACF database, not in the ICSF PKDS. The default action for an existing key is to leave it unchanged.

If the private key already exists as a secure key in the token key data set (TKDS), you cannot import the private key and the certificate will be imported without the private key.

Guidelines for choosing PKDS, PCICC, or ICSF: When you need hardware protection for the private key, choose the PKDS, PCICC, or ICSF keyword based on key type, key size, and available cryptographic hardware.

The PKDS keyword supports both ECC and RSA private keys. For RSA keys, PKDS is equivalent to PCICC 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 supports only RSA keys and 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 PKDS and PCICC keywords provide the best performance and support RSA key sizes up to 4096 bits, but require a PCI-class cryptographic coprocessor.
The ICSF keyword can be used on a PCI-class cryptographic coprocessor or older cryptographic coprocessor. However, the key size is limited to 1024 bits.

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.

PKDS[(pkds-label | * )]

Specifies as follows, based on the key type of the public or private key:

For an RSA key:
If the token contains only a certificate, you must specify a pkds-label value or an asterisk (*). Otherwise the PKDS keyword is ignored and no PKDS entry is created. The public key is stored in the ICSF PKDS as an RSA Modulus-Exponent (ME) key token with the specified label.

If the certificate has no private key and you specify PKDS without a PKDS label and without an asterisk (*), the PKDS keyword is ignored and no PKDS entry is created.

If the token contains a PKCS #12 package, the private key is stored in the ICSF PKDS as an RSA Chinese Remainder Theorem (CRT) key token with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.

Note: If you want to store the RSA private key in the PKDS as an RSA Modulus-Exponent (ME) key token, specify ICSF instead of PKDS.
For an ECC key:
If the token contains only a certificate, you must specify a pkds-label value or an asterisk (*). Otherwise the PKDS keyword is ignored and no PKDS entry is created. The public key is stored in the ICSF PKDS with the specified label.

If the certificate has no private key and you specify PKDS without a PKDS label and without an asterisk (*), the PKDS keyword is ignored and no PKDS entry is created.

If the token contains a PKCS #12 package, the private key is stored in the ICSF PKDS with either a system-generated label, a label specified by pkds-label, or a label copied from the certificate label.
For a DSA key: The PKDS keyword is ignored.

PCICC[(pkds-label | * )]

Specifies the same function as the PKDS operand for an RSA key. See the PKDS operand of IMPORT for details.

ICSF[(pkds-label | * )]

Specifies that the public or private key is to be converted to an RSA Modulus-Exponent (ME) key token. The resulting key is stored in the ICSF PKDS.

If the certificate has no private key and you specify ICSF without a PKDS label and without an asterisk (*), the ICSF keyword is ignored and no PKDS entry is created.

Examples


Example 1	Operation	User NETB0Y wants to add a digital certificate to RACF and associate it with his own user ID. The certificate is labeled `Savings Account` and currently resides in the z/OS PKCS #11 token named `NETB0Y.TKN1`. The status of the certificate will be trusted.
	Known	User NETB0Y has READ access to the discrete profile named `IRR.DIGTCERT.ADD` in the FACILITY class, and READ access to the discrete profile named `USER.NETB0Y.TKN1` in the CRYPTOZ class. Using RACDCERT LISTTOKEN, user NETB0Y determined the sequence number of the certificate to be added is `3`.
	Command	`RACDCERT IMPORT(TOKEN(NETB0Y.TKN1) SEQNUM(3)) ID(NETB0Y) TRUST WITHLABEL('Savings Account')`
	Output	None.

Example 2	Operation	User RACFADM wants to add a digital certificate for NETB0Y and protect the 1024-bit RSA key by storing it in the ICSF PKDS. The certificate is labeled `RSA token` and currently resides in the z/OS PKCS #11 token named `NETB0Y.TKN2`. The status of the certificate will be trusted.
	Known	User RACFADM has SPECIAL authority, sufficient authority to resources in the CSFSERV class and READ access to the discrete profile named `USER.NETB0Y.TKN2` in the CRYPTOZ class. The system contains an operational ICSF subsystem and PCI-class cryptographic coprocessor. Using RACDCERT LISTTOKEN, user RACFADM determined the sequence number of the certificate to be added is `1`.
	Command	`RACDCERT IMPORT(TOKEN(NETB0Y.TKN2) SEQNUM(1)) ID(NETB0Y) TRUST WITHLABEL('RSA token') PKDS`
	Output	None.