Change private key backup password with key name

Added two new methods:

• EThree.changePassword(keyName: String, oldPassword: String, newPassword: String) to change password of named backup of private key
• EThree.resetPrivateKeyBackupWithKeyName(keyName: String) to remove password of named backup of private key

Backup/restore private key with key name

Updated (extended) Backup & Restore methods

• We’ve updated (extended) Backup & Restore methods with the new parameter - key name, so you can backup a user's private key not only with the default key name but allow developers to define key name.
• Therefore, from now you can encrypt the same user’s private key a few times with different options (e.g. password) and backup it into the Virgil Cloud, then use any of the options (e.g. password) to restore the private key.

Bug fixing

• unregister deletes all cards of identify
• throw GroupException when user is trying to create a group that already exists

Encrypt shared stream

EThree encryptShared/decryptShared methods allows to encrypt stream with a generated key

e3kit Android Java/Kotlin v2.0.0

Added

• Kotlin-specific EThreeParams (with high order function for token callback);

Updated

• Some functions with @JvmOverloads to better support java;

Fixed

• Group#add function bug;

e3kit Android Java/Kotlin v0.8.0

Added

• Post-quantum keys support for peer-to-peer encryption (post-quantum group chats and double ratchet are coming later);
• New encrypted & authenticated data format including data padding & encrypted signature (authEncrypt & authDecrypt methods. Note that old decrypt is NOT able to decrypt data, encrypted by authEncrypt);
• Temporary channels - support of channels with unregistered users. Check out README for more information;
• Double Ratchet support. Check out README for more information;
• EThreeParams for easier customization of EThree;
• EThree.derivePasswords method to derive login and backup passwords from single one.
  Check out README for more info;
• EThreeBaseException. All EThree exceptions are extended from the EThreeBaseException from now;
• You can use "Text".toData() or ByteArray.toData() extension functions as well as Data#toBase64String() to easily work with Data class.
• Benchmarks;

Updated

• Virgil Core SDK to 7.1.0;
• Virgil Crypto to 0.12.0;
• Deprecated resetPrivateKeyBackup(password) method in favor of resetPrivateKeyBackup();
• Moved to Description in Exceptions. Please, check Appendix A to find out a matching between the old exceptions and the new ones. You can either find an updated info in functions docs;

Appendix A:

Kotlin

Move from the old exception structure:

try {
    // Exception-throwing code
} catch (exception: WrongPasswordException) {
    // Exception handling
}

To the new one:

try {
    // Exception-throwing code
} catch (exception: EThreeException) {
    when(exception.description) {
        EThreeException.Description.WRONG_PASSWORD -> {
            // Exception handling
        }
    }
}

Java

Move from the old exception structure:

try {
    // Exception-throwing code
} catch (WrongPasswordException exception) {
    // Exception handling
}

To the new one:

try {
    // Exception-throwing code
} catch (EThreeException exception) {
    switch (exception.description) {
        case EThreeException.Description.WRONG_PASSWORD:
            // Exception handling
            break;
        }
}

Exceptions mapping:

EThreeException:

• EThreeException(String?, Throwable?) -> EThreeException(Description, Throwable?) (EThreeException.Description.MISSING_PUBLIC_KEY)
• WrongPasswordException -> EThreeException (EThreeException.Description.WRONG_PASSWORD)
• ChangePasswordException -> EThreeException (EThreeException.Description.SAME_PASSWORD)
• UserNotRegisteredException -> EThreeException (EThreeException.Description.USER_IS_NOT_REGISTERED)
• AlreadyRegisteredException -> EThreeException (EThreeException.Description.USER_IS_ALREADY_REGISTERED)
• SignatureVerificationException -> EThreeException (EThreeException.Description.VERIFICATION_FAILED)
• ConversionException -> EThreeException (EThreeException.Description.STR_TO_DATA_FAILED)
• MissingIdentitiesException -> EThreeException (EThreeException.Description.MISSING_IDENTITIES)

KeyException:

• KeyException(String?, Throwable?) -> EThreeException(Description, Throwable?)
• PrivateKeyPresentException -> EThreeException (EThreeException.Description.PRIVATE_KEY_EXISTS)
• PrivateKeyNotFoundException -> EThreeException (EThreeException.Description.MISSING_PRIVATE_KEY)
• NoPrivateKeyBackupException -> EThreeException (EThreeException.Description.NO_PRIVATE_KEY_BACKUP)
• BackupKeyException -> EThreeException (EThreeException.Description.PRIVATE_KEY_BACKUP_EXISTS)

FindUsersException:

• FindUsersException(String?, Throwable?) -> FindUsersException(Description, Throwable?) (FindUsersException.Description.DUPLICATE_CARDS, FindUsersException.Description.MISSING_CACHED_CARD, FindUsersException.Description.CARD_WAS_NOT_FOUND)

RawGroupException:

• RawGroupException(String?, Throwable?) -> RawGroupException(Description, Throwable?) (RawGroupException.Description.EMPTY_TICKETS)
• FileGroupStorageException(String?, Throwable?) -> FileGroupStorageException(Description, Throwable?) (FileGroupStorageException.Description.INVALID_FILE_NAME, FileGroupStorageException.Description.EMPTY_FILE)

CardStorageException:

• CardStorageException(String?, Throwable?) -> SQLiteStorageException(Description, Throwable?)
• InconsistentCardStorageException -> SQLiteStorageException (SQLiteStorageException.Description.INCONSISTENT_DB)
• EmptyIdentitiesStorageException -> SQLiteStorageException (SQLiteStorageException.Description.EMPTY_IDENTITIES)

