In addition to using profiles in the CSFKEYS class (and, when Symmetric Key Label Export is enabled, the XCSFKEY class) to identify which users have permission to certain cryptographic keys, you can also enable the PKA Key Management Extensions control so that CSFKEYS and XCSFKEY profiles can place restrictions on how keys are used. For example, you can:

• restrict an asymmetric key from being used in secure export and import operations.
• restrict an asymmetric key from being used in handshake operations.
• Restrict a symmetric key from being exported (transferred from encryption under a master key to encryption under an application-supplied RSA public key). Alternatively, you can allow the symmetric key to be exported, but only by certain public keys (as indicated by a list of key labels), or only by public keys bound to certain identities (as indicated by a list of certificates in either a PKCS #11 token, or a SAF key ring).

Setting restrictions such as these can help ensure that keys are used only for intended purposes, regardless of who has access to the keys. For example, if you have an RSA key pair intended only for generating and verifying digital signatures, you can set a restriction to ensure that the public key of this key pair is never used to export a symmetric key.

You place restrictions on cryptographic keys using the ICSF segment of the CSFKEYS or XCSFKEY class profiles that cover the keys. After you have modified the profiles with the restrictions you want to place on the keys, you can enable the PKA Key Management Extensions control by creating a CSF.PKAEXTNS.ENABLE profile in class XFACILIT. You can also enable PKA Key Management Extensions in warning mode by creating a CSF.PKAEXTNS.ENABLE.WARNONLY profile in class XFACILIT. In order to enable PKA Key Management Extensions, Key Store Policy must be active for both the CKDS and the PKDS. For more information, refer to Enabling PKA Key Management Extensions.

Restricting asymmetric keys from being used in secure import and export operations

Using the ASYMUSAGE field in the ICSF segment of CSFKEYS profiles enables you to restrict asymmetric keys covered by the profile from being used in secure import and export operations. In secure export operations, a symmetric key (AES or DES) is moved from encryption under a master key to encryption under an asymmetric key (RSA public key). In a secure import operation, the private key of an RSA key pair is used to move a symmetric key from encryption under the RSA public key to encryption under a master key. The following callable services all identify an asymmetric key (either the public or private key of an RSA key pair) to encrypt or decrypt a symmetric key. The callable services that perform secure import and export operations are:

• Symmetric Key Generate (CSNDSYG and CSNFSYG)
• Symmetric Key Export (CSNDSYX and CSNFSYX)
• Symmetric Key Import (CSNDSYI and CSNFSYI) and Symmetric Key Import2 (CSNDSYI2 and CSNFSYI2)

For each of these services, a profile in the CSFKEYS class will control access to the asymmetric key. In addition to specifying user access to the key, the CSFKEYS profile can also specify information (in the ICSF segment of the profile) on how the key can be used. The ASYMUSAGE field of the ICSF segment enables you to specify whether an asymmetric key covered by the profile can participate in secure import or export operations. By specifying the NOSECUREEXPORT keyword in the ASYMUSAGE field, you restrict any asymmetric key covered by the profile from being used to encrypt or decrypt the symmetric key in these operations.

For example, the profile RSA.SAMMY.DIGSIG in class CSFKEYS covers an RSA key pair that should be used only for generating and verifying digital signatures and performing TLS/SSL handshakes. The following RALTER command modifies the profile to ensure that the public key of the RSA key pair is never used to export keys. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER CSFKEYS RSA.SAMMY.DIGSIG ICSF(ASYMUSAGE(NOSECUREEXPORT))
SETROPTS RACLIST(CSFKEYS) REFRESH

In order for the secure import/export restriction to take effect, you will need to enable the PKA Key Management Extensions control by creating a CSF.PKAEXTNS.ENABLE profile in class XFACILIT. In order to enable the PKA Key Management Extensions control, the Key Store Policy for both the CKDS and the PKDS must also be active. Refer to Enabling PKA Key Management Extensions for more information.

When the PKA Key Management Extensions control is enabled, the default is to allow keys to participate in secure import and export operations. You can also explicitly specify this using the SECUREEXPORT keyword in the ASYMUSAGE field of a CSFKEYS profile. For example:

RALTER CSFKEYS RSA.SAMMY.EXPORT ICSF(ASYMUSAGE(SECUREEXPORT))
SETROPTS RACLIST(CSFKEYS) REFRESH

The ASYMUSAGE field can also contain the NOHANDSHAKE or HANDSHAKE keywords to specify whether keys covered by the profile can participate in handshake operations (as described in Restricting asymmetric keys from being used in handshake operations). These keywords can be specified along with the NOSECUREEXPORT or SECUREEXPORT keywords when entering the RDEFINE or RALTER command.

RALTER CSFKEYS RSA.SAMMY.EXPORT ICSF(ASYMUSAGE(SECUREEXPORT NOHANDSHAKE))
SETROPTS RACLIST(CSFKEYS) REFRESH

Restricting asymmetric keys from being used in handshake operations

Using the ASYMUSAGE field in the ICSF segment of CSFKEYS profiles enables you to restrict asymmetric keys covered by the profile from being used in handshake operations. The following callable services all identify an asymmetric key to be used in a handshake operation. The callable services that perform handshake operations are:

• Digital Signature Generate (CSNDDSG and CSNFDSG)
• Digital Signature Verify (CSNDDSV and CSNFDSV)
• PKA Encrypt (CSNDPKE and CSNFPKE)
• PKA Decrypt (CSNDPKD and CSNFPKD)

For each of these services, a profile in the CSFKEYS class will control access to the asymmetric key used to generate/verify a digital signature, or encrypt/decrypt a clear key value. In addition to specifying user access to the key, the CSFKEYS profile can also specify information (in the ICSF segment of the profile) on how the key can be used. The ASYMUSAGE field of the ICSF segment enables you to specify whether an asymmetric key covered by the profile can participate in handshake operations. By specifying the NOHANDSHAKE keyword in the ASYMUSAGE field, you restrict any key covered by the profile from being used in handshake operations. For example, the profile RSA.SAMMY.EXPORT in class CSFKEYS covers an RSA key pair intended for exporting and importing symmetric keys. The following RALTER command modifies the profile to ensure that the RSA keys are not used in handshake operations. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER CSFKEYS RSA.SAMMY.EXPORT ICSF(ASYMUSAGE(NOHANDSHAKE))
SETROPTS RACLIST(CSFKEYS) REFRESH

In order for the restriction on handshake operations to take effect, you will need to enable the PKA Key Management Extensions control by creating a CSF.PKAEXTNS.ENABLE profile in class XFACILIT. In order to enable the PKA Key Management Extensions control, the Key Store Policy for both the CKDS and the PKDS must also be active. Refer to Enabling PKA Key Management Extensions for more information.

When the PKA Key Management Extensions control is enabled, the default is to allow keys to participate in handshake operations. You can also explicitly specify this using the HANDSHAKE keyword in the ASYMUSAGE field of profiles in the CSFKEYS class. For example:

RALTER CSFKEYS RSA.SAMMY.EXPORT ICSF(ASYMUSAGE(HANDSHAKE))
SETROPTS RACLIST(CSFKEYS) REFRESH

The ASYMUSAGE field can also contain the NOSECUREEXPORT or SECUREEXPORT keywords to specify whether keys covered by the profile can participate in secure import and export operations (as described in Restricting asymmetric keys from being used in secure import and export operations). These keywords can be specified along with the NOHANDSHAKE or HANDSHAKE keywords when entering the RDEFINE or RALTER command.

RALTER CSFKEYS RSA.SAMMY.EXPORT ICSF(ASYMUSAGE(NOSECUREEXPORT HANDSHAKE))
SETROPTS RACLIST(CSFKEYS) REFRESH

Placing restrictions on exporting symmetric keys

The Symmetric Key Export (CSNDSYX or CSNFSYX) callable service lets a calling application transfer a symmetric (AES or DES) key from encryption under a master key to encryption under an application-supplied RSA public key. This callable service is needed because a secure key (which is encrypted under a master key in the ICSF environment) might need to be shared with a partner, and to transfer it to that partner securely, it will need to be encrypted under an RSA key provided by the partner. The partner will then be able to decrypt it using a corresponding private key. Due to the nature of the operation performed by the Symmetric Key Export callable service, you may want to place additional restrictions on its use. Increasing the level of authority required to export symmetric keys describes how you can enable the Symmetric Key Label Export controls to specify that a user needs UPDATE authority in the XCSFKEY class (instead of the default READ authority in the CSFKEYS class) to export a symmetric key. By enabling the PKA Key Management Extensions control, can also specify that a symmetric key covered by a CSFKEYS or XCSFKEY profile:

• cannot be exported.
• can be exported by any asymmetric key in the PKDS
• can be exported only by certain asymmetric keys in the PKDS (as specified by a supplied list).
• can be exported by any asymmetric key, provided it is bound to an identity in a key certificate in a trusted certificate repository (either a PKCS #11 token or a SAF key ring).
• can be exported only by an asymmetric key that is bound to certain identities (as specified by a supplied list of key certificates in a trusted certificate repository).

When an application calls the CSNDSYX or CSNFSYX service, access to the symmetric key (the AES or DES key to be re-encrypted) is determined by a profile in the CSFKEYS class or, if the Symmetric Key Label Export control has been enabled, the XCSFKEY class. In addition to specifying user access to the key, the CSFKEYS or XCSFKEY profile can also place restrictions (in the ICSF segment of the profile) on export of the symmetric key. In the ICSF segment of a CSFKEYS or XCSFKEY profile, the SYMEXPORTABLE field contains a keyword that determines if the key can be exported, and, if so, how ICSF will determine the asymmetric keys (the RSA public keys) that can export (re-encrypt) the key.

• For more information on the BYNONE keyword, refer to Restricting the symmetric key from being exported.
• For more information on using the BYLIST keyword and the SYMEXPORTKEYS field, refer to Identifying RSA public keys that can export the symmetric key.
• For more information on using the BYLIST keyword and the SYMEXPORTCERTS field, refer to Identifying key certificates for symmetric key export.
• For more information on the BYANY keyword, refer to Placing no additional restrictions on symmetric key export.

Restricting the symmetric key from being exported

CSFKEYS and XCSFKEY profiles can contain an ICSF segment. Fields of the ICSF segment specify rules for key use. In the SYMEXPORTABLE field of the ICSF segment, the BYNONE keyword specifies that the symmetric key(s) covered by the profile can not be exported, regardless of a user's access authority to the key. If an application attempts to use the Symmetric Key Export (CSNDSYX or CSNFSYX) callable service to transfer a symmetric (AES or DES) key covered by the profile, the operation will fail and the service will return an error.

For example, the CKDS contains a DES key labeled DES.BRADY.CASTLE that should never be exported. The Symmetric Key Label Export control for DES keys has not been enabled, so the key is covered by a profile in the CSFKEYS class. The following RALTER command modifies the discrete profile DES.BRADY.CASTLE to indicate that the key should never be exported. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER CSFKEYS DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYNONE))
SETROPTS RACLIST(CSFKEYS) REFRESH

