Module org.cojen.tupl
Package org.cojen.tupl.ext

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 Summary

    Constructors
    Constructor
    Description
    CipherCrypto(byte[] encodedKey)
    Construct with an existing key, which is wrapped with SecretKeySpec, although additional keys might need to be generated.
    CipherCrypto(int keySize)
    Construct with a new key, available from the secretKey method.
    CipherCrypto(SecretKey key, int keySize)
    Construct with an existing key, although additional keys might need to be generated.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected String
    algorithm()
    Returns "AES" by default; override to change the algorithm.
    final void
    decryptPage(long pageIndex, int pageSize, byte[] src, int srcOffset, byte[] dst, int dstOffset)
    Called by multiple threads to decrypt a fixed-size database page.
    final void
    decryptPage(long pageIndex, int pageSize, long srcPtr, int srcOffset, long dstPtr, int dstOffset)
    Called by multiple threads to decrypt a fixed-size database page.
    final void
    encryptPage(long pageIndex, int pageSize, byte[] src, int srcOffset, byte[] dst, int dstOffset)
    Called by multiple threads to encrypt a fixed-size database page.
    final void
    encryptPage(long pageIndex, int pageSize, long srcPtr, int srcOffset, long dstPtr, int dstOffset)
    Called by multiple threads to encrypt a fixed-size database page.
    protected SecretKey
    generateKey(int keySize)
    Called to generate a key, using the algorithm and the given key size (bits).
    protected void
    initCipher(Cipher cipher, int opmode, SecretKey key)
    Called to initialize a new or re-used Cipher, generating a random initialization vector.
    protected void
    initCipher(Cipher cipher, int opmode, SecretKey key, IvParameterSpec ivSpec)
    Called to initialize a new or re-used Cipher, using the given initialization vector.
    static void
    main(String[] args)
    Generates and prints a new 128-bit key.
    protected Cipher
    newCipher(String transformation)
    Called to instantiate all Cipher instances, with the given transformation.
    final InputStream
    newDecryptingStream(InputStream in)
    Called to wrap an InputStream for supporting decryption.
    final OutputStream
    newEncryptingStream(OutputStream out)
    Called to wrap an OutputStream for supporting encryption.
    protected Cipher
    newPageCipher()
    Called to instantiate a Cipher for encrypting and decrypting regular database pages, using the fixed instance algorithm.
    protected Cipher
    newStreamCipher()
    Called to instantiate a Cipher for encrypting and decrypting header pages and redo logs, using the fixed instance algorithm.
    SecretKey
    secretKey()
    Provides access to the generated secret key.
    static String
    toString(byte[] key)
    Returns a String with a parseable Java byte array declaration.
    static String
    toString(SecretKey key)
    Returns a String with a parseable Java byte array declaration.

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.cojen.tupl.ext.Crypto

    decryptPage, decryptPage, encryptPage, encryptPage

  • 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) throws GeneralSecurityException
      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).
      Throws:
      GeneralSecurityException

    • CipherCrypto

      public CipherCrypto(SecretKey key, int keySize) throws GeneralSecurityException
      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)
      Throws:
      GeneralSecurityException

  • 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

    • 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, byte[] src, int srcOffset, byte[] dst, 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
      src - original unencrypted page
      srcOffset - offset into unencrypted page
      dst - destination for encrypted page
      dstOffset - offset into encrypted page
      Throws:
      GeneralSecurityException

    • encryptPage

      public final void encryptPage(long pageIndex, int pageSize, long srcPtr, int srcOffset, long dstPtr, 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
      srcPtr - original unencrypted page
      srcOffset - offset into unencrypted page
      dstPtr - destination for encrypted page
      dstOffset - offset into encrypted page
      Throws:
      GeneralSecurityException

    • decryptPage

      public final void decryptPage(long pageIndex, int pageSize, byte[] src, int srcOffset, byte[] dst, 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
      src - encrypted page
      srcOffset - offset into encrypted page
      dst - destination for decrypted page
      dstOffset - offset into decrypted page
      Throws:
      GeneralSecurityException

    • decryptPage

      public final void decryptPage(long pageIndex, int pageSize, long srcPtr, int srcOffset, long dstPtr, 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
      srcPtr - encrypted page
      srcOffset - offset into encrypted page
      dstPtr - 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