Using retained keys

Edit online

Retained key use is discouraged on the IBM Z® platform because a retained key can exist only in one CEX*C Cryptographic adapter, by definition.

  • This has potential problems:
    • The key cannot be exported, so it cannot be backed up.
    • The key cannot be exported to another card in the same group, so operations concerning the retained key cannot participate in load-balancing.
    • There is an exception to the above points, in that keys generated in a deterministic fashion using externally saved regeneration data (it is possible to save so-called 'regen data' securely) can be recreated from that data or created in multiple cards across a card group.

      However, this is a very sophisticated topic, and is beyond the scope of this document. Also, the complexity required to implement this properly, as well as the sophistication involved in its data management, present formidable obstacles.

Retained key support is offered in this release, however. The following verbs work with retained keys:
  • PKA Key Generate (CSNDPKG) generates an RSA retained key. The same restrictions that Integrated Cryptographic Service Facility (ICSF) has for retained key creation are implemented here. These are:
    • Notice that PKA Key Token Build will let you create 'key-mgmt' skeleton key tokens, and this is as designed. You can still pass these to PKA Key Generate and have a key pair created. What is not allowed is specifying that this 'key-mgmt' token is to be generated in PKA Key Generate as a RETAIN key token: a retained key. Such an attempt fails with error 12 reason code 3046.
    • The maximum modulus size is 2048 bits.
    • The usage flags are restricted to signature generation.

      Specifically, key management usage for retained keys is not allowed because of the dangers of losing your key encrypting key (kek) for important keys, when that kek exists only inside a single adapter.

  • Retained Key List (CSNDRKL) lists the retained keys inside an adapter.
  • Retained Key Delete (CSNDRKD) deletes a retained key from adapter internal storage.