Class SecureKey

java.lang.Object
org.jpos.security.SecureKey
All Implemented Interfaces:
Serializable, Loggeable
Direct Known Subclasses:
SecureKeyBlock, SecureVariantKey
public abstract class SecureKey extends Object implements Serializable, Loggeable
Represents a key that cannot be used except by your security module and for performing the operations allowed by the security module for this type of keys. So, a SecureKey can be safely stored in a clear file or database.

A SecureKey is typically a key encrypted under one of the secret keys that are protected by the security module itself (Local Master Keys --LMK for short).

SecureKey just holds:
1- Secure Key: a byte[] holding the key in the secure proprietary format of your security module. This is typically the clear key encrypted under LMK.
2- Key Type: identifies what this key can be used for (e.g. TYPE_ZPK (Zone PIN Key), TYPE_ZMK (Zone Master Key)...
3- Key Length (in bits): also called key size. e.g. LENGTH_DES, LENGTH_DES3_2KEY,...etc. This is not necessarily deducible from the length of the byte[] holding the secure key bytes, since encryption under LMK is proprietary to the security module.

NOTE: The security of SecureKey is totally dependent on the security of the used security module.

See Also:

  • Field Summary

    Fields
    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
    SecureKey()
    Default constructor; no instance state to initialise.

  • Method Summary

    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).
    short
    getKeyLength()
    Returns the clear-key length in bits.
    String
    getKeyName()
    Returns the optional key name.
    String
    getKeyType()
    Key Type is useful for stating what this key can be used for.
    abstract KeyScheme
    getScheme()
    Gets the key scheme used to protect this key.
    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
    setKeyLength(short keyLength)
    Sets the length of the key (in bits) (when it was still clear).
    void
    setKeyName(String keyName)
    Sets the optional key name.
    void
    setKeyType(String keyType)
    Key Type is useful for stating what this key can be used for.
    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, dump
    Modifier and Type
    Method
    Description
    void
    dump(PrintStream p, String indent)
    Dumps a human-readable representation of this object to the print stream.
    default void
    dump(PrintStream p, String indent, LogRenderer.Type type)
    Dumps a representation of this object using the specified renderer type.

  • Field Details

    • keyBytes

      protected byte[] keyBytes
      Secure Key Bytes

    • keyCheckValue

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

    • keyLength

      protected short keyLength
      This is the bit length of the key This can be: LENGTH_DES, LENGTH_DES3_2KEY, ...

    • 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 TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....

    • scheme

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

    • keyName

      protected String keyName
      Optional key name

  • Constructor Details

    • SecureKey

      protected SecureKey()
      Default constructor; no instance state to initialise.

  • Method Details

    • setKeyBytes

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

    • getKeyBytes

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

    • 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 (not in this class, but inside the security module). This check value allows identifying if two secure keys map to the same clear key.
      Parameters:
      keyCheckValue - 3-byte (or longer) 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 (not in this class, but inside the security module).
      Returns:
      the keyCheckValue that was set before by setKeyCheckValue()

    • setKeyLength

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

    • getKeyLength

      public short getKeyLength()
      Returns the clear-key length in bits.
      Returns:
      The Length of the secure key (when it was still clear)

    • 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 TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....
      Parameters:
      keyType - key-type label (e.g. TYPE_ZPK, TYPE_TMK)

    • 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 TYPE_TMK (Terminal Master Key), TYPE_ZPK (Zone PIN Key)....
      Returns:
      keyType

    • 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 abstract KeyScheme getScheme()
      Gets the key scheme used to protect this key.
      Returns:
      key scheme used to protect this key.

    • getKeyName

      public String getKeyName()
      Returns the optional key name.
      Returns:
      the configured key name, or null if none was set

    • setKeyName

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