First Commit

libraries/cryptography/api/build.gradle.kts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.libraries.cryptography.api"
+}

libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/AESEncryptionSpecs.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.api
+
+import android.security.keystore.KeyProperties
+
+object AESEncryptionSpecs {
+    const val BLOCK_MODE = KeyProperties.BLOCK_MODE_GCM
+    const val PADDINGS = KeyProperties.ENCRYPTION_PADDING_NONE
+    const val ALGORITHM = KeyProperties.KEY_ALGORITHM_AES
+    const val KEY_SIZE = 128
+    const val CIPHER_TRANSFORMATION = "$ALGORITHM/$BLOCK_MODE/$PADDINGS"
+}

libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionDecryptionService.kt

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.api
+
+import javax.crypto.Cipher
+import javax.crypto.SecretKey
+
+/**
+ * Simple service to provide encryption and decryption operations.
+ */
+interface EncryptionDecryptionService {
+    fun createEncryptionCipher(key: SecretKey): Cipher
+    fun createDecryptionCipher(key: SecretKey, initializationVector: ByteArray): Cipher
+    fun encrypt(key: SecretKey, input: ByteArray): EncryptionResult
+    fun decrypt(key: SecretKey, encryptionResult: EncryptionResult): ByteArray
+}

libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionResult.kt

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+@file:OptIn(ExperimentalEncodingApi::class)
+
+package io.element.android.libraries.cryptography.api
+
+import java.nio.ByteBuffer
+import kotlin.io.encoding.Base64
+import kotlin.io.encoding.ExperimentalEncodingApi
+
+/**
+ * Holds the result of an encryption operation.
+ */
+class EncryptionResult(
+    val encryptedByteArray: ByteArray,
+    val initializationVector: ByteArray
+) {
+    fun toBase64(): String {
+        val initializationVectorSize = ByteBuffer.allocate(Int.SIZE_BYTES).putInt(initializationVector.size).array()
+        val cipherTextWithIv: ByteArray =
+            ByteBuffer.allocate(Int.SIZE_BYTES + initializationVector.size + encryptedByteArray.size)
+                .put(initializationVectorSize)
+                .put(initializationVector)
+                .put(encryptedByteArray)
+                .array()
+        return Base64.encode(cipherTextWithIv)
+    }
+
+    companion object {
+        /**
+         * @param base64 the base64 representation of the encrypted data.
+         * @return the [EncryptionResult] from the base64 representation.
+         */
+        fun fromBase64(base64: String): EncryptionResult {
+            val cipherTextWithIv = Base64.decode(base64)
+            val buffer = ByteBuffer.wrap(cipherTextWithIv)
+            val initializationVectorSize = buffer.int
+            val initializationVector = ByteArray(initializationVectorSize)
+            buffer.get(initializationVector)
+            val encryptedByteArray = ByteArray(buffer.remaining())
+            buffer.get(encryptedByteArray)
+            return EncryptionResult(encryptedByteArray, initializationVector)
+        }
+    }
+}

libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/SecretKeyRepository.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.api
+
+import javax.crypto.SecretKey
+
+/**
+ * Simple interface to get, create and delete a secret key for a given alias.
+ * Implementation should be able to store the generated key securely.
+ */
+interface SecretKeyRepository {
+    /**
+     * Get or create a secret key for a given alias.
+     * @param alias the alias to use
+     * @param requiresUserAuthentication true if the key should be protected by user authentication
+     */
+    fun getOrCreateKey(alias: String, requiresUserAuthentication: Boolean): SecretKey
+
+    /**
+     * Delete the secret key for a given alias.
+     * @param alias the alias to use
+     */
+    fun deleteKey(alias: String)
+}

libraries/cryptography/impl/build.gradle.kts

@@ -0,0 +1,27 @@
+import extension.setupDependencyInjection
+import extension.testCommonDependencies
+
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023, 2024 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.libraries.cryptography.impl"
+}
+
+setupDependencyInjection()
+
+dependencies {
+    implementation(projects.libraries.di)
+    api(projects.libraries.cryptography.api)
+
+    testCommonDependencies(libs)
+}

