Class SecureKeyBlock

java.lang.Object
org.jpos.security.SecureKey
org.jpos.security.SecureKeyBlock
All Implemented Interfaces:
Serializable, Loggeable
public class SecureKeyBlock extends SecureKey
The class represents a secure key in key block form (TR-31 or derivatives).

In addition to standard Key Chcek Value and Key Schema, specifies the key block header, optional key block header, encrypted key and key block MAC.

The SecureKeyBlock instance can come from HSM (generate, import, translate) or from the key store. And this is an integral whole. Therefore, manipulation of key block values is not desirable. This is the reason why the key block setters methods are not available. Use the SecureKeyBlockBuilder to create the key block structure.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Algorithm
    algorithm
    The cryptographic algorithm with which the key contained in key block will be used.
    protected Exportability
    exportability
    The conditions under which the key can be exported outside the cryptographic domain.
    protected int
    keyBlockLength
    Entire key block length after encoding (header, optional header, encrypted confidential data, and MAC).
    protected byte[]
    keyBlockMAC
    The key block MAC ensures the integrity of the key block, and is calculated over the Header, Optional Header Blocks and the encrypted Key Data.
    protected char
    keyBlockVersion
    Identifies the method by which the key block is cryptographically protected and the content layout of the block.
    protected KeyUsage
    keyUsage
    The primary usage of the key contained in the key block.
    protected String
    keyVersion
    Version number to optionally indicate that the contents of the key block is a component (key part), or to prevent re-injection of an old key.
    protected ModeOfUse
    modeOfUse
    The operation that the key contained in the key block can perform.
    protected Map<String,String>
    optionalHeaders
    The TR-31 Key Block format allows a key block to contain up to 99 Optional Header Blocks which can be used to include additional (optional) data within the Key Block.
    protected String
    reserved
    This element is not specified by TR-31 (should contain two ASCII zeros).

    Fields inherited from class SecureKey

    keyBytes, keyCheckValue, keyLength, keyName, keyType, scheme
    Modifier and Type
    Field
    Description
    protected byte[]
    keyBytes
    Secure Key Bytes
    protected byte[]
    keyCheckValue
    The keyCheckValue allows identifying which clear key does this secure key represent.
    protected short
    keyLength
    This is the bit length of the key This can be: LENGTH_DES, LENGTH_DES3_2KEY, ...
    protected String
    keyName
    Optional key name
    protected String
    keyType
    Key Type is useful for stating what this key can be used for.
    protected KeyScheme
    scheme
    Key scheme indicates protection metchod appiled to this key by a security module.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    SecureKeyBlock()
    Constructs an SecureKeyBlock.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dump(PrintStream p, String indent)
    Dumps SecureKeyBlock basic information
    Algorithm
    getAlgorithm()
    The cryptographic algorithm with which the key contained in key block will be used.
    Exportability
    getExportability()
    The conditions under which the key can be exported outside the cryptographic domain.
    int
    getKeyBlockLength()
    Entire key block length after encoding (header, optional header, encrypted confidential data, and MAC).
    byte[]
    getKeyBlockMAC()
    The key block MAC ensures the integrity of the key block.
    char
    getKeyBlockVersion()
    Identifies the method by which the key block is cryptographically protected and the content layout of the block.
    short
    getKeyLength()
    Returns the clear-key length in bits.
    String
    getKeyType()
    Key Type is useful for stating what this key can be used for.
    KeyUsage
    getKeyUsage()
    The primary usage of the key contained in the key block.
    String
    getKeyVersion()
    Version number to optionally indicate that the contents of the key block is a component (key part), or to prevent re-injection of an old key.
    ModeOfUse
    getModeOfUse()
    The operation that the key contained in the key block can perform.
    Map<String,String>
    getOptionalHeaders()
    The key blok Optional Header Blocks.
    String
    getReserved()
    This element is not specified by TR-31 (should contain two ASCII zeros).
    KeyScheme
    getScheme()
    Gets the key scheme used to protect this key.
    void
    setKeyLength(short keyLength)
    Sets the length of the key (in bits) (when it was still clear).
    void
    setKeyType(String keyType)
    Key Type is useful for stating what this key can be used for.

    Methods inherited from class SecureKey

    getKeyBytes, getKeyCheckValue, getKeyName, setKeyBytes, setKeyCheckValue, setKeyName, setScheme
    Modifier and Type
    Method
    Description
    byte[]
    getKeyBytes()
    Returns the secure (LMK-protected) key bytes.
    byte[]
    getKeyCheckValue()
    The Key Check Value is typically a 24-bits (3 bytes) formed by encrypting a block of zeros under the secure key when the secure key is clear (not in this class, but inside the security module).
    String
    getKeyName()
    Returns the optional key name.
    void
    setKeyBytes(byte[] keyBytes)
    Sets the secure key bytes
    void
    setKeyCheckValue(byte[] keyCheckValue)
    The Key Check Value is typically a 24-bits (3 bytes) formed by encrypting a block of zeros under the secure key when the secure key is clear (not in this class, but inside the security module).
    void
    setKeyName(String keyName)
    Sets the optional key name.
    void
    setScheme(KeyScheme scheme)
    Key scheme indicates protection metchod appiled to this key by the security module.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface Loggeable

    dump
    Modifier and Type
    Method
    Description
    default void
    dump(PrintStream p, String indent, LogRenderer.Type type)
    Dumps a representation of this object using the specified renderer type.

  • Field Details

    • keyBlockVersion

      protected char keyBlockVersion
      Identifies the method by which the key block is cryptographically protected and the content layout of the block.

    • keyBlockLength

      protected int keyBlockLength
      Entire key block length after encoding (header, optional header, encrypted confidential data, and MAC).

    • keyUsage

      protected KeyUsage keyUsage
      The primary usage of the key contained in the key block.

    • algorithm

      protected Algorithm algorithm
      The cryptographic algorithm with which the key contained in key block will be used.

    • modeOfUse

      protected ModeOfUse modeOfUse
      The operation that the key contained in the key block can perform.

    • keyVersion

      protected String keyVersion
      Version number to optionally indicate that the contents of the key block is a component (key part), or to prevent re-injection of an old key.

    • exportability

      protected Exportability exportability
      The conditions under which the key can be exported outside the cryptographic domain.

    • reserved

      protected String reserved
      This element is not specified by TR-31 (should contain two ASCII zeros).

      In proprietary derivatives can be used as e.g: LMK identifier.

    • optionalHeaders

      protected Map<String,String> optionalHeaders
      The TR-31 Key Block format allows a key block to contain up to 99 Optional Header Blocks which can be used to include additional (optional) data within the Key Block.

    • keyBlockMAC

      protected byte[] keyBlockMAC
      The key block MAC ensures the integrity of the key block, and is calculated over the Header, Optional Header Blocks and the encrypted Key Data.

  • Constructor Details

    • SecureKeyBlock

      protected SecureKeyBlock()
      Constructs an SecureKeyBlock.

      It can be used internally by e.g: SecureKeyBlockBuilder.

  • Method Details

    • setKeyType

      public void setKeyType(String keyType)
      Description copied from class: SecureKey
      Key Type is useful for stating what this key can be used for. The value of Key Type specifies whether this secure key is a TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....
      Overrides:
      setKeyType in class SecureKey
      Parameters:
      keyType - key-type label (e.g. TYPE_ZPK, TYPE_TMK)

    • getKeyType

      public String getKeyType()
      Description copied from class: SecureKey
      Key Type is useful for stating what this key can be used for. The value of Key Type specifies whether this secure key is a TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....
      Overrides:
      getKeyType in class SecureKey
      Returns:
      keyType

    • setKeyLength

      public void setKeyLength(short keyLength)
      Description copied from class: SecureKey
      Sets the length of the key (in bits) (when it was still clear). This might be different than the bit length of the secureKeyBytes.
      Overrides:
      setKeyLength in class SecureKey
      Parameters:
      keyLength - clear key length in bits

    • getKeyLength

      public short getKeyLength()
      Description copied from class: SecureKey
      Returns the clear-key length in bits.
      Overrides:
      getKeyLength in class SecureKey
      Returns:
      The Length of the secure key (when it was still clear)

    • getScheme

      public KeyScheme getScheme()
      Description copied from class: SecureKey
      Gets the key scheme used to protect this key.
      Specified by:
      getScheme in class SecureKey
      Returns:
      key scheme used to protect this key.

    • getKeyBlockVersion

      public char getKeyBlockVersion()
      Identifies the method by which the key block is cryptographically protected and the content layout of the block.
      Returns:
      The key block version that corresponds to byte 0 of the key block.

    • getKeyBlockLength

      public int getKeyBlockLength()
      Entire key block length after encoding (header, optional header, encrypted confidential data, and MAC).
      Returns:
      The key block length that corresponds to bytes 1-4 of the key block.

    • getKeyUsage

      public KeyUsage getKeyUsage()
      The primary usage of the key contained in the key block.
      Returns:
      The key usage that corresponds to bytes 5-6 of the key block.

    • getAlgorithm

      public Algorithm getAlgorithm()
      The cryptographic algorithm with which the key contained in key block will be used.
      Returns:
      The key algorithm that corresponds to byte 7 of the key block.

    • getModeOfUse

      public ModeOfUse getModeOfUse()
      The operation that the key contained in the key block can perform.
      Returns:
      The mode of use that corresponds to byte 8 of the key block.

    • getKeyVersion

      public String getKeyVersion()
      Version number to optionally indicate that the contents of the key block is a component (key part), or to prevent re-injection of an old key.
      Returns:
      The key version that corresponds to bytes 9-10 of the key block.

    • getExportability

      public Exportability getExportability()
      The conditions under which the key can be exported outside the cryptographic domain.
      Returns:
      The key exportability that corresponds to byte 11 of the key block.

    • getReserved

      public String getReserved()
      This element is not specified by TR-31 (should contain two ASCII zeros).

      In proprietary derivatives can be used as e.g: LMK identifier.

      Returns:
      The reserved that corresponds to bytes 14-15 of the key block.

    • getOptionalHeaders

      public Map<String,String> getOptionalHeaders()
      The key blok Optional Header Blocks.

      The number of optional heders corresponds to bytes 12-13 of the key block.

      The order of the elements in the map is preserved by LinkedHashMap

      Returns:
      Read only map of Optional Key Blok Heders.

    • getKeyBlockMAC

      public byte[] getKeyBlockMAC()
      The key block MAC ensures the integrity of the key block.

      It is calculated over the Header, Optional Header Blocks and the encrypted Key Data. The length of the MAC depends on the type of LMK key:

      • 4 bytes for DES Key Block LMK
      • 8 bytes for AES Key Block LMK
      Returns:
      calculated key block MAC value.

    • dump

      public void dump(PrintStream p, String indent)
      Dumps SecureKeyBlock basic information
      Parameters:
      p - a PrintStream usually supplied by Logger
      indent - indention string, usually suppiled by Logger
      See Also: