Class CipherCrypto

java.lang.Object
org.cojen.tupl.ext.CipherCrypto
All Implemented Interfaces:
Crypto
public class CipherCrypto extends Object implements Crypto
Crypto implementation which uses Cipher and defaults to the AES algorithm. An encrypted salt-sector initialization vector (ESSIV) scheme is applied to all data pages in the main database file, where the initialization vector is defined as encrypt(iv=dataPageIndex, key=dataPageKey, data=dataPageSalt). The key and salt values are randomly generated when the database is created, and they are stored in the database header pages. The initialization vector for the header pages is randomly generated each time and is stored cleartext in the header pages. The secret key given to the constructor is used for encrypting header pages, and for any redo log files.

  • Constructor Details

    • CipherCrypto

      public CipherCrypto(int keySize) throws GeneralSecurityException
      Construct with a new key, available from the secretKey method.
      Parameters:
      keySize - key size in bits (with AES: 128, 192, or 256)
      Throws:
      GeneralSecurityException

    • CipherCrypto

      public CipherCrypto(byte[] encodedKey)
      Construct with an existing key, which is wrapped with SecretKeySpec, although additional keys might need to be generated. The key size must be permitted by the underlying algorithm, which for AES must be 128, 192, or 256 bits (16, 24, or 32 bytes).

    • CipherCrypto

      public CipherCrypto(SecretKey key, int keySize)
      Construct with an existing key, although additional keys might need to be generated.
      Parameters:
      keySize - key size in bits for additional keys (with AES: 128, 192, or 256)

  • Method Details

    • main

      public static void main(String[] args) throws Exception
      Generates and prints a new 128-bit key. Pass an argument to specify an alternate key size.
      Throws:
      Exception

    • factory

      public static Supplier<Crypto> factory(byte[] encodedKey)
      Construct with an existing key, which is wrapped with SecretKeySpec, although additional keys might need to be generated. The key size must be permitted by the underlying algorithm, which for AES must be 128, 192, or 256 bits (16, 24, or 32 bytes).

    • factory

      public static Supplier<Crypto> factory(SecretKey key, int keySize)
      Construct with an existing key, although additional keys might need to be generated.
      Parameters:
      keySize - key size in bits for additional keys (with AES: 128, 192, or 256)

    • secretKey

      public SecretKey secretKey()
      Provides access to the generated secret key.
      Throws:
      IllegalStateException - if key was passed into the constructor

    • encryptPage

      public final void encryptPage(long pageIndex, int pageSize, long srcAddr, int srcOffset, long dstAddr, int dstOffset) throws GeneralSecurityException
      Description copied from interface: Crypto
      Called by multiple threads to encrypt a fixed-size database page. Encrypted length must exactly match original length.
      Specified by:
      encryptPage in interface Crypto
      Parameters:
      pageIndex - page index within database
      srcAddr - original unencrypted page
      srcOffset - offset into unencrypted page
      dstAddr - destination for encrypted page
      dstOffset - offset into encrypted page
      Throws:
      GeneralSecurityException

    • decryptPage

      public final void decryptPage(long pageIndex, int pageSize, long srcAddr, int srcOffset, long dstAddr, int dstOffset) throws GeneralSecurityException
      Description copied from interface: Crypto
      Called by multiple threads to decrypt a fixed-size database page. Decrypted length must exactly match encrypted length.
      Specified by:
      decryptPage in interface Crypto
      Parameters:
      pageIndex - page index within database
      srcAddr - encrypted page
      srcOffset - offset into encrypted page
      dstAddr - destination for decrypted page
      dstOffset - offset into decrypted page
      Throws:
      GeneralSecurityException

    • newEncryptingStream

      public final OutputStream newEncryptingStream(OutputStream out) throws GeneralSecurityException, IOException
      Description copied from interface: Crypto
      Called to wrap an OutputStream for supporting encryption. Implementation of this method must be thread-safe, but the stream doesn't need to be.
      Specified by:
      newEncryptingStream in interface Crypto
      Parameters:
      out - encrypted data destination
      Returns:
      stream which encrypts all data
      Throws:
      GeneralSecurityException
      IOException

    • newDecryptingStream

      public final InputStream newDecryptingStream(InputStream in) throws GeneralSecurityException, IOException
      Description copied from interface: Crypto
      Called to wrap an InputStream for supporting decryption. Implementation of this method must be thread-safe, but the stream doesn't need to be.
      Specified by:
      newDecryptingStream in interface Crypto
      Parameters:
      in - encrypted data source
      Returns:
      stream which decrypts all data
      Throws:
      GeneralSecurityException
      IOException

    • toString

      public static String toString(SecretKey key)
      Returns a String with a parseable Java byte array declaration.

    • toString

      public static String toString(byte[] key)
      Returns a String with a parseable Java byte array declaration.

    • algorithm

      protected String algorithm()
      Returns "AES" by default; override to change the algorithm.

    • generateKey

      protected SecretKey generateKey(int keySize) throws GeneralSecurityException
      Called to generate a key, using the algorithm and the given key size (bits). In general, this method is only called when creating a new database. Afterwards, the generated keys cannot change, and this method won't be called again.
      Throws:
      GeneralSecurityException

    • newCipher

      protected Cipher newCipher(String transformation) throws GeneralSecurityException
      Called to instantiate all Cipher instances, with the given transformation.
      Throws:
      GeneralSecurityException

    • newPageCipher

      protected Cipher newPageCipher() throws GeneralSecurityException
      Called to instantiate a Cipher for encrypting and decrypting regular database pages, using the fixed instance algorithm. Default mode applied is CTR, with no padding.
      Throws:
      GeneralSecurityException

    • newStreamCipher

      protected Cipher newStreamCipher() throws GeneralSecurityException
      Called to instantiate a Cipher for encrypting and decrypting header pages and redo logs, using the fixed instance algorithm. Default mode applied is CTR, with no padding.
      Throws:
      GeneralSecurityException

    • initCipher

      protected void initCipher(Cipher cipher, int opmode, SecretKey key) throws GeneralSecurityException
      Called to initialize a new or re-used Cipher, generating a random initialization vector.
      Throws:
      GeneralSecurityException

    • initCipher

      protected void initCipher(Cipher cipher, int opmode, SecretKey key, IvParameterSpec ivSpec) throws GeneralSecurityException
      Called to initialize a new or re-used Cipher, using the given initialization vector.
      Throws:
      GeneralSecurityException