diff --git a/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionDecryptionService.kt b/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionDecryptionService.kt
index fc882bc54b..1e2866a20f 100644
--- a/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionDecryptionService.kt
+++ b/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/EncryptionDecryptionService.kt
@@ -15,8 +15,35 @@ import javax.crypto.SecretKey
  * Simple service to provide encryption and decryption operations.
  */
 interface EncryptionDecryptionService {
+    /**
+     * Creates a cipher ready to encrypt, for the callers that need the cipher itself, such as to bind it to a biometric prompt.
+     *
+     * @param key the key to encrypt with.
+     */
     fun createEncryptionCipher(key: SecretKey): Cipher
+
+    /**
+     * Creates a cipher ready to decrypt, for the callers that need the cipher itself.
+     *
+     * @param key the key to decrypt with.
+     * @param initializationVector the vector produced when the data was encrypted.
+     */
     fun createDecryptionCipher(key: SecretKey, initializationVector: ByteArray): Cipher
+
+    /**
+     * Encrypts data in one call.
+     *
+     * @param key the key to encrypt with.
+     * @param input the plaintext bytes.
+     * @return the ciphertext along with the initialization vector needed to decrypt it.
+     */
     fun encrypt(key: SecretKey, input: ByteArray): EncryptionResult
+
+    /**
+     * Decrypts data in one call.
+     *
+     * @param key the key the data was encrypted with.
+     * @param encryptionResult the ciphertext and its initialization vector, as returned by [encrypt].
+     */
     fun decrypt(key: SecretKey, encryptionResult: EncryptionResult): ByteArray
 }
diff --git a/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/SecretKeyRepository.kt b/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/SecretKeyRepository.kt
index b210664d9f..c68f3170b9 100644
--- a/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/SecretKeyRepository.kt
+++ b/libraries/cryptography/api/src/main/kotlin/io/element/android/libraries/cryptography/api/SecretKeyRepository.kt
@@ -16,10 +16,17 @@ import javax.crypto.SecretKey
  * Implementation should be able to store the generated key securely.
  */
 interface SecretKeyRepository {
+    /**
+     * Whether a key exists for the given alias, re-emitted when it is created or deleted.
+     *
+     * @param alias the alias to watch.
+     */
     fun hasKey(alias: String): Flow<Boolean>
 
     /**
      * Get or create a secret key for a given alias.
+     * Note that [requiresUserAuthentication] only applies when the key is created: an existing key keeps the protection it was created with.
+     *
      * @param alias the alias to use
      * @param requiresUserAuthentication true if the key should be protected by user authentication
      */