Package org.whiteflagprotocol.java.crypto

Class WfCipher

java.lang.Object
org.whiteflagprotocol.java.crypto.WfCipher
All Implemented Interfaces:
Destroyable
public final class WfCipher extends Object implements Destroyable
Whiteflag cipher class

This class represents a Whiteflag cipher. Instances of this are used to encrypt and decrypt a Whiteflag messages. This class needs to be instantiated with a Whiteflag encryption key instance.

Since:
1.1
Whiteflag version:
v1-draft.6
Whiteflag standard x-reference:
5.2.3 Key and Token Derivation

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    IVBYTELENGTH
    The byte length of an initialisation vector

  • Method Summary

    Modifier and Type
    Method
    Description
    final byte[]
    decrypt(byte[] data)
    Decrypts the provided data
    final String
    decrypt(String data)
    Decrypts the provided data
    final void
    destroy()
    Destroys this Whiteflag cipher by clearing the encryption key
    final byte[]
    encrypt(byte[] data)
    Encrypts the provided data
    final String
    encrypt(String data)
    Encrypts the provided data
    static final WfCipher
    fromKey(WfEncryptionKey key)
    Creates a new Whiteflag cipher instance from a Whiteflag encryption key
    protected final byte[]
    getContext()
    Gets the current context to which the encryption key is bound
    final byte[]
    getInitVector()
    Gets the current initialisation vector
    final boolean
    isDestroyed()
    Determine if this Whiteflag cipher has been destroyed.
    final boolean
    isSet()
    Checks if the cipher has been fully set up for encryption or decryption.
    final WfCipher
    setContext(byte[] context)
    Sets the context to bind the encryption key; in Whiteflag this is usually the blockchain address of the message originator
    final WfCipher
    setContext(String context)
    Sets the context to bind the encryption key; in Whiteflag this is usually the blockchain address of the message originator
    final byte[]
    setInitVector()
    Generates a new random initialisation vector.
    final WfCipher
    setInitVector(byte[] initialisationVector)
    Sets the initialisation vector.
    final WfCipher
    setInitVector(String initialisationVector)
    Sets the initialisation vector.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • IVBYTELENGTH

      public static final int IVBYTELENGTH
      The byte length of an initialisation vector
      See Also:

  • Method Details

    • fromKey

      public static final WfCipher fromKey(WfEncryptionKey key) throws WfCryptoException
      Creates a new Whiteflag cipher instance from a Whiteflag encryption key
      Parameters:
      key - the encryption key
      Returns:
      a new Whiteflag cipher instance
      Throws:
      IllegalArgumentException - if the encryption key is invalid
      WfCryptoException - if the cipher could not be created

    • destroy

      public final void destroy() throws DestroyFailedException
      Destroys this Whiteflag cipher by clearing the encryption key
      Specified by:
      destroy in interface Destroyable
      Throws:
      DestroyFailedException - if the destroy operation fails
      IllegalStateException - if the encryption key has already been destroyed

    • isDestroyed

      public final boolean isDestroyed()
      Determine if this Whiteflag cipher has been destroyed.
      Specified by:
      isDestroyed in interface Destroyable
      Returns:
      TRUE if destroyed, else FALSE

    • setContext

      public final WfCipher setContext(String context)
      Sets the context to bind the encryption key; in Whiteflag this is usually the blockchain address of the message originator
      Parameters:
      context - a hexadecimal string with the context specific information required to derive the correct key
      Returns:
      this Whiteflag cipher object

    • setContext

      public final WfCipher setContext(byte[] context)
      Sets the context to bind the encryption key; in Whiteflag this is usually the blockchain address of the message originator
      Parameters:
      context - a byte array with the context specific information required to derive the correct key
      Returns:
      this Whiteflag cipher object

    • setInitVector

      public final byte[] setInitVector() throws WfCryptoException
      Generates a new random initialisation vector. This should be used when encrypting a new message.
      Returns:
      a byte array with the random initialisation vector
      Throws:
      WfCryptoException - if a random in initialization vector could not be generated

    • setInitVector

      public final WfCipher setInitVector(String initialisationVector)
      Sets the initialisation vector. This should only be used to decrypt a message.
      Parameters:
      initialisationVector - a hexadecimal string with the initialisation vector
      Returns:
      this Whiteflag cipher object

    • setInitVector

      public final WfCipher setInitVector(byte[] initialisationVector)
      Sets the initialisation vector. This should only be used to decrypt a message.
      Parameters:
      initialisationVector - a byte array with the initialisation vector
      Returns:
      this Whiteflag cipher object

    • getInitVector

      public final byte[] getInitVector()
      Gets the current initialisation vector
      Returns:
      a byte array with the initialisation vector

    • isSet

      public final boolean isSet()
      Checks if the cipher has been fully set up for encryption or decryption.
      Returns:
      TRUE if cipher has been fully set up, else FALSE

    • encrypt

      public final String encrypt(String data) throws WfCryptoException
      Encrypts the provided data
      Parameters:
      data - a hexadecimal string with the data to be encrypted
      Returns:
      a hexadecimal string with the encrypted data
      Throws:
      WfCryptoException - if data could not be encrypted

    • encrypt

      public final byte[] encrypt(byte[] data) throws WfCryptoException
      Encrypts the provided data
      Parameters:
      data - a byte array the data to be encrypted
      Returns:
      a byte array with the encrypted data
      Throws:
      IllegalStateException - if this cipher has not been fully set up or keys have been destroyed
      WfCryptoException - if data could not be encrypted

    • decrypt

      public final String decrypt(String data) throws WfCryptoException
      Decrypts the provided data
      Parameters:
      data - a hexadecimal string with the data to be decrypted
      Returns:
      a hexadecimal string with the decrypted data
      Throws:
      WfCryptoException - if data could not be decrypted

    • decrypt

      public final byte[] decrypt(byte[] data) throws WfCryptoException
      Decrypts the provided data
      Parameters:
      data - a byte array the data to be decrypted
      Returns:
      a byte array with the decrypted data
      Throws:
      IllegalStateException - if this cipher has not been fully set up or keys have been destroyed
      WfCryptoException - if data could not be decrypted

    • getContext

      protected final byte[] getContext()
      Gets the current context to which the encryption key is bound
      Returns:
      a byte array with the context, typically the blockchain address of the message originator