From c551b9e0bb7e39ab3a7545fc566dae837aa30843 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Fri, 23 Jul 2021 14:06:03 +0200 Subject: [PATCH] crypto: Fill out the docs for the cross signing service --- .../crosssigning/CrossSigningService.kt | 41 ++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/crypto/crosssigning/CrossSigningService.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/crypto/crosssigning/CrossSigningService.kt index 359e33cc2c..709babc23f 100644 --- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/crypto/crosssigning/CrossSigningService.kt +++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/session/crypto/crosssigning/CrossSigningService.kt @@ -25,9 +25,13 @@ import org.matrix.android.sdk.internal.crypto.crosssigning.UserTrustResult import org.matrix.android.sdk.internal.crypto.store.PrivateKeysInfo interface CrossSigningService { - + /** + * Is our own device signed by our own cross signing identity + */ fun isCrossSigningVerified(): Boolean + // TODO this isn't used anywhere besides in tests? + // Is this the local trust concept that we have for devices? fun isUserTrusted(otherUserId: String): Boolean /** @@ -43,29 +47,55 @@ interface CrossSigningService { fun initializeCrossSigning(uiaInterceptor: UserInteractiveAuthInterceptor?, callback: MatrixCallback) + /** + * Does our own user have a valid cross signing identity uploaded. + * + * In other words has any of our devices uploaded public cross signing keys to the server. + */ fun isCrossSigningInitialized(): Boolean = getMyCrossSigningKeys() != null + /** + * Inject the private cross signing keys, likely from backup, into our store. + * + * This will check if the injected private cross signing keys match the public ones provided + * by the server and if they do so + */ fun checkTrustFromPrivateKeys(masterKeyPrivateKey: String?, uskKeyPrivateKey: String?, sskPrivateKey: String?): UserTrustResult + /** + * Get the public cross signing keys for the given user + * + * @param otherUserId The ID of the user for which we would like to fetch the cross signing keys. + */ fun getUserCrossSigningKeys(otherUserId: String): MXCrossSigningInfo? fun getLiveCrossSigningKeys(userId: String): LiveData> + /** Get our own public cross signing keys */ fun getMyCrossSigningKeys(): MXCrossSigningInfo? + /** Get our own private cross signing keys */ fun getCrossSigningPrivateKeys(): PrivateKeysInfo? fun getLiveCrossSigningPrivateKeys(): LiveData> + /** + * Can we sign our other devices or other users? + * + * Returning true means that we have the private self-signing and user-signing keys at hand. + */ fun canCrossSign(): Boolean + /** Do we have all our private cross signing keys in storage? */ fun allPrivateKeysKnown(): Boolean + /** Mark a user identity as trusted and sign and upload signatures of our user-signing key to the server */ fun trustUser(otherUserId: String, callback: MatrixCallback) + /** Mark our own master key as trusted */ fun markMyMasterKeyAsTrusted() /** @@ -74,11 +104,20 @@ interface CrossSigningService { fun trustDevice(deviceId: String, callback: MatrixCallback) + /** + * Check if a device is trusted + * + * This will check that we have a valid trust chain from our own master key to a device, either + * using the self-signing key for our own devices or using the user-signing key and the master + * key of another user. + */ fun checkDeviceTrust(otherUserId: String, otherDeviceId: String, + // TODO what is locallyTrusted used for? locallyTrusted: Boolean?): DeviceTrustResult // FIXME Those method do not have to be in the service + // TODO those three methods doesn't seem to be used anywhere? fun onSecretMSKGossip(mskPrivateKey: String) fun onSecretSSKGossip(sskPrivateKey: String) fun onSecretUSKGossip(uskPrivateKey: String)