Parameters

Edit online

The parameters for CSNBRKA.

For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see Parameters common to all verbs.

rule_array_count
Direction: Input
Type: Integer
The number of keywords you supplied in the rule_array parameter. This value must be 1 - 11.
rule_array
Direction: Input
Type: String array
The rule_array contains keywords that provide control information to the verb. The keywords must be in contiguous storage with each of the keywords left-aligned in its own 8-byte location and padded on the right with blanks. The rule_array keywords are described in Table 1.
Table 1. Keywords for Restrict Key Attribute control information

Keywords for Restrict Key Attribute control information
Token type (one required)
AES Specifies to further restrict one or more attributes of a variable-length AES key-token. This keyword is not supported for a fixed-length AES key-token.

When inputting a TR-31 token, it must have the Algorithm A attribute.
DES Specifies to further restrict one or more attributes of a DES key-token.

When inputting a TR-31 token, it must have the Algorithm T or D attribute.
HMAC Specifies to further restrict one or more attributes of a variable-length HMAC key-token.

When inputting a TR-31 token, it must have the Algorithm H attribute.
Keywords for AES or HMAC variable-length key tokens (key token for clear key not allowed)
General attribute restriction (one, optional). Ignored if attribute restriction keyword is specified.
NOEXPORT Prohibits the key from being exported by any verb.

For CCA tokens, this keyword is equivalent to providing all of the export control attribute restrictions keywords (NOEX-AES, NOEX-DES, NOEX-RSA, NOEX-RAW, NOEXSYM, NOEXAASY, and NOEXUASY).

When the key_identifier value refers to an X9-SWKB (TR-31 token), this keyword prohibits the X9-SWKB from being exported. For an X9- SWKB with current Exportability setting of S or E, the Exportability is changed to N. For other Exportability settings, no change is made.

This is the default when no attribute restrictions keywords (export control and key usage) are specified.

NOEXNX24 Valid only when the key_identifier value refers to an X9-SWKB (TR-31 token). Prohibits the X9-SWKB from being exported under a KEK that is not compliant with ANSI X9.24 parts 1 and 2.

For a key with current Exportability setting of S, the Exportability is changed to E. For other Exportability settings, no change is made.
Export control attribute restrictions (one or more, optional).
NOEX-AES Prohibits the key from being exported using an AES key.
NOEX-DES Prohibits the key from being exported using a DES key.
NOEX-RSA Prohibits the key from being exported using an RSA key.
NOEX-RAW Prohibits the key from being exported using a RAW key. Defined for future use. Currently ignored.
NOEX-SYM Prohibits the key from being exported using a symmetric key.
NOEXAASY Prohibits the key form being exported using an authenticated asymmetric key (for example, an RSA key in a trusted block).
NOEXUASY Prohibits the key from being exported using an unauthenticated asymmetric key.
Key-management field attribute restrictions (one, optional). Only valid for AES DKYGENKY keys.
KMF-GND Use the key management fields from the key to be generated.
KMF-MBP (Release 7.5 or later) The key management fields of the key to be generated must be permissible based on the key management fields of the generating key. Only one of KMF-MBE or KMF-MBP may be on.
KMF-GND2 Use the key management fields from the key to be generated.
KMF-MBE (Release 7.5 or later) The key management fields of the key to be generated must be equal to the key management fields of the generating key. Only one of KMF-MBE or KMF-MBP may be on.
Ciphertext translation restriction (one, optional). Only valid for AES CIPHER keys.
C-XLATE Restricts the key to being used by the Cipher Text Translate2 (CSNBCTT2) verb.
KEK identifier rule (one, optional). Not allowed if KEK_identifier_length parameter is 0. Required if KEK identifier is a key label and the key in key storage is an RSA KEK).
IKEK-AES The inbound key-encrypting key for the external key is an AES KEK. This is the default.

When using a TR-31 KEK, it must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: A
  • TR-31 mode of key use: D or E
