Package com.mku.salmon.streams

Class AesStream

  • public class AesStream
extends RandomAccessStream
    Stream wrapper provides AES-256 encryption, decryption, and integrity verification of a data stream.

    • 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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      long getBlock()
      Returns the current block value
      int getBufferSize()
      Get the internal buffer size.
      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 setBufferSize​(int bufferSize)
      Set the internal buffer size.
      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 java.lang.Object

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

    • Constructor Detail

      • AesStream

        public AesStream​(byte[] key,
                 byte[] nonce,
                 EncryptionMode encryptionMode,
                 RandomAccessStream baseStream)
          throws java.io.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:
        java.io.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:
        Salmon README.md

      • AesStream

        public AesStream​(byte[] key,
                 byte[] nonce,
                 EncryptionMode encryptionMode,
                 RandomAccessStream baseStream,
                 EncryptionFormat format)
          throws java.io.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:
        java.io.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:
        Salmon README.md

      • AesStream

        public AesStream​(byte[] key,
                 byte[] nonce,
                 EncryptionMode encryptionMode,
                 RandomAccessStream baseStream,
                 EncryptionFormat format,
                 boolean integrity,
                 byte[] hashKey)
          throws java.io.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:
        java.io.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:
        Salmon README.md

      • AesStream

        public AesStream​(byte[] key,
                 byte[] nonce,
                 EncryptionMode encryptionMode,
                 RandomAccessStream baseStream,
                 EncryptionFormat format,
                 boolean integrity,
                 byte[] hashKey,
                 int chunkSize)
          throws java.io.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:
        java.io.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:
        Salmon README.md

    • Method Detail

      • 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 java.io.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:
        java.io.IOException - Thrown if there is an IO error.

      • setPosition

        public void setPosition​(long value)
                 throws java.io.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:
        java.io.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 java.io.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:
        java.io.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 java.io.IOException
        Closes the stream and all resources associated with it (including the base stream).
        Specified by:
        close in class RandomAccessStream
        Throws:
        java.io.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 java.io.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:
        java.io.IOException - Thrown if there is an IO error.

      • write

        public void write​(byte[] buffer,
                  int offset,
                  int count)
           throws java.io.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:
        java.io.IOException - Thrown if there is an IO error.

      • isIntegrityEnabled

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

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

      • getBufferSize

        public int getBufferSize()
        Get the internal buffer size.
        Returns:
        The buffer size

      • setBufferSize

        public void setBufferSize​(int bufferSize)
        Set the internal buffer size.
        Parameters:
        bufferSize - The new buffer size