libraries/cryptography/impl/src/main/kotlin/io/element/android/libraries/cryptography/impl/AESEncryptionDecryptionService.kt

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.impl
+
+import dev.zacsweers.metro.AppScope
+import dev.zacsweers.metro.ContributesBinding
+import io.element.android.libraries.cryptography.api.AESEncryptionSpecs
+import io.element.android.libraries.cryptography.api.EncryptionDecryptionService
+import io.element.android.libraries.cryptography.api.EncryptionResult
+import javax.crypto.Cipher
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * Default implementation of [EncryptionDecryptionService] using AES encryption.
+ */
+@ContributesBinding(AppScope::class)
+class AESEncryptionDecryptionService : EncryptionDecryptionService {
+    override fun createEncryptionCipher(key: SecretKey): Cipher {
+        return Cipher.getInstance(AESEncryptionSpecs.CIPHER_TRANSFORMATION).apply {
+            init(Cipher.ENCRYPT_MODE, key)
+        }
+    }
+
+    override fun createDecryptionCipher(key: SecretKey, initializationVector: ByteArray): Cipher {
+        val spec = GCMParameterSpec(128, initializationVector)
+        return Cipher.getInstance(AESEncryptionSpecs.CIPHER_TRANSFORMATION).apply {
+            init(Cipher.DECRYPT_MODE, key, spec)
+        }
+    }
+
+    override fun encrypt(key: SecretKey, input: ByteArray): EncryptionResult {
+        val cipher = createEncryptionCipher(key)
+        val encryptedData = cipher.doFinal(input)
+        return EncryptionResult(encryptedData, cipher.iv)
+    }
+
+    override fun decrypt(key: SecretKey, encryptionResult: EncryptionResult): ByteArray {
+        val cipher = createDecryptionCipher(key, encryptionResult.initializationVector)
+        return cipher.doFinal(encryptionResult.encryptedByteArray)
+    }
+}

libraries/cryptography/impl/src/main/kotlin/io/element/android/libraries/cryptography/impl/CryptographyModule.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.impl
+
+import dev.zacsweers.metro.AppScope
+import dev.zacsweers.metro.BindingContainer
+import dev.zacsweers.metro.ContributesTo
+import dev.zacsweers.metro.Provides
+import java.security.KeyStore
+
+internal const val ANDROID_KEYSTORE = "AndroidKeyStore"
+
+@ContributesTo(AppScope::class)
+@BindingContainer
+object CryptographyModule {
+    @Provides
+    fun providesAndroidKeyStore(): KeyStore {
+        return KeyStore.getInstance(ANDROID_KEYSTORE).apply {
+            load(null)
+        }
+    }
+}

libraries/cryptography/impl/src/main/kotlin/io/element/android/libraries/cryptography/impl/KeyStoreSecretKeyRepository.kt

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.impl
+
+import android.annotation.SuppressLint
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import dev.zacsweers.metro.AppScope
+import dev.zacsweers.metro.ContributesBinding
+import io.element.android.libraries.cryptography.api.AESEncryptionSpecs
+import io.element.android.libraries.cryptography.api.SecretKeyRepository
+import timber.log.Timber
+import java.security.KeyStore
+import java.security.KeyStoreException
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+
+/**
+ * Default implementation of [SecretKeyRepository] that uses the Android Keystore to store the keys.
+ * The generated key uses AES algorithm, with a key size of 128 bits, and the GCM block mode.
+ */
+@ContributesBinding(AppScope::class)
+class KeyStoreSecretKeyRepository(
+    private val keyStore: KeyStore,
+) : SecretKeyRepository {
+    // False positive lint issue
+    @SuppressLint("WrongConstant")
+    override fun getOrCreateKey(alias: String, requiresUserAuthentication: Boolean): SecretKey {
+        val secretKeyEntry = (keyStore.getEntry(alias, null) as? KeyStore.SecretKeyEntry)
+            ?.secretKey
+        return if (secretKeyEntry == null) {
+            val generator = KeyGenerator.getInstance(AESEncryptionSpecs.ALGORITHM, ANDROID_KEYSTORE)
+            val keyGenSpec = KeyGenParameterSpec.Builder(
+                alias,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+            )
+                .setBlockModes(AESEncryptionSpecs.BLOCK_MODE)
+                .setEncryptionPaddings(AESEncryptionSpecs.PADDINGS)
+                .setKeySize(AESEncryptionSpecs.KEY_SIZE)
+                .setUserAuthenticationRequired(requiresUserAuthentication)
+                .build()
+            generator.init(keyGenSpec)
+            generator.generateKey()
+        } else {
+            secretKeyEntry
+        }
+    }
+
+    override fun deleteKey(alias: String) {
+        try {
+            keyStore.deleteEntry(alias)
+        } catch (e: KeyStoreException) {
+            Timber.e(e)
+        }
+    }
+}