Identifying RSA public keys that can export the symmetric key

CSFKEYS and XCSFKEY profiles can contain an ICSF segment. Fields of the ICSF segment specify rules for key use. In the SYMEXPORTABLE field of the ICSF segment, the BYLIST keyword specifies that the symmetric key(s) covered by the profile can be exported by keys identified using the SYMEXPORTKEYS or SYMEXPORTCERTS fields.

Using the SYMEXPORTKEYS field, you can list the RSA public keys in the PKDS that are allowed to export the symmetric key. The SYMEXPORTKEYS list consists of one or more PKDS key labels identifying the RSA public keys under which the symmetric key can be re-encrypted. These labels follow the normal ICSF label conventions; they can be space separated, and quotes are optional.

A special key label is the asterisk character ( * ). If the SYMEXPORTKEYS field contains this special key label, any RSA public key in the PKDS can export the symmetric key (provided no other access requirement or control prevents it).

If an application attempts to use the Symmetric Key Export (CSNDSYX or CSNFSYX) callable service to transfer a symmetric (AES or DES) key covered by the profile, ICSF will compare the RSA public key identified by the application with those identified in the SYMEXPORTKEYS list. If the key is in the list, the operation is allowed to continue. If it is not in the list, and is also not bound to an identity in a certificate listed in the SYMEXPORTCERTS field (as described in Identifying key certificates for symmetric key export), the operation will fail and the service will return an error.

