forked from GitHub-Mirror/riotX-android
Move javadoc to interface
This commit is contained in:
Benoit Marty
parent
ca98ff5864
commit
02d3fea4a9
@ -19,34 +19,168 @@ package im.vector.matrix.android.api.session.crypto.keysbackup
|
||||
import im.vector.matrix.android.api.MatrixCallback
|
||||
import im.vector.matrix.android.api.listeners.ProgressListener
|
||||
import im.vector.matrix.android.api.listeners.StepProgressListener
|
||||
import im.vector.matrix.android.internal.crypto.model.ImportRoomKeysResult
|
||||
import im.vector.matrix.android.internal.crypto.keysbackup.model.KeysBackupVersionTrust
|
||||
import im.vector.matrix.android.internal.crypto.keysbackup.model.MegolmBackupCreationInfo
|
||||
import im.vector.matrix.android.internal.crypto.keysbackup.model.rest.KeysVersion
|
||||
import im.vector.matrix.android.internal.crypto.keysbackup.model.rest.KeysVersionResult
|
||||
import im.vector.matrix.android.internal.crypto.model.ImportRoomKeysResult
|
||||
|
||||
// TODO Add doc from implementation
|
||||
interface KeysBackupService {
|
||||
/**
|
||||
* Retrieve the current version of the backup from the home server
|
||||
*
|
||||
* It can be different than keysBackupVersion.
|
||||
* @param callback onSuccess(null) will be called if there is no backup on the server
|
||||
*/
|
||||
fun getCurrentVersion(callback: MatrixCallback<KeysVersionResult?>)
|
||||
|
||||
/**
|
||||
* Create a new keys backup version and enable it, using the information return from [prepareKeysBackupVersion].
|
||||
*
|
||||
* @param keysBackupCreationInfo the info object from [prepareKeysBackupVersion].
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
fun createKeysBackupVersion(keysBackupCreationInfo: MegolmBackupCreationInfo, callback: MatrixCallback<KeysVersion>)
|
||||
|
||||
/**
|
||||
* Facility method to get the total number of locally stored keys
|
||||
*/
|
||||
fun getTotalNumbersOfKeys(): Int
|
||||
|
||||
/**
|
||||
* Facility method to get the number of backed up keys
|
||||
*/
|
||||
fun getTotalNumbersOfBackedUpKeys(): Int
|
||||
|
||||
/**
|
||||
* Start to back up keys immediately.
|
||||
*
|
||||
* @param progressListener the callback to follow the progress
|
||||
* @param callback the main callback
|
||||
*/
|
||||
fun backupAllGroupSessions(progressListener: ProgressListener?, callback: MatrixCallback<Unit>?)
|
||||
|
||||
/**
|
||||
* Check trust on a key backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
fun getKeysBackupTrust(keysBackupVersion: KeysVersionResult, callback: MatrixCallback<KeysBackupVersionTrust>)
|
||||
|
||||
/**
|
||||
* Return the current progress of the backup
|
||||
*/
|
||||
fun getBackupProgress(progressListener: ProgressListener)
|
||||
|
||||
/**
|
||||
* Get information about a backup version defined on the homeserver.
|
||||
*
|
||||
* It can be different than keysBackupVersion.
|
||||
* @param version the backup version
|
||||
* @param callback
|
||||
*/
|
||||
fun getVersion(version: String, callback: MatrixCallback<KeysVersionResult?>)
|
||||
|
||||
/**
|
||||
* This method fetches the last backup version on the server, then compare to the currently backup version use.
|
||||
* If versions are not the same, the current backup is deleted (on server or locally), then the backup may be started again, using the last version.
|
||||
*
|
||||
* @param callback true if backup is already using the last version, and false if it is not the case
|
||||
*/
|
||||
fun forceUsingLastVersion(callback: MatrixCallback<Boolean>)
|
||||
|
||||
/**
|
||||
* Check the server for an active key backup.
|
||||
*
|
||||
* If one is present and has a valid signature from one of the user's verified
|
||||
* devices, start backing up to it.
|
||||
*/
|
||||
fun checkAndStartKeysBackup()
|
||||
|
||||
fun addListener(listener: KeysBackupStateListener)
|
||||
|
||||
fun removeListener(listener: KeysBackupStateListener)
|
||||
|
||||
/**
|
||||
* Set up the data required to create a new backup version.
|
||||
* The backup version will not be created and enabled until [createKeysBackupVersion]
|
||||
* is called.
|
||||
* The returned [MegolmBackupCreationInfo] object has a `recoveryKey` member with
|
||||
* the user-facing recovery key string.
|
||||
*
|
||||
* @param password an optional passphrase string that can be entered by the user
|
||||
* when restoring the backup as an alternative to entering the recovery key.
|
||||
* @param progressListener a progress listener, as generating private key from password may take a while
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
fun prepareKeysBackupVersion(password: String?, progressListener: ProgressListener?, callback: MatrixCallback<MegolmBackupCreationInfo>)
|
||||
|
||||
/**
|
||||
* Delete a keys backup version. It will delete all backed up keys on the server, and the backup itself.
|
||||
* If we are backing up to this version. Backup will be stopped.
|
||||
*
|
||||
* @param version the backup version to delete.
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
fun deleteBackup(version: String, callback: MatrixCallback<Unit>?)
|
||||
|
||||
/**
|
||||
* Ask if the backup on the server contains keys that we may do not have locally.
|
||||
* This should be called when entering in the state READY_TO_BACKUP
|
||||
*/
|
||||
fun canRestoreKeys(): Boolean
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
* It adds (or removes) the signature of the current device to the authentication part of the keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param trust the trust to set to the keys backup.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
fun trustKeysBackupVersion(keysBackupVersion: KeysVersionResult, trust: Boolean, callback: MatrixCallback<Unit>)
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param recoveryKey the recovery key to challenge with the key backup public key.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
fun trustKeysBackupVersionWithRecoveryKey(keysBackupVersion: KeysVersionResult, recoveryKey: String, callback: MatrixCallback<Unit>)
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param password the pass phrase to challenge with the keyBackupVersion public key.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
fun trustKeysBackupVersionWithPassphrase(keysBackupVersion: KeysVersionResult, password: String, callback: MatrixCallback<Unit>)
|
||||
|
||||
/**
|
||||
* Restore a backup with a recovery key from a given backup version stored on the homeserver.
|
||||
*
|
||||
* @param keysVersionResult the backup version to restore from.
|
||||
* @param recoveryKey the recovery key to decrypt the retrieved backup.
|
||||
* @param roomId the id of the room to get backup data from.
|
||||
* @param sessionId the id of the session to restore.
|
||||
* @param stepProgressListener the step progress listener
|
||||
* @param callback Callback. It provides the number of found keys and the number of successfully imported keys.
|
||||
*/
|
||||
fun restoreKeysWithRecoveryKey(keysVersionResult: KeysVersionResult, recoveryKey: String, roomId: String?, sessionId: String?, stepProgressListener: StepProgressListener?, callback: MatrixCallback<ImportRoomKeysResult>)
|
||||
|
||||
/**
|
||||
* Restore a backup with a password from a given backup version stored on the homeserver.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to restore from.
|
||||
* @param password the password to decrypt the retrieved backup.
|
||||
* @param roomId the id of the room to get backup data from.
|
||||
* @param sessionId the id of the session to restore.
|
||||
* @param stepProgressListener the step progress listener
|
||||
* @param callback Callback. It provides the number of found keys and the number of successfully imported keys.
|
||||
*/
|
||||
fun restoreKeyBackupWithPassword(keysBackupVersion: KeysVersionResult, password: String, roomId: String?, sessionId: String?, stepProgressListener: StepProgressListener?, callback: MatrixCallback<ImportRoomKeysResult>)
|
||||
|
||||
val keysBackupVersion: KeysVersionResult?
|
||||
|
||||
@ -126,18 +126,6 @@ internal class KeysBackup(
|
||||
keysBackupStateManager.removeListener(listener)
|
||||
}
|
||||
|
||||
/**
|
||||
* Set up the data required to create a new backup version.
|
||||
* The backup version will not be created and enabled until [createKeysBackupVersion]
|
||||
* is called.
|
||||
* The returned [MegolmBackupCreationInfo] object has a `recoveryKey` member with
|
||||
* the user-facing recovery key string.
|
||||
*
|
||||
* @param password an optional passphrase string that can be entered by the user
|
||||
* when restoring the backup as an alternative to entering the recovery key.
|
||||
* @param progressListener a progress listener, as generating private key from password may take a while
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
override fun prepareKeysBackupVersion(password: String?,
|
||||
progressListener: ProgressListener?,
|
||||
callback: MatrixCallback<MegolmBackupCreationInfo>) {
|
||||
@ -193,12 +181,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new keys backup version and enable it, using the information return from [prepareKeysBackupVersion].
|
||||
*
|
||||
* @param keysBackupCreationInfo the info object from [prepareKeysBackupVersion].
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
override fun createKeysBackupVersion(keysBackupCreationInfo: MegolmBackupCreationInfo,
|
||||
callback: MatrixCallback<KeysVersion>) {
|
||||
val createKeysBackupVersionBody = CreateKeysBackupVersionBody()
|
||||
@ -237,13 +219,6 @@ internal class KeysBackup(
|
||||
.executeBy(taskExecutor)
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete a keys backup version. It will delete all backed up keys on the server, and the backup itself.
|
||||
* If we are backing up to this version. Backup will be stopped.
|
||||
*
|
||||
* @param version the backup version to delete.
|
||||
* @param callback Asynchronous callback
|
||||
*/
|
||||
override fun deleteBackup(version: String, callback: MatrixCallback<Unit>?) {
|
||||
CryptoAsyncHelper.getDecryptBackgroundHandler().post {
|
||||
// If we're currently backing up to this backup... stop.
|
||||
@ -279,10 +254,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Ask if the backup on the server contains keys that we may do not have locally.
|
||||
* This should be called when entering in the state READY_TO_BACKUP
|
||||
*/
|
||||
override fun canRestoreKeys(): Boolean {
|
||||
// Server contains more keys than locally
|
||||
val totalNumberOfKeysLocally = getTotalNumbersOfKeys()
|
||||
@ -306,27 +277,15 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Facility method to get the total number of locally stored keys
|
||||
*/
|
||||
override fun getTotalNumbersOfKeys(): Int {
|
||||
return cryptoStore.inboundGroupSessionsCount(false)
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
* Facility method to get the number of backed up keys
|
||||
*/
|
||||
override fun getTotalNumbersOfBackedUpKeys(): Int {
|
||||
return cryptoStore.inboundGroupSessionsCount(true)
|
||||
}
|
||||
|
||||
/**
|
||||
* Start to back up keys immediately.
|
||||
*
|
||||
* @param progressListener the callback to follow the progress
|
||||
* @param callback the main callback
|
||||
*/
|
||||
override fun backupAllGroupSessions(progressListener: ProgressListener?,
|
||||
callback: MatrixCallback<Unit>?) {
|
||||
// Get a status right now
|
||||
@ -377,12 +336,6 @@ internal class KeysBackup(
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Check trust on a key backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
override fun getKeysBackupTrust(keysBackupVersion: KeysVersionResult,
|
||||
callback: MatrixCallback<KeysBackupVersionTrust>) {
|
||||
// TODO Validate with François that this is correct
|
||||
@ -467,14 +420,6 @@ internal class KeysBackup(
|
||||
return keysBackupVersionTrust
|
||||
}
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
* It adds (or removes) the signature of the current device to the authentication part of the keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param trust the trust to set to the keys backup.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
override fun trustKeysBackupVersion(keysBackupVersion: KeysVersionResult,
|
||||
trust: Boolean,
|
||||
callback: MatrixCallback<Unit>) {
|
||||
@ -562,13 +507,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param recoveryKey the recovery key to challenge with the key backup public key.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
override fun trustKeysBackupVersionWithRecoveryKey(keysBackupVersion: KeysVersionResult,
|
||||
recoveryKey: String,
|
||||
callback: MatrixCallback<Unit>) {
|
||||
@ -588,13 +526,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Set trust on a keys backup version.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to check.
|
||||
* @param password the pass phrase to challenge with the keyBackupVersion public key.
|
||||
* @param callback block called when the operations completes.
|
||||
*/
|
||||
override fun trustKeysBackupVersionWithPassphrase(keysBackupVersion: KeysVersionResult,
|
||||
password: String,
|
||||
callback: MatrixCallback<Unit>) {
|
||||
@ -658,9 +589,6 @@ internal class KeysBackup(
|
||||
keysBackupStateListener = null
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the current progress of the backup
|
||||
*/
|
||||
override fun getBackupProgress(progressListener: ProgressListener) {
|
||||
CryptoAsyncHelper.getDecryptBackgroundHandler().post {
|
||||
val backedUpKeys = cryptoStore.inboundGroupSessionsCount(true)
|
||||
@ -670,16 +598,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore a backup with a recovery key from a given backup version stored on the homeserver.
|
||||
*
|
||||
* @param keysVersionResult the backup version to restore from.
|
||||
* @param recoveryKey the recovery key to decrypt the retrieved backup.
|
||||
* @param roomId the id of the room to get backup data from.
|
||||
* @param sessionId the id of the session to restore.
|
||||
* @param stepProgressListener the step progress listener
|
||||
* @param callback Callback. It provides the number of found keys and the number of successfully imported keys.
|
||||
*/
|
||||
override fun restoreKeysWithRecoveryKey(keysVersionResult: KeysVersionResult,
|
||||
recoveryKey: String,
|
||||
roomId: String?,
|
||||
@ -772,16 +690,6 @@ internal class KeysBackup(
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore a backup with a password from a given backup version stored on the homeserver.
|
||||
*
|
||||
* @param keysBackupVersion the backup version to restore from.
|
||||
* @param password the password to decrypt the retrieved backup.
|
||||
* @param roomId the id of the room to get backup data from.
|
||||
* @param sessionId the id of the session to restore.
|
||||
* @param stepProgressListener the step progress listener
|
||||
* @param callback Callback. It provides the number of found keys and the number of successfully imported keys.
|
||||
*/
|
||||
override fun restoreKeyBackupWithPassword(keysBackupVersion: KeysVersionResult,
|
||||
password: String,
|
||||
roomId: String?,
|
||||
@ -923,13 +831,6 @@ internal class KeysBackup(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get information about a backup version defined on the homeserver.
|
||||
*
|
||||
* It can be different than keysBackupVersion.
|
||||
* @param version the backup version
|
||||
* @param callback
|
||||
*/
|
||||
override fun getVersion(version: String,
|
||||
callback: MatrixCallback<KeysVersionResult?>) {
|
||||
getKeysBackupVersionTask
|
||||
@ -953,12 +854,6 @@ internal class KeysBackup(
|
||||
.executeBy(taskExecutor)
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieve the current version of the backup from the home server
|
||||
*
|
||||
* It can be different than keysBackupVersion.
|
||||
* @param callback onSuccess(null) will be called if there is no backup on the server
|
||||
*/
|
||||
override fun getCurrentVersion(callback: MatrixCallback<KeysVersionResult?>) {
|
||||
getKeysBackupLastVersionTask
|
||||
.configureWith(Unit)
|
||||
@ -981,12 +876,6 @@ internal class KeysBackup(
|
||||
.executeBy(taskExecutor)
|
||||
}
|
||||
|
||||
/**
|
||||
* This method fetches the last backup version on the server, then compare to the currently backup version use.
|
||||
* If versions are not the same, the current backup is deleted (on server or locally), then the backup may be started again, using the last version.
|
||||
*
|
||||
* @param callback true if backup is already using the last version, and false if it is not the case
|
||||
*/
|
||||
override fun forceUsingLastVersion(callback: MatrixCallback<Boolean>) {
|
||||
getCurrentVersion(object : MatrixCallback<KeysVersionResult?> {
|
||||
override fun onSuccess(data: KeysVersionResult?) {
|
||||
@ -1032,12 +921,6 @@ internal class KeysBackup(
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Check the server for an active key backup.
|
||||
*
|
||||
* If one is present and has a valid signature from one of the user's verified
|
||||
* devices, start backing up to it.
|
||||
*/
|
||||
override fun checkAndStartKeysBackup() {
|
||||
if (!isStucked) {
|
||||
// Try to start or restart the backup only if it is in unknown or bad state
|
||||
|
||||
Loading…
Reference in New Issue
Block a user