Note: K1 is needed when wrapping/unwrapping TR-31 tokens, and K0 is needed when wrapping/unwrapping CCA tokens.
IKEK-PKA The inbound key-encrypting key for the external key is an asymmetric key. Required if an RSA transport key is used (that is, the key being changed is wrapped using the PKOAEP2 method).
Keywords for DES fixed-length key tokens
General attribute restriction (one, optional). Ignored if attribute restriction or key restriction keyword is specified.
NOEXPORT Prohibits the key from being exported by any verb. Use this keyword to set XPORT-OK off (CV bit 17 = B'0') and NOT31XPT (CV bit 27 = B'1'). This is the default if no attribute restriction or key restriction keywords are specified.
Attribute to restrict (one, optional). Keywords CCAXPORT and NOT31XPT in this group are defaults if no keyword is provided. Only valid for DES. Make multiple calls to this verb as needed to restrict more than one of these attributes.
CCAXPORT Prohibits the key from being exported by any verb. Use this keyword to set XPORT-OK off (CV bit 17 = B'0').
DOUBLE-O For double-length DES key tokens that do not have equal key halves (ignoring parity bits), sets CV bit 40 = B'1' to guarantee that the two 8-byte key values of a DES double-length key are unique, that is, the key halves are not replicated. Key type must be EXPORTER, IKEYXLAT, IMPORTER, or OKEYXLAT.
Note: A double-length key with replicated key halves has an effective strength of a single-length key.
NOT31XPT Sets export control CV to NOT31XPT (bit 57 = B'1') to prohibit TR-31 export of the key.
KEK identifier rule (one, optional). Not allowed if KEK_identifier_length variable is 0.
IKEK-DES The inbound key-encrypting key for the external key is a DES KEK. This is the default.

When using a TR-31 KEK, it must have the following attributes:

  • TR-31 key usage: K0 or K1
  • Algorithm: T
  • TR-31 mode of key use: D or E
Note: K1 is needed when wrapping or unwrapping TR-31 tokens, and K0 is needed when wrapping or unwrapping CCA tokens.
Key-management field attribute restrictions (one, optional). Only valid for AES DKYGENKY keys (Release 7.5 or later)
KMF-MBP (Release 7.5 or later) The key management fields of the key to be generated must be permissible based on the key management fields of the generating key. An error is returned if the KMF-MBE bit is already set.
KMF-MBE (Release 7.5 or later) The key management fields of the key to be generated must be equal to the key management fields of the generating key. If the KMF-MBP bit is on, it is replaced with the KMF-MBE bit.
key_identifier_length
Direction: Input
Type: Integer
The length of the key_identifier parameter in bytes. The maximum value is 9992.
key_identifier
Direction: Input
Type: String
The key for which the export control is to be updated. The parameter contains an internal token or the 64-byte label of the key in key storage. If a label is specified, the key token will be updated in key storage and not returned by this verb.
key_encrypting_key_identifier_length
Direction: Input
Type: Integer

A pointer to an integer variable containing the number of bytes of data in the key_encrypting_key_identifier variable. Set the value to zero if the input key_identifier is an internal key token, and set the value to greater than or equal to 64 if the input key is in an external key token. If the variable contains a key label, set the value to 64. The maximum value is 9992.

key_encrypting_key_identifier
Direction: Input
Type: String
A pointer to a string variable containing the operational CCA or TR-31 AES or DES EXPORTER or IMPORTER key-encrypting key, or the RSA private key needed to decipher the external input symmetric key token, or the key label of such a key in key storage.
opt_parameter1_length
Direction: Input
Type: Integer
The byte length of the opt_parameter1 parameter. This value must be 0.
opt_parameter1
Direction: Input
Type: String
This parameter is ignored.
opt_parameter2_length
Direction: Input
Type: Integer
The byte length of the opt_parameter2 parameter. This value must be 0.
opt_parameter2
Direction: Input
Type: String
This parameter is ignored.