Module org.cryptomator.cryptolib

Package org.cryptomator.cryptolib.common

Class MasterkeyFileAccess

java.lang.Object

org.cryptomator.cryptolib.common.MasterkeyFileAccess

public class MasterkeyFileAccess
extends Object

Allow loading and persisting of masterkeys from and to encrypted json files.

Requires a passphrase for derivation of a KEK.

        MasterkeyFileAccess masterkeyFileAccess = new MasterkeyFileAccess(pepper, csprng);
        try (Masterkey masterkey = masterkeyFileAccess.load(path, passphrase) {
                // use masterkey
  }
 

Constructor Summary

Constructors

Constructor	Description
MasterkeyFileAccess(byte[] pepper, SecureRandom csprng)

Method Summary

Modifier and Type	Method	Description
byte[]	changePassphrase(byte[] masterkey, CharSequence oldPassphrase, CharSequence newPassphrase)	Reencrypts a masterkey with a new passphrase.
void	changePassphrase(InputStream oldIn, OutputStream newOut, CharSequence oldPassphrase, CharSequence newPassphrase)
Masterkey	load(InputStream in, CharSequence passphrase)
Masterkey	load(Path filePath, CharSequence passphrase)	Loads the JSON contents from the given file and derives a KEK from the given passphrase to unwrap the contained keys.
void	persist(Masterkey masterkey, OutputStream out, CharSequence passphrase, int vaultVersion)
void	persist(Masterkey masterkey, Path filePath, CharSequence passphrase)	Derives a KEK from the given passphrase and wraps the key material from masterkey.
void	persist(Masterkey masterkey, Path filePath, CharSequence passphrase, int vaultVersion)
static int	readAllegedVaultVersion(byte[] masterkey)	Deprecated. Starting with vault format 8, the vault version is no longer stored inside the masterkey file.

Methods inherited from class java.lang.Object

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

Constructor Detail

MasterkeyFileAccess

public MasterkeyFileAccess(byte[] pepper,
                           SecureRandom csprng)

Method Detail

readAllegedVaultVersion

@Deprecated
public static int readAllegedVaultVersion(byte[] masterkey)
                                   throws IOException

Deprecated.

Starting with vault format 8, the vault version is no longer stored inside the masterkey file.

Parses the given masterkey file contents and returns the alleged vault version without verifying the version MAC.

Parameters:

masterkey - The file contents of a masterkey file.

Returns:

The (unverified) vault version

Throws:

IOException - In case of errors, such as unparseable JSON.

changePassphrase

public byte[] changePassphrase(byte[] masterkey,
                               CharSequence oldPassphrase,
                               CharSequence newPassphrase)
                        throws IOException,
                               InvalidPassphraseException

Reencrypts a masterkey with a new passphrase.

Parameters:

masterkey - The original JSON representation of the masterkey

oldPassphrase - The old passphrase

newPassphrase - The new passphrase

Returns:

A JSON representation of the masterkey, now encrypted with newPassphrase

Throws:

IOException - If failing to read, parse or write JSON

InvalidPassphraseException - If the wrong oldPassphrase has been supplied for the masterkey

changePassphrase

public void changePassphrase(InputStream oldIn,
                             OutputStream newOut,
                             CharSequence oldPassphrase,
                             CharSequence newPassphrase)
                      throws IOException,
                             InvalidPassphraseException

Throws:

IOException

InvalidPassphraseException

load

public Masterkey load(Path filePath,
                      CharSequence passphrase)
               throws MasterkeyLoadingFailedException

Loads the JSON contents from the given file and derives a KEK from the given passphrase to unwrap the contained keys.

Parameters:

filePath - Which file to load

passphrase - The passphrase used during key derivation

Returns:

A new masterkey. Should be used in a try-with-resource statement.

Throws:

InvalidPassphraseException - If the provided passphrase can not be used to unwrap the stored keys.

MasterkeyLoadingFailedException - If reading the masterkey file fails

load

public Masterkey load(InputStream in,
                      CharSequence passphrase)
               throws IOException

Throws:

IOException

persist

public void persist(Masterkey masterkey,
                    Path filePath,
                    CharSequence passphrase)
             throws IOException

Derives a KEK from the given passphrase and wraps the key material from masterkey. Then serializes the encrypted keys as well as used key derivation parameters into a JSON representation that will be stored at the given filePath.

Parameters:

masterkey - The key to protect

filePath - Where to store the file (gets overwritten, parent dir must exist)

passphrase - The passphrase used during key derivation

Throws:

IOException - When unable to write to the given file

persist

public void persist(Masterkey masterkey,
                    Path filePath,
                    CharSequence passphrase,
                    @Deprecated
                    int vaultVersion)
             throws IOException

Throws:

IOException

persist

public void persist(Masterkey masterkey,
                    OutputStream out,
                    CharSequence passphrase,
                    @Deprecated
                    int vaultVersion)
             throws IOException

Throws:

IOException