Class CipherSession
- java.lang.Object
-
- org.syncany.crypto.CipherSession
-
public class CipherSession extends java.lang.Object
The cipher session is used by theMultiCipherOutputStream
and theMultiCipherInputStream
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 perCipherSpec
. - 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.
- Keys used by
-
-
Constructor Summary
Constructors Constructor Description CipherSession(SaltedSecretKey masterKey)
Creates a new cipher session, using the given master key.CipherSession(SaltedSecretKey masterKey, int secretKeyReadCacheSize, int secretKeyWriteReuseCount)
Creates a new cipher session, using the given master key.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description javax.crypto.SecretKey
getMasterKey()
Returns the master keySaltedSecretKey
getReadSecretKey(CipherSpec cipherSpec, byte[] salt)
Creates a new secret key or retrieves it from the read cache.SaltedSecretKey
getWriteSecretKey(CipherSpec cipherSpec)
Creates or retrieves a derived write secret key and updates the cache and re-use count.
-
-
-
Constructor Detail
-
CipherSession
public CipherSession(SaltedSecretKey masterKey)
Creates a new cipher session, using the given master key. Derived keys will be created from that master key.The default settings for read/write key cache will be used. Refer to
the class description
for more details. Default values:DEFAULT_SECRET_KEY_READ_CACHE_SIZE
andDEFAULT_SECRET_KEY_WRITE_REUSE_COUNT
- Parameters:
masterKey
- The master key, used for deriving new read/write keys
-
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/writesecretKeyReadCacheSize
- 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 insecretKeyWriteReuseCount
(as set inthe 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 bysecretKeyReadCacheSize
(as set inthe 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 retrievalsalt
- 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
-
-