package org.cryptomator.cryptolib.api;

import org.cryptomator.cryptolib.common.MasterkeyFileAccess;

import java.net.URI;

/**
 * Masterkey loaders load keys to unlock Cryptomator vaults.
 *
 * @see MasterkeyFileAccess
 */
@FunctionalInterface
public interface MasterkeyLoader {

	/**
	 * Loads a master key. This might be a long-running operation, as it may require user input or expensive computations.
	 *
	 * @param keyId An URI uniquely identifying the source and identity of the key
	 * @return The raw key bytes. Must not be null
	 * @throws MasterkeyLoadingFailedException Thrown when it is impossible to fulfill the request
	 */
	Masterkey loadKey(URI keyId) throws MasterkeyLoadingFailedException;

}

@@ -399,16 +399,389 @@
 ations.%0A
+%09 * %3Cp%3E%0A%09 * It is the caller's responsibility to destroy the returned %7B@link Masterkey%7D after usage by calling %7B@link Masterkey#destroy()%7D. This can easily be done using a try-with-resource block:%0A%09 * %3Cpre%3E%0A%09 * %7B@code%0A%09 * Masterkeyloader keyLoader;%0A%09 * URI keyId;%0A%09 * try (Masterkey key = keyLoader.loadKey(keyId) )%7B%0A%09 *     // Do stuff with the key%0A%09 * %7D%0A%09 * %7D%0A%09 * %3C/pre%3E%0A
 %09 *%0A%09 * 
@@ -868,17 +868,53 @@
 @return 
-T
+a %7B@link Masterkey%7D object wrapping t
 he raw k

improve documentation of the MasterkeyLoader interface