z/OS Cryptographic Services ICSF Application Programmer's Guide
Previous topic | Next topic | Contents | Index | Contact z/OS | Library | PDF


Specifying a Control-Vector-Base Value

z/OS Cryptographic Services ICSF Application Programmer's Guide
SA22-7522-16

You can determine the value of a control vector by working through the following series of questions:

  1. Begin with a field of 64 bits (eight bytes) set to B'0'. The most significant bit is referred to as bit 0. Define the key type and subtype (bits 8 to 14), as follows:
    • The main key type bits (bits 8 to 11). Set bits 8 to 11 to one of the following values:
      Bits 8 to 11Main Key Type
      0000Data operation keys
      0010PIN keys
      0011Cryptographic variable-encrypting keys
      0100Key-encrypting keys
      0101Key-generating keys
    • The key subtype bits (bits 12 to 14). Set bits 12 to 14 to one of the following values:
      Note:
      For Diversified Key Generating Keys, the subtype field specifies the hierarchical level of the DKYGENKY. If the subtype is non-zero, then the DKYGENKY can only generate another DKYGENKY key with the hierarchy level decremented by one. If the subtype is zero, the DKYGENKY can only generate the final diversified key ( a non-DKYGENKY key) with the key type specified by the usage bits.
      Bits 12 to 14Key Subtype
      Data Operation Keys
      000Compatibility key (DATA)
      001Confidentiality key (CIPHER, DECIPHER, or ENCIPHER)
      010MAC key (MAC or MACVER)
      Key-Encrypting Keys
      000Transport-sending keys (EXPORTER and OKEYXLAT)
      001Transport-receiving keys (IMPORTER and IKEYXLAT)
      PIN Keys
      001PIN-generating key (PINGEN, PINVER)
      000Inbound PIN-block decrypting key (IPINENC)
      010Outbound PIN-block encrypting key (OPINENC)
      Cryptographic Variable-Encrypting Keys
      111Cryptographic variable-encrypting key (CVAR....)
      Diversified Key Generating Keys
      000DKY Subtype 0
      001DKY Subtype 1
      010DKY Subtype 2
      011DKY Subtype 3
      100DKY Subtype 4
      101DKY Subtype 5
      110DKY Subtype 6
      111DKY Subtype 7
  2. For key-encrypting keys, set the following bits:
    • The key-generating usage bits (gks, bits 18 to 20). Set the gks bits to B'111' to indicate that the Key Generate callable service can use the associated key-encrypting key to encipher generated keys when the Key Generate callable service is generating various key-pair key-form combinations (see the Key-Encrypting Keys section of Figure 8). Without any of the gks bits set to 1, the Key Generate callable service cannot use the associated key-encrypting key. The Key Token Build callable service can set the gks bits to 1 when you supply the OPIM, IMEX, IMIM, OPEX, and EXEX keywords.
    • The IMPORT and EXPORT bit and the XLATE bit (ix, bits 21 and 22). If the ‘i’ bit is set to 1, the associated key-encrypting key can be used in the Data Key Import, Key Import, Data Key Export, and Key Export callable services. If the ‘x’ bit is set to 1, the associated key-encrypting key can be used in the Key Translate callable service.
    • The key-form bits (fff, bits 40 to 42). The key-form bits indicate how the key was generated and how the control vector participates in multiple-enciphering. To indicate that the parts can be the same value, set these bits to B'010'. For information about the value of the key-form bits in the right half of a control vector, see Step 8.
  3. For MAC and MACVER keys, set the following bits:
    • The MAC control bits (bits 20 and 21). For a MAC-generate key, set bits 20 and 21 to B'11'. For a MAC-verify key, set bits 20 and 21 to B'01'.
    • The key-form bits (fff, bits 40 to 42). For a single-length key, set the bits to B'000'. For a double-length key, set the bits to B'010'.
  4. For PINGEN and PINVER keys, set the following bits:
    • The PIN calculation method bits (aaaa, bits 0 to 3). Set these bits to one of the following values:
      Bits 0 to 3Calculation Method Keyword Description
      0000NO-SPECA key with this control vector can be used with any PIN calculation method.
      0001IBM-PIN or IBM-PINOA key with this control vector can be used only with the IBM PIN or PIN Offset calculation method.
      0010VISA-PVVA key with this control vector can be used only with the VISA-PVV calculation method.
      0100GBP-PIN or GBP-PINOA key with this control vector can be used only with the German Banking Pool PIN or PIN Offset calculation method.
      0011INBK-PINA key with this control vector can be used only with the Interbank PIN calculation method.
      0101NL-PIN-1A key with this control vector can be used only with the NL-PIN-1, Netherlands PIN calculation method.
    • The prohibit-offset bit (o, bit 37) to restrict operations to the PIN value. If set to 1, this bit prevents operation with the IBM 3624 PIN Offset calculation method and the IBM German Bank Pool PIN Offset calculation method.
  5. For PINGEN, IPINENC, and OPINENC keys, set bits 18 to 22 to indicate whether the key can be used with the following callable services
    Service AllowedBit NameBit
    Clear PIN GenerateCPINGEN18
    Encrypted PIN Generate AlternateEPINGENA19
    Encrypted PIN GenerateEPINGEN20 for PINGEN

    19 for OPINENC

    Clear PIN Generate AlternateCPINGENA21 for PINGEN

    20 for IPINENC

    Encrypted Pin VerifyEPINVER19
    Clear PIN EncryptCPINENC18
  6. For the IPINENC (inbound) and OPINENC (outbound) PIN-block ciphering keys, do the following:
    • Set the TRANSLAT bit (t, bit 21) to 1 to permit the key to be used in the PIN Translate callable service. The Control Vector Generate callable service can set the TRANSLAT bit to 1 when you supply the TRANSLAT keyword.
    • Set the REFORMAT bit (r, bit 22) to 1 to permit the key to be used in the PIN Translate callable service. The Control Vector Generate callable service can set the REFORMAT bit and the TRANSLAT bit to 1 when you supply the REFORMAT keyword.
  7. For the cryptographic variable-encrypting keys (bits 18 to 22), set the variable-type bits (bits 18 to 22) to one of the following values:
    Bits
    18 to 22
    Generic Key Type  Description
    00000CVARPINEUsed in the Encrypted PIN Generate Alternate service to encrypt a clear PIN.
    00010CVARXCVLUsed in the Control Vector Translate callable service to decrypt the left mask array.
    00011CVARXCVRUsed in the Control Vector Translate callable service to decrypt the right mask array.
    00100CVARENCUsed in the Cryptographic Variable Encipher callable service to encrypt an unformatted PIN.
  8. For key-generating keys, set the following bits:
    • For KEYGENKY, set bit 18 for UKPT usage and bit 19 for CLR8-ENC usage.
    • For DKYGENKY, bits 12–14 will specify the hierarchical level of the DKYGENKY key. If the subtype CV bits are non-zero, then the DKYGENKY can only generate another DKYGENKY key with the hierarchical level decremented by one. If the subtype CV bits are zero, the DKYGENKY can only generate the final diversified key (a non-DKYGENKY key) with the key type specified by usage bits.

      To specify the subtype values of the DKYGENKY, keywords DKYL0, DKYL1, DKYL2, DKYL3, DKYL4, DKYL5, DKYL6 and DKYL7 will be used.

    • For DKYGENKY, bit 18 is reserved and must be zero.
    • Usage bits 18-22 for the DKYGENKY key type are defined as follows. They will be encoded as the final key type that the DKYGENKY key generates.
      Bits
      19 to 22
      KeywordUsage
      0001DDATADATA, DATAC, single or double length
      0010DMACMAC, DATAM
      0011DMVMACVER, DATAMV
      0100DIMPIMPORTER, IKEYXLAT
      0101DEXPEXPORTER, OKEYXLAT
      0110DPVRPINVER
      1000DMKEYSecure message key for encrypting keys
      1001DMPINSecure message key for encrypting PINs
      1111DALLAll key types may be generated except DKYGENKY and KEYGENKY keys. Usage of the DALL keyword is controlled by a separate access control point.
  9. For secure messaging keys, set the following bits:
    • Set bit 18 to 1 if the key will be used in the secure messaging for PINs service. Set bit 19 to 1 if the key will be used in the secure messaging for keys service.
  10. For all keys, set the following bits:
    • The export bit (E, bit 17). If set to 0, the export bit prevents a key from being exported. By setting this bit to 0, you can prevent the receiver of a key from exporting or translating the key for use in another cryptographic subsystem. Once this bit is set to 0, it cannot be set to 1 by any service other than Control Vector Translate. The Prohibit Export callable service can reset the export bit.
    • The key-part bit (K, bit 44). Set the key-part bit to 1 in a control vector associated with a key part. When the final key part is combined with previously accumulated key parts, the key-part bit in the control vector for the final key part is set to 0. The Control Vector Generate callable service can set the key-part bit to 1 when you supply the KEY-PART keyword.
    • The anti-variant bits (bit 30 and bit 38). Set bit 30 to 0 and bit 38 to 1. Many cryptographic systems have implemented a system of variants where a 7-bit value is exclusive-ORed with each 7-bit group of a key-encrypting key before enciphering the target key. By setting bits 30 and 38 to opposite values, control vectors do not produce patterns that can occur in variant-based systems.
    • Control vector bits 64 to 127. If bits 40 to 42 are B'000' (single-length key), set bits 64 to 127 to 0. Otherwise, copy bits 0 to 63 into bits 64 to 127 and set bits 105 and 106 to B'01'.
    • Set the parity bits (low-order bit of each byte, bits 7, 15, ..., 127). These bits contain the parity bits (P) of the control vector. Set the parity bit of each byte so the number of zero-value bits in the byte is an even number.
    • For secure messaging keys, usage bit 18 on will enable the encryption of keys in a secure message and usage bit 19 on will enable the encryption of PINs in a secure message.
    • The ENH-ONLY bit (H, bit 56). Set the ENH-ONLY bit to 1 in a control vector to require the key value be encrypted with the enhanced wrapping. method. The Control Vector Generate callable service can set the ENH-ONLY bit to 1 when you supply the ENH-ONLY keyword.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014