For example, the following RALTER command modifies the discrete profile DES.BRADY.CASTLE so that the DES key it covers can be exported only by the RSA public key RSA.BRADY.CASTLE. In this example, the Symmetric Key Label Export control has been enabled for DES keys, so the DES.BRADY.CASTLE profile is defined in the XCSFKEY class. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTKEYS(RSA.BRADY.CASTLE))
SETROPTS RACLIST(XCSFKEY) REFRESH

To instead allow any RSA public key in the PKDS to export the symmetric key covered by the DES.BRADY.CASTLE profile, you would specify the asterisk character ( * ) in the SYMEXPORTKEYS field.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTKEYS(*))
SETROPTS RACLIST(XCSFKEY) REFRESH

The ADDSYMEXPORTKEYS keyword of the ICSF segment enables you to add labels to a SYMEXPORTKEYS list without having to recreate the entire list. For example, to add the label RSA.BKNIGHT.CASTLE to the list, you would enter:

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(ADDSYMEXPORTKEYS(RSA.BKNIGHT.CASTLE))
SETROPTS RACLIST(XCSFKEY) REFRESH

Similarly, you can delete labels from a SYMEXPORTKEYS list using the DELSYMEXPORTKEYS keyword:

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(DELSYMEXPORTKEYS(RSA.BKNIGHT.CASTLE))
SETROPTS RACLIST(XCSFKEY) REFRESH

