Move Account management and related utils to synctools (#383)

* Add AccountManager extensions and Android account utilities

- Add `setAndVerifyUserData` extension function for reliable user data setting
- Add `AndroidAccountUtils` with `createAccount` function for account creation with verified user data

* Move SensitiveString and tests from DAVx5 to synctools

* Fix some issues

- Use `asString()` instead of `toString()` for `SensitiveString` in `createAccount`
- Improve KDoc

* Convert SensitiveString to value class and remove manual equals/hashCode

Author: rfc2822

lib/src/main/kotlin/at/bitfire/synctools/util/AccountManagerExtensions.kt

@@ -0,0 +1,33 @@
+/*
+ * This file is part of bitfireAT/synctools which is released under GPLv3.
+ * Copyright © All Contributors. See the LICENSE and AUTHOR files in the root directory for details.
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+package at.bitfire.synctools.util
+
+import android.accounts.Account
+import android.accounts.AccountManager
+import java.util.logging.Logger
+
+/**
+ * [AccountManager.setUserData] has been found to be unreliable at times. This extension function
+ * checks whether the user data has actually been set and retries up to ten times before it gives up,
+ * without throwing an Exception.
+ *
+ * Account user data should only be used to reference an own reliable storage.
+ */
+fun AccountManager.setAndVerifyUserData(account: Account, key: String, value: String?) {
+    for (i in 1..10) {
+        if (getUserData(account, key) == value)
+            return  /* already set / success */
+
+        setUserData(account, key, value)
+
+        // wait a bit because AccountManager access sometimes seems a bit asynchronous
+        Thread.sleep(100)
+    }
+
+    val logger = Logger.getLogger(javaClass.name)
+    logger.warning("AccountManager failed to set $account user data $key := $value")
+}

lib/src/main/kotlin/at/bitfire/synctools/util/AndroidAccountUtils.kt

@@ -0,0 +1,44 @@
+/*
+ * This file is part of bitfireAT/synctools which is released under GPLv3.
+ * Copyright © All Contributors. See the LICENSE and AUTHOR files in the root directory for details.
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+package at.bitfire.synctools.util
+
+import android.accounts.Account
+import android.accounts.AccountManager
+import android.content.Context
+import android.os.Bundle
+
+object AndroidAccountUtils {
+
+    /**
+     * Creates a system account and makes sure the user data are set correctly.
+     *
+     * @param context  operating context
+     * @param account  account to create
+     * @param userData user data to set
+     * @param password password to set
+     *
+     * @return whether the account has been created
+     */
+    fun createAccount(context: Context, account: Account, userData: Map<String, String>, password: SensitiveString? = null): Boolean {
+        val userDataBundle = Bundle(userData.size).apply {
+            for ((key, value) in userData)
+                putString(key, value)
+        }
+
+        // create account
+        val manager = AccountManager.get(context)
+        if (!manager.addAccountExplicitly(account, password?.asString(), userDataBundle))
+            return false
+
+        // Android seems to lose the initial user data sometimes, so make sure that the values are set
+        for ((key, value) in userData)
+            manager.setAndVerifyUserData(account, key, value)
+
+        return true
+    }
+
+}

lib/src/main/kotlin/at/bitfire/synctools/util/SensitiveString.kt