GroupException:

• GroupException(String?, Throwable?) -> GroupException(Description, Throwable?) (GroupException.Description.INVALID_GROUP)
• InvalidChangeParticipantsGroupException -> GroupException (GroupException.Description.INVALID_CHANGE_PARTICIPANTS)
• MissingCachedGroupException -> GroupException (GroupException.Description.MISSING_CACHED_GROUP)
• MessageNotFromThisGroupException -> GroupException (GroupException.Description.MESSAGE_NOT_FROM_THIS_GROUP)
• GroupIsOutdatedGroupException -> GroupException (GroupException.Description.GROUP_IS_OUTDATED)
• VerificationFailedGroupException -> GroupException (GroupException2.Description.VERIFICATION_FAILED)
• PermissionDeniedGroupException -> GroupException (GroupException.Description.GROUP_PERMISSION_DENIED)
• GroupNotFoundException -> GroupException (GroupException.Description.GROUP_WAS_NOT_FOUND)
• GroupIdTooShortException -> GroupException (GroupException.Description.SHORT_GROUP_ID)
• InvalidParticipantsCountGroupException -> GroupException (GroupException.Description.INVALID_PARTICIPANTS_COUNT)
• InconsistentStateGroupException -> GroupException (GroupException.Description.INCONSISTENT_STATE)

e3kit Android Java/Kotlin v0.6.1-beta1

• ethree-kotlin artifact name is deprecated and will be removed starting with v0.6.2-beta1 version;
• Artifact name has been changed from ethree-kotlin to ethree;
• Group chats added;
• Public keys cache added;
• e3kit enclave module has been added;
• lookupPublicKeys, encrypt(data/text, LookupResult), decrypt(data/text, VirgilPublicKey) are deprecated (check javadoc to find the new methods);
• OnCompleteListener, OnResultListener, Completable, Result - are moved to com.virgilsecurity.common package - just let Android Studio re-import them;
• LookupResult, OnGetTokenCallback - are moved to com.virgilsecurity.android.common;
• RegistrationException is replaced with EThreeExecption;

e3kit Android Java/Kotlin v0.5.1

• Renamed artifact from ethree-kotlin to ethree
• Updated Virgil Crypto library;
• Removed coroutines module;

e3kit Android Java/Kotlin v0.5.0

Added:

• Stream encryption;
• Unregister;
• Result and Completable;
• CoroutineScope control (usually for Kotlin);
• LookupResult typealias (for Kotlin only);
• lookupPublicKeys function overload with one identity;

Updated:

• lookupPublicKeys returns LookupResult;
• encrypt accepts LookupResult;

Fixed:

• rotatePrivateKey function;

Detailed info:

• Streams encryption: you can now encrypt streams. It's compatible with old data encryption, so you can encrypt/decrypt data->stream and vice versa. Stream encrypt doesn't sign encrypted data, and stream decrypt doesn't verify it. This is why stream decrypt doesn't need VirgilPublicKey unlike old data decrypt.
• Unregister: this function is used to revoke the public key on Virgil Cloud service. You'll be able to call register with the same identity after a successful unregister. (You cannot call register twice with the same identity without unregister)
• Result and Completable: Now all async functions can be executed synchronously in the current thread or in a background thread with a callback. This gives you the ability to easily use e3kit with other libraries, such as RxJava, RxKotlin, and others.

Result is used for functions that return some value. lookupPublicKeys now returns Result. You can get the value from this Result type synchronously by calling get(), or anynchronously via addCallback. Sample code:

Sync:

val lookupResult = eThree.lookupPublicKeys(identity).get()

Async:

eThree.lookupPublicKeys(identity)
       .addCallback(object : OnResultListener<LookupResult> {
           override fun onSuccess(result: LookupResult) {
               // Keys are here
           }

           override fun onError(throwable: Throwable) {
               // Handle error
           }
       })

Completable is used for functions that don't return any value. For example: register. You can execute this function synchronously by calling execute(), or anynchronously via addCallback. Sample code:
Sync:

eThree.register().execute()

Async:

eThree.register().addCallback(object : OnCompleteListener {
    override fun onSuccess() {
        // Successfully registered
    }

    override fun onError(throwable: Throwable) {
        // Handle error
    }
})

Java usage will be similar to Kotlin.

To migrate from an older version of e3kit (< 0.5.0) to this new version with Result and Completable, you have to move callback from method arguments to the addCallback method call.

• CoroutineScope control: it's possible to provide CoroutineScope in addCallback function as the scope argument. It gives you the possibility to choose what thread you're using for async calls, cancel async requests, provide request lifetime, etc. You can read more about CoroutineScope here. It's common to use coroutines in Kotlin, but you can use it from Java as well. You can check out e3kit tests for basic usage of Java+CoroutineScope, but it's recommended to use Kotlin instead.
• LookupResult typealias: It's an alias for Map<String, VirgilPublicKey> that can be used in Kotlin only. For Java nothing has changed - just use Map<String, VirgilPublicKey> as it was before.
• lookupPublicKeys function overload with one identity: there's no need to call lookupPublicKeys(listOf(identity)) anymore, just use lookupPublicKeys(identity) instead.

E3Kit Android Java/Kotlin v0.3.7

• Added missing hasLocalPrivateKey to coroutines package
• Added overloaded methods for resetPrivateKeyBackup function