Troubleshoot the Cryptographic Coprocessor

Use these troubleshooting methods to tackle some of the basic problems that may occur with your Cryptographic Coprocessor. If the troubleshooting information does not address your problem, contact your service representative.

Always assure that you have applied all current PTFs for the relevant products and programs.

Using return codes

The primary method for detecting and troubleshooting problems is by monitoring return codes and reason codes.
  • A return code of 0 indicates successful completion. To provide some additional information, the Cryptographic Coprocessor associates some non-zero reason codes with this return code.
  • A return code of 4 indicates that the application programming interface (API) has completed processing, but an unusual event occurred. It could be related to a problem created by the application program, or it could be a normal occurrence based on data that is supplied to the API.
  • A return code of 8 indicates that the API did not complete successfully. An application programming error most likely caused this.
  • A return code of 12 normally indicates some type of problem in the setup or configuration of your Coprocessor. This code means that the processing of the API did not complete successfully.
  • A return code of 16 normally indicates a severe error in Common Cryptographic Architecture Cryptographic Service Provider (CCA CSP), system licensed internal code, or the Cryptographic Coprocessor licensed internal code. For these types of errors, you should contact your service representative.

You can also troubleshoot problems by analyzing the messages that appear in the job log or in the system operator (QSYSOPR) queue. Generally, any event that sends a message to the job log also returns an associated return code and a reason code to the calling programming. Messages sent to the system operator message, if reporting a severe problem, will normally point to a source of additional information about the problem. Such information is intended for IBM® service, and therefore you may not necessarily find them useful for problem determination.

Common errors

You should watch out for these common errors:
  • Did you vary on the device? You cannot send any requests to your Cryptographic Coprocessor until you vary on the device.

  • Is the CCA finding a device? If you do not explicitly use the Cryptographic_Resource_Allocate API, you must name the cryptographic device CRP01. If you do not name it that, the CCA cannot select any device. Either name the device CRP01 or change your program to use the Cryptographic_Resource_Allocate CCA API to select the device.

  • Are you selecting the correct device? If you have a default device (for example, a device named CRP01) and an additional device, the Cryptographic Coprocessor will select the default device, unless you use Cryptographic_Resource_Allocate.

  • Is the Cryptographic Coprocessor finding a key store file? If you do not explicitly use the Key_Store_Designate SAPI, the CCA CSP support will attempt to use the files named on the device description. If you have named no files on the device description, the Cryptographic Coprocessor will not find any files.

  • Have you loaded and set a master key? The Cryptographic Coprocessor will not complete any cryptographic requests other than those for configuring your Cryptographic Coprocessor, unless you load a master key.

  • Does the Old master key register contain a key? The Cryptographic Coprocessor cannot re-encrypt keys under the Current® master key unless the Old master key register contains a value.

  • Does your default role have authority to use a given hardware command? If not, you will need to log on by using a profile that uses a role that has the correct authority.

  • Does any role have authority to use a given hardware command? If your Cryptographic Coprocessor requires the hardware command and you have not authorized a role to use that command, you must reinitialize your Cryptographic Coprocessor. Do this by using either the Cryptographic_Facility_Control API or the Hardware Service Manager that is found in System Service Tools. Using the Cryptographic_Facilty_Control API requires that you authorize a role to the hardware command that reinitializes the Cryptographic Coprocessor. If no such role exists, you must use the Hardware Service Manager.

  • Is a function control vector loaded? Your Cryptographic Coprocessor cannot run any cryptographic operations other than configuration until you load a function control vector.

  • If you are loading a master key, did you begin by clearing out the new master key register? If your Cryptographic Coprocessor has a partially loaded new master key register, you cannot load the first part of a master key.

  • Did you remember to set the clock in your Coprocessor before removing the authority to do so from the DEFAULT role? If not, you must reinitialize your Cryptographic Coprocessor by using either the Cryptographic_Facility_Control API or the Hardware Service Manager found in System Service Tools. Using the Cryptographic_Facilty_Control API requires that you authorize a role to the hardware command that reinitializes the Cryptographic Coprocessor. If no such role exists, you must use the Hardware Service Manager.

  • Did you set the EID before trying to generate public-private key pairs? You must set the EID before you can generate RSA keys.

  • Did you correctly initialize the first byte of a null key token to binary 0? If not, the CCA support may try to use it as a key label. CCA Support will either report it as a bad label format or report that it could find the key record.

  • Do you use the same name for a label in a PKA key store file and a retained PKA key? If so, your Cryptographic Coprocessor will never find the retained key because the Cryptographic Coprocessor always searches the key store file first.

  • Do you have EBCDIC data in any fields in a skeleton PKA key token? The Cryptographic Coprocessor specifically checks for ASCII data in a number of the fields and will return an error if it finds EBCDIC data.
Parent topic: Cryptography