You can also delete the entire SYMEXPORTKEYS field using the NOSYMEXPORTKEYS keyword.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(NOSYMEXPORTKEYS)
SETROPTS RACLIST(XCSFKEY) REFRESH

Identifying key certificates for symmetric key export

CSFKEYS and XCSFKEY profiles can contain an ICSF segment. Fields of the ICSF segment specify rules for key use. In the SYMEXPORTABLE field of the ICSF segment, the BYLIST keyword specifies that the symmetric key(s) covered by the CSFKEYS or the XCSFKEY profile can be exported by keys identified using the SYMEXPORTKEYS or SYMEXPORTCERTS fields.

Using the SYMEXPORTCERTS field, you can supply a list of certificate labels in a trusted certificate repository (either a PKCS #11 token or a SAF key ring). As described in Enabling PKA Key Management Extensions, you enable the PKA Key Management Extensions control by creating a CSF.PKAEXTNS.ENABLE profile in class XFACILIT. You can use the APPLDATA field in that profile to identify the type and name of the trusted certificate repository. If the APPLDATA field is not used to provide this information, the default certificate repository is a PKCS #11 token named CSF.TRUSTED.KEYRING. The format of the SYMEXPORTCERTS field depends on whether the trusted certificate repository is a PKCS #11 token or a SAF key ring.

• If the trusted certificate repository is a PKCS #11 token, the certificate labels are listed in the format 'cka-id/cert-label', where:

  cka-id

  is the CKA_ID attribute of the certificate object. This portion of the specification is optional, and only necessary if multiple certificate objects have the same CKA_LABEL. If provided, RACF will convert this portion of the specification into uppercase before storing it in the profile.

  /cert-label

  is the CKA_LABEL attribute of the certificate object. Note that the forward slash character (/) is required even if the optional cka-id portion of the specification is omitted. If this portion of the specification contains blank characters, the entire specification must be enclosed in single quotes.

• If the trusted certificate repository is a SAF key ring, the certificate labels are listed in the format 'userID/cert-label', where:

  userID

  is the owner of the certificate. This portion of the specification is optional, and only necessary if multiple certificates have the same label. If provided, RACF will convert this portion of the specification into uppercase before storing it in the profile.

  /cert-label

  is the label of the digital certificate that was assigned when the certificate was created. Note that the forward slash character (/) is required even if the optional userID portion of the specification is omitted. If this portion of the specification contains blank characters, the entire specification must be enclosed in single quotes.

Regardless of whether you are using a PKCS #11 token or a SAF key ring, you can also use the asterisk character ( * ) in the SYMEXPORTCERTS field to match any certificate in the trusted certificate repository. Using the asterisk character in the SYMEXPORTCERTS field is the same as listing all the certificates in the trusted certificate repository.

If an application attempts to use the Symmetric Key Export (CSNDSYX or CSNFSYX) callable service to transfer a symmetric (AES or DES) key covered by the profile, ICSF will compare the RSA public key identified by the application with those bound to identities in certificates in the SYMEXPORTCERTS list. If any of the listed certificates contains the RSA public key, the operation is allowed to continue. If none of the listed certificates contain the public key, and the key is also not listed in the SYMEXPORTKEYS field (as described in Identifying RSA public keys that can export the symmetric key), the operation will fail and the service will return an error.

For example, say you want to allow export of a the symmetric key DES.BRADY.CASTLE only by the user and public key bound by a certificate in a SAF key ring. The SAF key ring was identified to ICSF when the PKA Key Management Extensions control was enabled (using the APPLDATA field of the CSF.PKAEXTNS.ENABLE profile). The label of the digital certificate in the SAF key ring is "Mister Ink", and the discrete profile covering the key has already been defined in the XCSFKEY class. The following RALTER command specifies that the only RSA public key that can export the symmetric key is the one bound to the identity in the "Mister Ink" certificate. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTCERTS('/Mister Ink'))
SETROPTS RACLIST(XCSFKEY) REFRESH