@@ -0,0 +1,58 @@
+/*
+ * Copyright © All Contributors. See LICENSE and AUTHORS in the root directory for details.
+ */
+
+package at.bitfire.synctools.util
+
+/**
+ * Wrapper for passwords and other sensitive strings so that they're not directly [String]s,
+ * so that they're less likely to be used in clear-text unintentionally, like being printed in logs
+ * by [Any.toString].
+ *
+ * This class does not address the issue that clear-text passwords are stored in memory. This problem
+ * could only be reduced if we would consequently store and process only encrypted passwords, except
+ * some "providePassword" method that provides the clear-text password for a lambda function as
+ * [CharArray] and wipes out the array values after usage.
+ *
+ * See also:
+ *
+ * - https://stackoverflow.com/a/8889285
+ * - https://javaee.github.io/security-api/apidocs/javax/security/enterprise/credential/Password.html and
+ *   https://javaee.github.io/security-api/apidocs/javax/security/enterprise/credential/UsernamePasswordCredential.html
+ */
+@JvmInline
+value class SensitiveString private constructor(
+    private val data: String
+) {
+
+    /**
+     * Returns the sensitive string as a [CharArray].
+     *
+     * _Be careful when using it (for instance, don't print its content unintentionally)._
+     */
+    fun asCharArray() = data.toCharArray()
+
+    /**
+     * Returns the sensitive string as an immutable [String].
+     *
+     * _Be careful when using it (for instance, don't print it unintentionally)._
+     */
+    fun asString() = data
+
+    /**
+     * Overrides [toString] so that it doesn't expose the clear-text string (password).
+     */
+    override fun toString() = "*****"
+
+
+    companion object {
+
+        fun CharArray.toSensitiveString() =
+            SensitiveString(this.concatToString())
+
+        fun CharSequence.toSensitiveString() =
+            SensitiveString(this.toString())
+
+    }
+
+}

lib/src/test/kotlin/at/bitfire/synctools/util/AndroidAccountUtilsTest.kt

@@ -0,0 +1,46 @@
+/*
+ * This file is part of bitfireAT/synctools which is released under GPLv3.
+ * Copyright © All Contributors. See the LICENSE and AUTHOR files in the root directory for details.
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+package at.bitfire.synctools.util
+
+import android.accounts.Account
+import android.accounts.AccountManager
+import android.content.Context
+import at.bitfire.synctools.util.SensitiveString.Companion.toSensitiveString
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+
+@RunWith(RobolectricTestRunner::class)
+class AndroidAccountUtilsTest {
+
+    val context: Context = RuntimeEnvironment.getApplication()
+
+    @Test
+    fun testCreateAccount() {
+        val userData = mapOf(
+            "int" to "1",
+            "string" to "abc/\"-"
+        )
+
+        val account = Account("testCreateAccount", javaClass.name)
+        val manager = AccountManager.get(context)
+        try {
+            assertTrue(AndroidAccountUtils.createAccount(context, account, userData, "secret".toSensitiveString()))
+
+            // validate user data
+            assertEquals("1", manager.getUserData(account, "int"))
+            assertEquals("abc/\"-", manager.getUserData(account, "string"))
+            assertEquals("secret", manager.getPassword(account))
+        } finally {
+            assertTrue(manager.removeAccountExplicitly(account))
+        }
+    }
+
+}

lib/src/test/kotlin/at/bitfire/synctools/util/SensitiveStringTest.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright © All Contributors. See LICENSE and AUTHORS in the root directory for details.
+ */
+
+package at.bitfire.synctools.util
+
+import at.bitfire.synctools.util.SensitiveString.Companion.toSensitiveString
+import org.junit.Assert
+import org.junit.Test
+
+class SensitiveStringTest {
+
+    private data class UsernameAndPassword(
+        val username: String,
+        val password: SensitiveString
+    )
+
+    @Test
+    fun `equals (other object)`() {
+        val password = "some-password".toSensitiveString()
+        Assert.assertFalse(password == Any())
+    }
+
+    @Test
+    fun `equals (other password)`() {
+        val password = "some-password".toSensitiveString()
+        Assert.assertFalse(password == "other-password".toSensitiveString())
+    }
+
+    @Test
+    fun `equals (same password)`() {
+        val password = "some-password".toSensitiveString()
+        Assert.assertTrue(password == "some-password".toSensitiveString())
+    }
+
+    @Test
+    fun `toString in data class`() {
+        val credentials = UsernameAndPassword(
+            "some-user",
+            "some-password".toSensitiveString()
+        )
+
+        val logMessage = "Credentials: $credentials"
+        Assert.assertEquals("Credentials: UsernameAndPassword(username=some-user, password=*****)", logMessage)
+    }
+
+}