Usage notes

The generated AES key can be 16, 24, or 32 bytes in length, depending on the Key length keyword specified in the rule array, with a default length of 16 bytes. The generated DES key can be 8 or 16 bytes in length as specified in the rule array, with a default length of 8 bytes.

• RSA enciphered key:

  For the RSA enciphered key, the generated symmetric key value is formatted into the key block specified by the Key-formatting method keyword. The formatted key block is wrapped with an RSA public-key. The RSA enciphered key is not returned in a CCA nor a TR-31 key-token.

  Use the rule array to specify one of the following four Key-formatting methods for the RSA enciphered key:

  1. PKCSOAEP

     The generated key value is formatted as defined in the RSA PKCS #1 v2.0 standard for the RSAES-OAEP encryption/decryption scheme. See PKCS #1 hash formats. This key-formatting method generates a CCA or TR-31 AES or DES DATA key. Optionally specify a hash method keyword of SHA-1 or SHA-256 or use the default of SHA-1 to calculate the OAEP message digest.

  2. PKCS-1.2

     The generated key value is formatted as defined in the RSA PKCS #1 v2.0 standard for the RSAES-PKCS1-v1_5 encryption/decryption scheme. See PKCS #1 hash formats. This key-formatting method generates a CCA or TR-31 AES or DES DATA key.

  3. ZERO-PAD

     The generated key value is padded on the left with zero bits up to the modulus size of the RSA key. This key-formatting method generates a CCA or TR-31 AES or DES DATA key.

  4. PKA92

     The generated key value is formatted as defined in PKA92 key format and encryption process. This key-formatting method generates a CCA DES key-encrypting key. On input, for key-formatting methods PKCSOAEP, PKCS-1.2, and ZERO-PAD, the control vector to use for the output RSA enciphered key is generated by this service. Therefore, provide a NULL token to the RSA_enciphered_key_identifier parameter.

     For key-formatting method PKA92, a control vector must be provided on input for a CCA DES EXPORTER or IMPORTER key-encrypting key. Using PKA92 means that the generated key is a key-encrypting key, and that the local enciphered key and the RSA enciphered key must be a pair of CCA EXPORTER and IMPORTER keys (TR-31 tokens are not supported for PKA92).

• Local enciphered key:

  For the local enciphered key, the generated symmetric key value is wrapped with a symmetric master-key or a DES key-encrypting key:

  1. When a CCA or TR-31 AES DATA key is generated (PKCSOAEP, PKCS-1.2, or ZERO-PAD), the local enciphered key is always wrapped with the AES master-key. This is the default. Or you can specify the equivalent optional encipherment method keyword OP. The local enciphered key is returned in a fixed-length operational CCA AES DATA key-token or an operational TR-31 AES key token with the following attributes:
     • TR-31 key usage: D0
     • Algorithm: A
     • TR-31 mode of key use: B, D, or E
  2. When a CCA or TR-31 DES DATA key is generated (PKCSOAEP, PKCS-1.2, or ZERO-PAD), the local enciphered key is wrapped with the DES master-key, or a DES key-encrypting key (KEK). A KEK must be a CCA DES IMPORTER or EXPORTER KEK, or a TR-31 DES KEK depending on the optional encipherment method specified. Wrapping the local enciphered key with the DES master-key is the default, or specify an optional encipherment method keyword of OP, IM, or EX. When IM or EX is specified, the key_encrypting_key_identifier parameter must identify the key-encrypting key used to encipher the local enciphered key. For CCA KEK tokens, if the IM keyword is used, the CCA KEK must be an IMPORTER. If EX is specified, then the CCA KEK must be an EXPORTER. For TR-31 KEK tokens, if the IM keyword is used, the TR-31 KEK must have the following attributes:
     • TR-31 key usage: K0
     • Algorithm: T
     • TR-31 mode of key use: D
     If EX is specified then the TR-31 KEK must have these attributes:
     • TR-31 key usage: K0
     • Algorithm: T
     • TR-31 mode of key use: E
     The local enciphered key is returned in a fixed-length external or operational CCA DES key-token or an external or operational TR-31 key-token.
  3. When a CCA DES key-encrypting key is generated (PKA92), the local enciphered key is always wrapped with the DES master-key. This is the default. Do not specify an encipherment method keyword. The local enciphered key is returned in a fixed-length CCA DES key-token. On input, for key-formatting methods PKCSOAEP, PKCS-1.2, and ZERO-PAD, the control vector to use for the output local enciphered key can be provided in an internal, external, or NULL key-token. For the internal and external tokens this means either a fixed-length symmetric CCA DATA DES key-token or a skeleton TR-31 DATA DES key-token with the following attributes:
     • TR-31 key usage: D0
     • Algorithm: T
     • TR-31 mode of key use: B, D, or E

     For key-formatting method PKA92, a control vector must be provided on input for a CCA DES IMPORTER or a CCA DES EXPORTER key-encrypting key. Using PKA92 means that the generated key is a key-encrypting key, and that the local enciphered key and the RSA enciphered key must be a pair of CCA EXPORTER and IMPORTER keys (TR-31 tokens are not supported for PKA92).

     CBC mode (WRAP-ENH) is available to wrap CCA DES keys. CBC mode is considered an enhanced wrapping method compared to the legacy wrapping method which uses ECB mode. Specify key-wrapping method USECONFG, WRAP-ECB, or WRAP-ENH. The use of keywords WRAP-ECB and WRAP-ENH requires a special access control point to be enabled in the active role. To restrict a local enciphered DES key from being wrapped with the legacy wrapping method once it has been wrapped with the enhanced wrapping method, specify the optional translation control keyword ENH-ONLY. These wrapping keywords are only valid when the local_enciphred_key_identifier parameter is producing a CCA token (not valid when the output is a TR-31 token).

Extra PKA92 Notes:

Use the PKA92 key-formatting method to generate a CCA DES key-encrypting key (IMPORTER/EXPORTER). The verb enciphers one key copy using the key encipherment technique employed in the IBM® Transaction Security System (TSS) 4753, 4755, and AS/400 cryptographic product PKA92 implementations (see PKA92 key format and encryption process. The control vector for the RSA-enciphered copy of the key is taken from an internal (operational) DES key token that must be present on input in the RSA_enciphered_key variable. The other key copy (local_enciphered_key_identifier) is enciphered under the DES master key.

Only key-encrypting keys that conform to the rules for an OPEX case under the Key Generate verb are permitted. The control vector for the local key is taken from a DES key token that must be present on input in the local_enciphered_key_identifier variable. The control vector for one key copy must be from the EXPORTER class, while the control vector for the other key copy must be from the IMPORTER class.