Package com.mku.salmon.streams

Class AesStream

java.lang.Object
com.mku.streams.RandomAccessStream
com.mku.salmon.streams.AesStream
public class AesStream extends RandomAccessStream
Stream wrapper provides AES-256 encryption, decryption, and integrity verification of a data stream.

  • Nested Class Summary

    Nested classes/interfaces inherited from class com.mku.streams.RandomAccessStream

    RandomAccessStream.SeekOrigin

  • Field Summary

    Fields inherited from class com.mku.streams.RandomAccessStream

    DEFAULT_BUFFER_SIZE

  • Constructor Summary

    Constructors
    Constructor
    Description
    AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream)
    Instantiate a new encrypted stream with a key, a nonce, and a base stream.
    AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format)
    Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally store the nonce information in the header, see EncryptionFormat.
    AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format, boolean integrity, byte[] hashKey)
    Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally enable integrity with a hash key and store the nonce and the integrity information in the header, see EncryptionFormat.
    AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format, boolean integrity, byte[] hashKey, int chunkSize)
    Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally enable integrity with a hash key and specified chunk size as well as store the nonce and the integrity information in the header, see EncryptionFormat.

  • Method Summary

    Modifier and Type
    Method
    Description
    InputStream
    asReadStream()
    Get a native buffered stream to use with 3rd party libraries.
    boolean
    canRead()
    If the stream is readable (only if EncryptionMode is EncryptionMode.Decrypt)
    boolean
    canSeek()
    If the stream is seekable (supported only if base stream is seekable).
    boolean
    canWrite()
    If the stream is writable (only if EncryptionMode is EncryptionMode.Encrypt)
    void
    close()
    Closes the stream and all resources associated with it (including the base stream).
    void
    flush()
    Flushes any buffered data to the base stream.
    static ProviderType
    getAesProviderType()
    Get the global AES provider type.
    int
    getAlignSize()
    Align size for performance calculating the integrity when available.
    long
    getBlock()
    Returns the current block value
    int
    getChunkSize()
    Returns the chunk size used to apply hash signature
    byte[]
    getCounter()
    Returns the current Counter value.
    EncryptionMode
    getEncryptionMode()
    Get the encryption mode see EncryptionMode.
    byte[]
    getHashKey()
    Returns a copy of the hash key.
    byte[]
    getKey()
    Returns a copy of the encryption key.
    long
    getLength()
    Provides the length of the actual transformed data (minus the header and integrity data).
    byte[]
    getNonce()
    Returns a copy of the nonce.
    static long
    getOutputSize(EncryptionMode mode, long length, EncryptionFormat format)
    Get the output size of the data to be transformed (encrypted or decrypted) including header and hashes.
    static long
    getOutputSize(EncryptionMode mode, long length, EncryptionFormat format, int chunkSize)
    Get the output size of the data to be transformed (encrypted or decrypted) including header and hashes for the specified chunk size.
    long
    getPosition()
    Provides the position of the stream relative to the data to be transformed.
    boolean
    hasIntegrity()
    If the stream has integrity embedded.
    boolean
    isAllowRangeWrite()
    Get the allowed range write option.
    boolean
    isIntegrityEnabled()
    Check if the stream has integrity enabled.
    int
    read(byte[] buffer, int offset, int count)
    Decrypts the data from the baseStream and stores them in the buffer provided.
    long
    seek(long offset, RandomAccessStream.SeekOrigin origin)
    Seek to a specific position on the stream.
    static void
    setAesProviderType(ProviderType aesProviderType)
    Set the global AES provider type.
    void
    setAllowRangeWrite(boolean value)
    Warning! Allow byte range encryption writes on a current stream.
    void
    setFailSilently(boolean value)
    Set to True if you want the stream to fail silently when integrity cannot be verified.
    void
    setLength(long value)
    Set the length of the base stream.
    void
    setPosition(long value)
    Sets the current position of the stream relative to the data to be transformed.
    void
    write(byte[] buffer, int offset, int count)
    Encrypts the data from the buffer and writes the result to the baseStream.

    Methods inherited from class com.mku.streams.RandomAccessStream

    copyTo, copyTo, copyTo, copyTo

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • AesStream

      public AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream) throws IOException
      Instantiate a new encrypted stream with a key, a nonce, and a base stream.

      If you read from the stream it will decrypt the data from the baseStream. If you write to the stream it will encrypt the data to the baseStream. The transformation is based on AES CTR Mode.

      Parameters:
      key - The AES key that is used to encrypt decrypt
      nonce - The nonce used for the initial counter
      encryptionMode - Encryption mode Encrypt or Decrypt this cannot change later
      baseStream - The base Stream that will be used to read the data
      Throws:
      IOException - Thrown if there is an IO error.
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.
      See Also:

    • AesStream

      public AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format) throws IOException
      Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally store the nonce information in the header, see EncryptionFormat.

      If you read from the stream it will decrypt the data from the baseStream. If you write to the stream it will encrypt the data to the baseStream. The transformation is based on AES CTR Mode.

      Parameters:
      key - The AES key that is used to encrypt decrypt
      nonce - The nonce used for the initial counter
      encryptionMode - Encryption mode Encrypt or Decrypt this cannot change later
      baseStream - The base Stream that will be used to read the data
      format - The format to use, see EncryptionFormat
      Throws:
      IOException - Thrown if there is an IO error.
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.
      See Also:

    • AesStream

      public AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format, boolean integrity, byte[] hashKey) throws IOException
      Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally enable integrity with a hash key and store the nonce and the integrity information in the header, see EncryptionFormat.

      If you read from the stream it will decrypt the data from the baseStream. If you write to the stream it will encrypt the data to the baseStream. The transformation is based on AES CTR Mode.

      Parameters:
      key - The AES key that is used to encrypt decrypt
      nonce - The nonce used for the initial counter. If mode is Decrypt and format is Salmon then use null.
      encryptionMode - Encryption mode Encrypt or Decrypt this cannot change later
      baseStream - The base Stream that will be used to read the data
      format - The format to use, see EncryptionFormat
      integrity - True to enable integrity verification
      hashKey - Hash key to be used with integrity
      Throws:
      IOException - Thrown if there is an IO error.
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.
      See Also:

    • AesStream

      public AesStream(byte[] key, byte[] nonce, EncryptionMode encryptionMode, RandomAccessStream baseStream, EncryptionFormat format, boolean integrity, byte[] hashKey, int chunkSize) throws IOException
      Instantiate a new encrypted stream with a key, a nonce, a base stream, and optionally enable integrity with a hash key and specified chunk size as well as store the nonce and the integrity information in the header, see EncryptionFormat.

      If you read from the stream it will decrypt the data from the baseStream. If you write to the stream it will encrypt the data to the baseStream. The transformation is based on AES CTR Mode.

      Notes: The initial value of the counter is a result of the concatenation of an 12 byte nonce and an additional 4 bytes counter. The counter is then: incremented every block, encrypted by the key, and xored with the plain text.

      Parameters:
      key - The AES key that is used to encrypt decrypt
      nonce - The nonce used for the initial counter
      encryptionMode - Encryption mode Encrypt or Decrypt this cannot change later
      baseStream - The base Stream that will be used to read the data
      format - The format to use, see EncryptionFormat
      integrity - True to enable integrity verification
      hashKey - Hash key to be used with integrity
      chunkSize - the chunk size to be used with integrity
      Throws:
      IOException - Thrown if there is an IO error.
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.
      See Also:

  • Method Details

    • getAlignSize

      public int getAlignSize()
      Align size for performance calculating the integrity when available.
      Overrides:
      getAlignSize in class RandomAccessStream
      Returns:
      The align size

    • getOutputSize

      public static long getOutputSize(EncryptionMode mode, long length, EncryptionFormat format)
      Get the output size of the data to be transformed (encrypted or decrypted) including header and hashes. This can be used for efficient memory pre-allocation.
      Parameters:
      mode - The EncryptionMode Encrypt or Decrypt.
      length - The length of the data to transform.
      format - The format to use, see EncryptionFormat
      Returns:
      The size of the output data.
      Throws:
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.

    • getOutputSize

      public static long getOutputSize(EncryptionMode mode, long length, EncryptionFormat format, int chunkSize)
      Get the output size of the data to be transformed (encrypted or decrypted) including header and hashes for the specified chunk size. This can be used for efficient memory pre-allocation.
      Parameters:
      mode - The EncryptionMode Encrypt or Decrypt.
      length - The length of the data to transform.
      format - The format to use, see EncryptionFormat
      chunkSize - the chunk size to be used with integrity
      Returns:
      The size of the output data.
      Throws:
      SecurityException - Thrown if there is a security exception
      IntegrityException - Thrown if the data are corrupt or tampered with.

    • setAesProviderType

      public static void setAesProviderType(ProviderType aesProviderType)
      Set the global AES provider type. Supported types: ProviderType.
      Parameters:
      aesProviderType - The provider Type.

    • getAesProviderType

      public static ProviderType getAesProviderType()
      Get the global AES provider type. Supported types: ProviderType.
      Returns:
      The provider Type.

    • getLength

      public long getLength()
      Provides the length of the actual transformed data (minus the header and integrity data).
      Specified by:
      getLength in class RandomAccessStream
      Returns:
      The length of the stream.

    • getPosition

      public long getPosition() throws IOException
      Provides the position of the stream relative to the data to be transformed.
      Specified by:
      getPosition in class RandomAccessStream
      Returns:
      The current position of the stream.
      Throws:
      IOException - Thrown if there is an IO error.

    • setPosition

      public void setPosition(long value) throws IOException
      Sets the current position of the stream relative to the data to be transformed.
      Specified by:
      setPosition in class RandomAccessStream
      Parameters:
      value - The new position
      Throws:
      IOException - Thrown if there is an IO error.

    • canRead

      public boolean canRead()
      If the stream is readable (only if EncryptionMode is EncryptionMode.Decrypt)
      Specified by:
      canRead in class RandomAccessStream
      Returns:
      True if mode is decryption.

    • canSeek

      public boolean canSeek()
      If the stream is seekable (supported only if base stream is seekable).
      Specified by:
      canSeek in class RandomAccessStream
      Returns:
      True if stream is seekable.

    • canWrite

      public boolean canWrite()
      If the stream is writable (only if EncryptionMode is EncryptionMode.Encrypt)
      Specified by:
      canWrite in class RandomAccessStream
      Returns:
      True if mode is decryption.

    • hasIntegrity

      public boolean hasIntegrity()
      If the stream has integrity embedded.
      Returns:
      True if the stream has integrity embedded.

    • seek

      public long seek(long offset, RandomAccessStream.SeekOrigin origin) throws IOException
      Seek to a specific position on the stream. This does not include the header and any hash Signatures.
      Specified by:
      seek in class RandomAccessStream
      Parameters:
      offset - The offset that seek will use
      origin - If it is Begin the offset will be the absolute position from the start of the stream If it is Current the offset will be added to the current position of the stream If it is End the offset will be the absolute position starting from the end of the stream.
      Returns:
      The position after the seeking was complete.
      Throws:
      IOException - Thrown if there is an IO error.

    • setLength

      public void setLength(long value)
      Set the length of the base stream. Currently unsupported.
      Specified by:
      setLength in class RandomAccessStream
      Parameters:
      value - The new length

    • flush

      public void flush()
      Flushes any buffered data to the base stream.
      Specified by:
      flush in class RandomAccessStream

    • close

      public void close() throws IOException
      Closes the stream and all resources associated with it (including the base stream).
      Specified by:
      close in class RandomAccessStream
      Throws:
      IOException - Thrown if there is an IO error.

    • getCounter

      public byte[] getCounter()
      Returns the current Counter value.
      Returns:
      The current Counter value.

    • getBlock

      public long getBlock()
      Returns the current block value
      Returns:
      The current block

    • getKey

      public byte[] getKey()
      Returns a copy of the encryption key.
      Returns:
      The current key

    • getHashKey

      public byte[] getHashKey()
      Returns a copy of the hash key.
      Returns:
      The current hash key

    • getNonce

      public byte[] getNonce()
      Returns a copy of the nonce.
      Returns:
      The nonce.

    • getChunkSize

      public int getChunkSize()
      Returns the chunk size used to apply hash signature
      Returns:
      The chunk size

    • setAllowRangeWrite

      public void setAllowRangeWrite(boolean value)
      Warning! Allow byte range encryption writes on a current stream. Overwriting is not a good idea because it will re-use the same IV. This is not recommended if you use the stream on storing files or generally data if prior version can be inspected by others. You should only use this setting for initial encryption with parallel streams and not for overwriting!
      Parameters:
      value - True to allow byte range encryption write operations

    • setFailSilently

      public void setFailSilently(boolean value)
      Set to True if you want the stream to fail silently when integrity cannot be verified. In that case read() operations will return -1 instead of raising an exception. This prevents 3rd party code like media players from crashing.
      Parameters:
      value - True to fail silently.

    • read

      public int read(byte[] buffer, int offset, int count) throws IOException
      Decrypts the data from the baseStream and stores them in the buffer provided.
      Specified by:
      read in class RandomAccessStream
      Parameters:
      buffer - The buffer that the data will be stored after decryption
      offset - The start position on the buffer that data will be written.
      count - The requested count of the data bytes that should be decrypted
      Returns:
      The number of data bytes that were decrypted.
      Throws:
      IOException - Thrown if there is an IO error.

    • write

      public void write(byte[] buffer, int offset, int count) throws IOException
      Encrypts the data from the buffer and writes the result to the baseStream. If you are using integrity you will need to align all write operations to the chunk size otherwise align to the encryption block size.
      Specified by:
      write in class RandomAccessStream
      Parameters:
      buffer - The buffer that contains the data that will be encrypted
      offset - The offset in the buffer that the bytes will be encrypted.
      count - The length of the bytes that will be encrypted.
      Throws:
      IOException - Thrown if there is an IO error.

    • asReadStream

      public InputStream asReadStream()
      Get a native buffered stream to use with 3rd party libraries.
      Overrides:
      asReadStream in class RandomAccessStream
      Returns:
      The native read stream

    • isIntegrityEnabled

      public boolean isIntegrityEnabled()
      Check if the stream has integrity enabled.
      Returns:
      True if integrity is enabled

    • getEncryptionMode

      public EncryptionMode getEncryptionMode()
      Get the encryption mode see EncryptionMode.
      Returns:
      The encryption mode

    • isAllowRangeWrite

      public boolean isAllowRangeWrite()
      Get the allowed range write option. This can check if you can use random access write. This is generally not a good option since it prevents reusing the same nonce/counter.
      Returns:
      True if the stream allowed to seek and write.