Class SecureKeySpec

java.lang.Object
org.jpos.security.SecureKeySpec
All Implemented Interfaces:
Serializable, Loggeable
public class SecureKeySpec extends Object implements Serializable, Loggeable
This class contains a set of desirable key properties that can be passed to an HSM device for example to generate a key or import it.

This class is not intended to use for key storage. It can contain confidentional data like key length. That is why they should not be kept persistently anywhere.

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 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 byte[]
    keyBytes
    Secure Key Bytes.
    protected byte[]
    keyCheckValue
    The keyCheckValue allows identifying which clear key does this secure key represent.
    protected int
    keyLength
    The key length is expressed in bits and refers to clear key (before LMK protection).
    protected String
    keyName
    Optional key name.
    protected String
    keyType
    Key Type is useful for stating what this key can be used for.
    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 final 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).
    protected KeyScheme
    scheme
    Key scheme indicates protection metchod appiled to this key by a security module.
    protected int
    variant
    Indicates key protection variant metchod appiled to this key by a security module.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SecureKeySpec()
    Default constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    dump(PrintStream p, String indent)
    Dumps SecureKeySpec information.
    protected String
    formKeyHeader(String indent)
    Renders the key-block header fields (version/usage/algorithm/etc.) as XML, indented for dump(PrintStream, String).
    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.
    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.
    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.
    int
    getKeyLength()
    Gets the length of the key.
    String
    getKeyName()
    Gets optional key name.
    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.
    int
    getVariant()
    Gets the key variant method used to protect this key.
    void
    setAlgorithm(Algorithm algorithm)
    Sets the cryptographic algorithm (byte 7 of the key block).
    void
    setExportability(Exportability exportability)
    Sets the exportability (byte 11 of the key block).
    void
    setKeyBlockMAC(byte[] keyBlockMAC)
    Sets the key block MAC.
    void
    setKeyBlockVersion(char keyBlockVersion)
    Sets the key-block version character (byte 0 of the key block).
    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.
    void
    setKeyLength(int keyLength)
    Sets the length of the key.
    void
    setKeyName(String keyName)
    Sets optional key name.
    void
    setKeyType(String keyType)
    Key Type is useful for stating what this key can be used for.
    void
    setKeyUsage(KeyUsage keyUsage)
    Sets the primary key usage (bytes 5-6 of the key block).
    void
    setKeyVersion(String keyVersion)
    Sets the key version (bytes 9-10 of the key block).
    void
    setModeOfUse(ModeOfUse modeOfUse)
    Sets the mode of use (byte 8 of the key block).
    void
    setReserved(String reserved)
    Sets the reserved field (bytes 14-15 of the key block).
    void
    setScheme(KeyScheme scheme)
    Key scheme indicates protection metchod appiled to this key by the security module.
    void
    setVariant(int variant)
    Sets key protection variant 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

    • scheme

      protected KeyScheme scheme
      Key scheme indicates protection metchod appiled to this key by a security module.

    • keyLength

      protected int keyLength
      The key length is expressed in bits and refers to clear key (before LMK protection).

    • keyType

      protected String keyType
      Key Type is useful for stating what this key can be used for.

      The value of Key Type specifies whether this encryped key is a

    • variant

      protected int variant
      Indicates key protection variant metchod appiled to this key by a security module.

    • keyBytes

      protected byte[] keyBytes
      Secure Key Bytes.

    • keyCheckValue

      protected byte[] keyCheckValue
      The keyCheckValue allows identifying which clear key does this secure key represent.

    • keyBlockVersion

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

    • 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 final 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.

    • keyName

      protected String keyName
      Optional key name.

  • Constructor Details

  • Method Details

    • setScheme

      public void setScheme(KeyScheme scheme)
      Key scheme indicates protection metchod appiled to this key by the security module.
      Parameters:
      scheme - key scheme used to protect this key.

    • getScheme

      public KeyScheme getScheme()
      Gets the key scheme used to protect this key.
      Returns:
      key scheme used to protect this key.

    • setKeyLength

      public void setKeyLength(int keyLength)
      Sets the length of the key.

      The key length is expressed in bits and refers to clear key (before LMK protection) This might be different than the bit length of the secureKeyBytes.

      Parameters:
      keyLength - clear key length in bits

    • getKeyLength

      public int getKeyLength()
      Gets the length of the key.

      The key length is expressed in bits and refers to clear key (before LMK protection)

      Returns:
      The length of the clear key

    • setKeyType

      public void setKeyType(String keyType)
      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

      Parameters:
      keyType - type of the key

    • getKeyType

      public String getKeyType()
      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

      Returns:
      keyType type of the key

    • setVariant

      public void setVariant(int variant)
      Sets key protection variant metchod appiled to this key by the security module.
      Parameters:
      variant - key variant method used to protect this key.

    • getVariant

      public int getVariant()
      Gets the key variant method used to protect this key.
      Returns:
      key variant method 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.

    • setKeyBlockVersion

      public void setKeyBlockVersion(char keyBlockVersion)
      Sets the key-block version character (byte 0 of the key block).
      Parameters:
      keyBlockVersion - the version character

    • 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.

    • setKeyUsage

      public void setKeyUsage(KeyUsage keyUsage)
      Sets the primary key usage (bytes 5-6 of the key block).
      Parameters:
      keyUsage - the new key usage

    • 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.

    • setAlgorithm

      public void setAlgorithm(Algorithm algorithm)
      Sets the cryptographic algorithm (byte 7 of the key block).
      Parameters:
      algorithm - the new algorithm

    • 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.

    • setModeOfUse

      public void setModeOfUse(ModeOfUse modeOfUse)
      Sets the mode of use (byte 8 of the key block).
      Parameters:
      modeOfUse - the new mode of use

    • 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.

    • setKeyVersion

      public void setKeyVersion(String keyVersion)
      Sets the key version (bytes 9-10 of the key block).
      Parameters:
      keyVersion - the new key version

    • 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.

    • setExportability

      public void setExportability(Exportability exportability)
      Sets the exportability (byte 11 of the key block).
      Parameters:
      exportability - the new exportability flag

    • 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.

    • setReserved

      public void setReserved(String reserved)
      Sets the reserved field (bytes 14-15 of the key block).
      Parameters:
      reserved - the new reserved value

    • 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:
      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.

    • setKeyBlockMAC

      public void setKeyBlockMAC(byte[] keyBlockMAC)
      Sets the key block MAC.
      Parameters:
      keyBlockMAC - the MAC bytes

    • setKeyBytes

      public void setKeyBytes(byte[] keyBytes)
      Sets the secure key bytes.
      Parameters:
      keyBytes - bytes representing the secured key

    • getKeyBytes

      public byte[] getKeyBytes()
      Returns the secure (LMK-protected) key bytes.
      Returns:
      The bytes representing the secured key

    • setKeyCheckValue

      public 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.

      This check value allows identifying if two secure keys map to the same clear key.

      Parameters:
      keyCheckValue - the Key Check Value

    • getKeyCheckValue

      public 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.
      Returns:
      the Key Check Value

    • getKeyName

      public String getKeyName()
      Gets optional key name.
      Returns:
      name of the key

    • setKeyName

      public void setKeyName(String keyName)
      Sets optional key name.
      Parameters:
      keyName - name of the key

    • dump

      public void dump(PrintStream p, String indent)
      Dumps SecureKeySpec information.
      Specified by:
      dump in interface Loggeable
      Parameters:
      p - a print stream usually supplied by Logger
      indent - indention string, usually suppiled by Logger
      See Also:

    • formKeyHeader

      protected String formKeyHeader(String indent)
      Renders the key-block header fields (version/usage/algorithm/etc.) as XML, indented for dump(PrintStream, String).
      Parameters:
      indent - indent prefix to apply to every emitted line
      Returns:
      the rendered header XML, or null if no header fields are set