The preceding example assumes that no other certificates have the same label. If other certificates do have the same label, you would want to include the user ID of the certificate owner in the SYMEXPORTCERTS list specification. For example, if the user BKNIGHT is the certificate owner, you would enter:

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTCERTS('BKNIGHT/Mister Ink'))
SETROPTS RACLIST(XCSFKEY) REFRESH

You can also use the asterisk character ( * ) in the SYMEXPORTCERT field to match any certificate in the certificate repository.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTCERTS(*))
SETROPTS RACLIST(XCSFKEY) REFRESH

The ADDSYMEXPORTCERTS keyword of the ICSF segment enables you to add certificate labels to a SYMEXPORTCERTS list without having to recreate the entire list. For example, to add the certificate 'SERRIN/Mister Ink' to the list of certificate labels, you would enter:

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(ADDSYMEXPORTCERTS('SERRIN/Mister Ink'))
SETROPTS RACLIST(XCSFKEY) REFRESH

Similarly, you can delete certificate labels from a SYMEXPORTCERTS list using the DELSYMEXPORTCERTS keyword:

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(DELSYMEXPORTCERTS('BKNIGHT/Mister Ink'))
SETROPTS RACLIST(XCSFKEY) REFRESH

You can also delete the entire SYMEXPORTCERTS field using the NOSYMEXPORTCERTS keyword.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(NOSYMEXPORTCERTS)
SETROPTS RACLIST(XCSFKEY) REFRESH

Placing no additional restrictions on symmetric key export

If no keyword value is specified in the ICSF segment's SYMEXPORTABLE field, then, by default, no additional restrictions are placed on the export of symmetric keys covered by the profile. Provided no other access requirement or control prevents it, the symmetric key can be exported by any RSA public key. Although this is the default behavior, you can also explicitly specify it using the BYANY keyword. You might want to do this, for example, if you had previously specified the BYNONE or BYLIST keyword in the SYMEXPORTABLE field, and now want to return to the default behavior.

For example, to specify that there are no restrictions on the export of the symmetric key covered by the profile DES.BRADY.CASTLE in the XCSFKEY class, and that any RSA key can be used in the export operation (provided the user has access permission to the key), you could enter the following RALTER command. The SETROPTS RACLIST command is used to refresh the profile in common storage.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYANY))
SETROPTS RACLIST(CSFKEYS) REFRESH

You can also return to the default behavior by deleting the entire SYMEXPORTABLE field using the NOSYMEXPORTABLE keyword.

