diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/crypto/keysbackup/KeysBackupService.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/crypto/keysbackup/KeysBackupService.kt index c044e6ae..061a6564 100644 --- a/matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/crypto/keysbackup/KeysBackupService.kt +++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/api/session/crypto/keysbackup/KeysBackupService.kt @@ -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) + + /** + * 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) + + /** + * 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?) + + /** + * 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) + + /** + * 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) + + /** + * 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) + + /** + * 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) + + /** + * 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?) + + /** + * 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) + + /** + * 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) + + /** + * 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) + + /** + * 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) + + /** + * 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) val keysBackupVersion: KeysVersionResult? diff --git a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/crypto/keysbackup/KeysBackup.kt b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/crypto/keysbackup/KeysBackup.kt index 18ca7ad0..810cc489 100644 --- a/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/crypto/keysbackup/KeysBackup.kt +++ b/matrix-sdk-android/src/main/java/im/vector/matrix/android/internal/crypto/keysbackup/KeysBackup.kt @@ -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) { @@ -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) { 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?) { 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?) { // 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) { // 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) { @@ -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) { @@ -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) { @@ -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) { 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) { 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) { getCurrentVersion(object : MatrixCallback { 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