libraries/cryptography/impl/src/test/kotlin/io/element/android/libraries/cryptography/impl/AESEncryptionDecryptionServiceTest.kt

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.impl
+
+import android.security.keystore.KeyProperties
+import com.google.common.truth.Truth.assertThat
+import org.junit.Assert.assertThrows
+import org.junit.Test
+import java.security.GeneralSecurityException
+import javax.crypto.KeyGenerator
+
+class AESEncryptionDecryptionServiceTest {
+    private val encryptionDecryptionService = AESEncryptionDecryptionService()
+
+    @Test
+    fun `given a valid key then encrypt decrypt work`() {
+        val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES)
+        keyGenerator.init(128)
+        val key = keyGenerator.generateKey()
+        val input = "Hello World".toByteArray()
+        val encryptionResult = encryptionDecryptionService.encrypt(key, input)
+        val decrypted = encryptionDecryptionService.decrypt(key, encryptionResult)
+        assertThat(decrypted).isEqualTo(input)
+    }
+
+    @Test
+    fun `given a wrong key then decrypt fail`() {
+        val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES)
+        keyGenerator.init(128)
+        val encryptionKey = keyGenerator.generateKey()
+        val input = "Hello World".toByteArray()
+        val encryptionResult = encryptionDecryptionService.encrypt(encryptionKey, input)
+        val decryptionKey = keyGenerator.generateKey()
+        assertThrows(GeneralSecurityException::class.java) {
+            encryptionDecryptionService.decrypt(decryptionKey, encryptionResult)
+        }
+    }
+}

libraries/cryptography/test/build.gradle.kts

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+plugins {
+    id("io.element.android-library")
+}
+
+android {
+    namespace = "io.element.android.libraries.cryptography.test"
+}
+
+dependencies {
+    api(projects.libraries.cryptography.api)
+}

libraries/cryptography/test/src/main/kotlin/io/element/android/libraries/cryptography/test/SimpleSecretKeyRepository.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Element Creations Ltd.
+ * Copyright 2023-2025 New Vector Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial.
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+package io.element.android.libraries.cryptography.test
+
+import io.element.android.libraries.cryptography.api.AESEncryptionSpecs
+import io.element.android.libraries.cryptography.api.SecretKeyRepository
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+
+class SimpleSecretKeyRepository : SecretKeyRepository {
+    private var secretKeyForAlias = HashMap<String, SecretKey>()
+
+    override fun getOrCreateKey(alias: String, requiresUserAuthentication: Boolean): SecretKey {
+        return secretKeyForAlias.getOrPut(alias) {
+            generateKey()
+        }
+    }
+
+    override fun deleteKey(alias: String) {
+        secretKeyForAlias.remove(alias)
+    }
+
+    private fun generateKey(): SecretKey {
+        val keyGenerator = KeyGenerator.getInstance(AESEncryptionSpecs.ALGORITHM)
+        keyGenerator.init(AESEncryptionSpecs.KEY_SIZE)
+        return keyGenerator.generateKey()
+    }
+}