RALTER XCSFKEY DES.BRADY.CASTLE ICSF(NOSYMEXPORTABLE)
SETROPTS RACLIST(XCSFKEY) REFRESH

Enabling PKA Key Management Extensions

The rules for cryptographic key usage defined in the ICSF segment of CSFKEYS and XCSFKEY profiles (described in Restricting asymmetric keys from being used in secure import and export operations, Restricting asymmetric keys from being used in handshake operations, and Placing restrictions on exporting symmetric keys) will not be in effect unless PKA Key Management Extensions are enabled. PKA Key Management Extensions cannot be enabled unless Key Store Policy is active for both the CKDS and PKDS.

Enabling any one of the following controls will activate Key Store Policy for a CKDS:

• CSF.CKDS.TOKEN.CHECK.LABEL.WARN
• CSF.CKDS.TOKEN.CHECK.LABEL.FAIL
• CSF.CKDS.TOKEN.NODUPLICATES

Enabling any one of the following controls will activate Key Store Policy for a PKDS:

• CSF.PKDS.TOKEN.CHECK.LABEL.WARN
• CSF.PKDS.TOKEN.CHECK.LABEL.FAIL
• CSF.PKDS.TOKEN.NODUPLICATES

The following table shows the controls for enabling PKA Key Management Extensions in either warning or fail mode. To enable one of the controls, create the appropriate profile in the XFACILIT class.

For example, you've already used the ICSF segment of profiles in the CSFKEYS or XCSFKEY class to define various restrictions on how keys covered by the profiles can be used. You're not certain that all applications at your installation are using the keys according to the new restrictions, and do not want to disrupt current work patterns at your installation. For this reason, you decide to allow a warning period during which you can identify noncompliant applications without causing application failure. To do this, you would:

1. Enable PKA Key Management Extensions in warning mode:

   RDEFINE XFACILIT CSF.PKAEXTNS.ENABLE.WARNONLY
   SETROPTS RACLIST(XFACILIT) REFRESH

2. Because you have enabled PKA Key Management Extensions in warning mode, ICSF will allow applications to use keys in ways that violate ICSF segment specifications. However, ICSF will generate SMF type 82 subtype 27 records for any violation. Using the information in these records, you can modify your installation's applications as needed.
3. When you are ready to move to a stricter implementation of the policy, you enable the PKA Key Management Extensions control for fail mode, and disable the one for warning mode.

   RDEFINE XFACILIT CSF.PKAEXTNS.ENABLE
   RDELETE XFACILIT CSF.PKAEXTNS.ENABLE.WARNONLY
   SETROPTS RACLIST(XFACILIT) REFRESH

   If you accidentally enable PKA Key Management Extensions in both warning and fail mode, the control for fail mode will take precedence.

As described in Identifying key certificates for symmetric key export, you can use the ICSF segment's SYMEXPORTCERTS field to provide a list of certificate labels in a trusted certificate repository (either a PKCS #11 token or a SAF key ring). This enables you to specify that symmetric keys covered by a CSFKEYS or XCSFKEY profile can be exported only by RSA public keys that are bound to identities in the listed certificates. If using the SYMEXPORTCERTS field to provide a list of certificate labels in a trusted certificate repository, you will need to identify that trusted certificate repository to ICSF. You do this using the APPLDATA field of the CSF.PKAEXTNS.ENABLE profile. If the trusted key repository is a PKCS #11 token, it should be identified in the APPLDATA field in the format *TOKEN*/PKCS-token-name. If the trusted key repository is a SAF key ring, it should be identified in the APPLDATA field in the format userID/key-ring-name. For example, if the trusted key repository was a SAF key ring named TRUSTED.KEY.EXPORTERS created by BOBADMIN, you would enter:

RDEFINE XFACILIT CSF.PKAEXTNS.ENABLE APPLDATA(BOBADMIN/TRUSTD.KEY.EXPORTERS)
SETROPTS RACLIST(XFACILIT) REFRESH

If an APPLDATA field is not provided on the CSF.PKAEXTNS.ENABLE, the default certificate repository is a PKCS #11 token named CSF.TRUSTED.KEYRING.

