Package org.syncany.crypto

Class CipherSession

  • public class CipherSession
extends java.lang.Object
    The cipher session is used by the MultiCipherOutputStream and the MultiCipherInputStream to reference the application's master key, and to temporarily store and retrieve derived secret keys.

    While a cipher session does not create a master key, it creates and manages the derived keys using the CipherUtil class:

    • Keys used by MultiCipherOutputStream (for writing new files) are reused a number of times before a new salted key is created. The main purpose of reusing keys is to increase performance. Because the master key is cryptographically strong, the derived keys can be reused a few times without any drawbacks on security. The class keeps one secret key per CipherSpec.
    • Keys used by MultiCipherInputStream (when reading files) are cached in order to minimize the amount of keys that have to be created when files are processed.

    • Constructor Detail

      • CipherSession

        public CipherSession​(SaltedSecretKey masterKey,
                     int secretKeyReadCacheSize,
                     int secretKeyWriteReuseCount)
        Creates a new cipher session, using the given master key. Derived keys will be created from that master key.

        This method expects a reuse-count for write keys and a cache size for the read-key cache. Refer to the class description for more details.

        Parameters:
        masterKey - The master key, used for deriving new read/write
        secretKeyReadCacheSize - Number of read keys to store in the cache (higher means more performance, but more memory usage)
        secretKeyWriteReuseCount - Number of times to reuse a write key (higher means more performance, but lower security)

    • Method Detail

      • getMasterKey

        public javax.crypto.SecretKey getMasterKey()
        Returns the master key

      • getWriteSecretKey

        public SaltedSecretKey getWriteSecretKey​(CipherSpec cipherSpec)
                                  throws java.lang.Exception
        Creates or retrieves a derived write secret key and updates the cache and re-use count. If a key is reused more than the threshold defined in secretKeyWriteReuseCount (as set in the constructor, a new key is created and added to the cache.

        If a new key needs to be created, CipherUtil is used to do so.

        Contrary to the read cache, the write cache key is a only CipherSpec, i.e. only one secret key per cipher spec can be held in the cache.

        Parameters:
        cipherSpec - Defines the type of key to be created (or retrieved); used as key for the cache retrieval
        Returns:
        Returns a newly created secret key or a cached key
        Throws:
        java.lang.Exception - If an error occurs with key creation

      • getReadSecretKey

        public SaltedSecretKey getReadSecretKey​(CipherSpec cipherSpec,
                                        byte[] salt)
                                 throws java.lang.Exception
        Creates a new secret key or retrieves it from the read cache. If the given cipher spec / salt combination is found in the cache, the cached secret key is returned. If not, a new key is created. Keys are removed from the cache when the cache reached the size defined by secretKeyReadCacheSize (as set in the constructor.

        If a new key needs to be created, CipherUtil is used to do so.

        Contrary to the write cache, the read cache key is a combination of CipherSpec and a salt. For each cipher spec, multiple salted keys can reside in the cache at the same time.

        Parameters:
        cipherSpec - Defines the type of key to be created (or retrieved); used as one part of the key for cache retrieval
        salt - Defines the salt for the key to be created (or retrieved); used as one part of the key for cache retrieval
        Returns:
        Returns a newly created secret key or a cached key
        Throws:
        java.lang.Exception - If an error occurs with key creation