PKA Decrypt (CSNDPKD and CSNFPKD)

CALL CSNDPKD(
              return_code,
              reason_code,
              exit_data_length,
              exit_data,
              rule_array_count,
              rule_array,
              PKA_enciphered_keyvalue_length,
              PKA_enciphered_keyvalue,
              data_structure_length,
              data_structure,
              key_identifier_length,
              key_identifier,
              target_keyvalue_length,
              target_keyvalue)
 

return_code

Direction	Type
Output	Integer

The return code specifies the general result of the callable service. ICSF and cryptographic coprocessor return and reason codes lists the return codes.

reason_code

Direction	Type
Output	Integer

The reason code specifies the result of the callable service that is returned to the application program. Each return code has different reason codes that are assigned to it that indicate specific processing problems. ICSF and cryptographic coprocessor return and reason codes lists the reason codes.

exit_data_length

Direction	Type
Input/Output	Integer

The length of the data that is passed to the installation exit. The data is identified in the exit_data parameter.

exit_data

Direction	Type
Input/Output	String

The data that is passed to the installation exit.

rule_array_count

Direction	Type
Input	Integer

The number of keywords you supplied in the rule_array parameter. This value must be 1.

rule_array

Direction	Type
Input	String

The keyword that provides control information to the callable service. The keyword is left-justified in an 8-byte field and padded on the right with blanks.

Table 1. Keywords for PKA Decrypt

Keyword	Meaning
Recovery Method (required) specifies the method to use to recover the key value.
PKCS-1.2	RSA PKCS #1 V1.5 block type 02 will be used to recover the key value.
PKCSOAEP	Specifies to recover the data formatted using the RSAES-OAEP encoding scheme defined in the RSA PKCS #1 v2.0 standard. This keyword is not valid when using a secure PKCS #11 private key.
ZERO-PAD	The input PKA_enciphered_keyvalue is decrypted using the RSA private key. The entire result (including leading zeros) will be returned in the target_keyvalue field. For PKA keys, the key_identifier must be an external RSA token or the labelname of a external token. This keyword is not valid when using a secure PKCS #11 private key.
Hash Method (one required when PKCSOAEP is specified. Otherwise, not allowed.)
SHA-1	Specifies to use the SHA-1 method to calculate the OAEP message digest.
SHA-256	Specifies to use the SHA-256 method to calculate the OAEP message digest.

PKA_enciphered_keyvalue_length

Direction	Type
Input	Integer

The length of the PKA_enciphered_keyvalue parameter in bytes. The maximum size that can be generated is 512 bytes. The length should be the same as the modulus length of the key_identifier.

PKA_enciphered_keyvalue

Direction	Type
Input	String

This field contains the key value protected under an RSA public key. This byte-length string is left-justified within the PKA_enciphered_keyvalue parameter.

data_structure_length

Direction	Type
Input	Integer

The value must be 0.

data_structure

Direction	Type
Input	String

This field is currently ignored.

key_identifier_length

Direction	Type
Input	Integer

The length of the key_identifier parameter. When the key_identifier is a key label, this field specifies the length of the label. The maximum size that you can specify is 3500 bytes.

key_identifier

Direction	Type
Input	String

For PKA keys, an internal RSA private key token, the label of an internal RSA private key token, or an external RSA private key token containing a clear RSA private key in modulus-exponent or Chinese Remainder Theorem format.

For secure PKCS #11 keys, this is the 44-byte handle of the private key, prefixed with an EBCDIC equal sign character (‘=’ or x’7E’), and padded on the right with spaces for a total length of 64 bytes.

The corresponding public key was used to wrap the key value.

target_keyvalue_length

Direction	Type
Input/Output	Integer

The length of the target_keyvalue parameter. The maximum size that can be generated is 512 bytes. On return, this field is updated with the actual length of target_keyvalue.

If ZERO-PAD is specified, this length will be the same as the RSA modulus byte length.

target_keyvalue

Direction	Type
Output	String

This field will contain the decrypted, deformatted key value. If ZERO-PAD is specified, the decrypted key value, including leading zeros, will be returned.

The exponent of the RSA public key must be odd.

Crypto Express accelerators do clear key RSA operations. Requests with encrypted keys are routed to a coprocessor.

To use this service with a secure PKCS #11 private key that is a public object, the caller must have SO (READ) authority or USER (READ) authority (any access) to the containing PKCS #11 token.

To use this service with a secure PKCS #11 private key that is a private object, the caller must have USER (READ) authority (user access) to the containing PKCS #11 token.

See z/OS Cryptographic Services ICSF Writing PKCS #11 Applications for more information on the SO and User PKCS #11 roles.

SAF may be invoked to verify the caller is authorized to use this callable service, the key label, or internal secure key tokens that are stored in the CKDS, PKDS, or TKDS.

PKA RSA private key must be enabled for key management functions. Secure PKCS #11 private keys must be enabled for decryption.

For PKA keys, the hardware configuration sets the limit on the modulus size of keys for key management; thus, this service will fail if the RSA key modulus bit length exceeds this limit.

For PKA keys, the PKA Decrypt access control point controls the function of this service.

For secure PKCS #11 private keys, see 'PKCS #11 Access Control Points' in z/OS Cryptographic Services ICSF Writing PKCS #11 Applications for more information on the access control points of the Enterprise PKCS #11 coprocessor.

This table lists the required cryptographic hardware for each server type and describes restrictions for this callable service.