PKA key management extensions example

The following example provides additional illustration of the ICSF segment fields and keywords that you can use to place restrictions on how cryptographic keys can be used.

A DES key has been created for encrypting transactions between a Company and its Business Partner. The Business Partner's public key has previously been added to the PKDS for the purpose of exporting the DES key. The Company's security administrator wants to be sure that only the Business Partner's public key can be used to export the DES key that the Company and its Business Partner are sharing. There is already a profile covering the label of the RSA public key in the PKDS, but no profile covering the label of the new DES key. The security administrator needs to alter the profile for the RSA public key label, and define a new profile for the DES key label. The security administrator has also enabled the Symmetric Key Label Export Control to increase the level of authority needed to export symmetric keys, and so the profile covering the DES key is defined in the XCSFKEY class.

RALTER CSFKEYS RSA.BRADY.CASTLE ICSF(ASYMUSAGE(SECUREEXPORT NOHANDSHAKE))
RDEFINE XCSFKEY DES.BRADY.CASTLE ICSF(SYMEXPORTABLE(BYLIST) SYMEXPORTKEYS(RSA.BRADY.CASTLE)) UACC(NONE)
PERMIT DES.BRADY.CASTLE CL(XCSFKEY) ID(SAMPRTNR) UPDATE
SETROPTS RACLIST(CSFKEYS) REFRESH
SETROPTS RACLIST(XCSFKEY) REFRESH

Key Store Policy is active for both the CKDS and PKDS, so the security administrator only needs to enable the PKA Key Management Extensions control, and refresh the XFACILIT class in storage.

RDEFINE XFACILIT CSF.PKAEXTNS.ENABLE
SETROPTS RACLIST(XFACILIT) REFRESH

Later, the security administrator wants further restrictions on exporting the DES key that the Company and its Business Partner are sharing. The security administrator wants to bind an existing RSA public key to an identity, and allow export of the DES key only by the user and public key bound by a particular certificate. The security administrator creates the certificate for the RSA key, creates a SAF key ring, and adds the certificate to the key ring.

RACDCERT ID(BOBADMIN) GENCERT                                                +
         SUBJECTSDN(CN('Mister Ink Inc')O('Business Partner')C('uk'))        +
         WITHLABEL('Mister Ink')SIGNWITH(CERTAUTH LABEL(LocalCertauth'))     +
         KEYUSAGE(DOCSIGN)                                                   +
         NOTAFTER(DATE(2020-12-31))                                          +
         FROMICSF(RSA.BRADY.CASTLE)                                          +
RACDCERT ID(BOBADMIN) ADDRING(TRUSTD.KEY.EXPORTERS)
RACDCERT ID(BOBADMIN) CONNECT(LABEL('Mister Ink' RING(TRUSTD.KEY.EXPORTERS)  +
         USAGE(PERSONAL))
RALTER XCSFKEY DES.BRADY.CASTLE ICSF(NOSYMEXPORTKEYS                         +
         SYMEXPORTCERTS('/Mister Ink'))
SETROPTS RACLIST(XCSFKEY) REFRESH

Because the security administrator knows that only one certificate with the label "Mister Ink" will be present in the key ring, he does not specify the user ID portion of the string in the SYMEXPORTCERTS list. Note, however, that the security administrator still needs to include the forward slash ( / ) delimiter even though a user ID was not provided. Also note that the NOSYMEXPORTKEYS keyword is used to remove the SYMEXPORTKEYS list that had been previously defined.

The security administrator modifies the CSF.PKAEXTNS.ENABLE profile in the XFACILIT class to identify the SAF key ring as the certificate repository.

RDEFINE XFACILIT CSF.PKAEXTNS.ENABLE APPLDATA(TRUSTD.KEY.EXPORTERS)
SETROPTS RACLIST(XFACILIT) REFRESH

For more information on the ICSF fields and keywords, refer to Restricting asymmetric keys from being used in secure import and export operations, Restricting asymmetric keys from being used in handshake operations, and Placing restrictions on exporting symmetric keys.