Package org.signal.libsignal.net

Class KeyTransparencyClient

  • All Implemented Interfaces:
    
public class KeyTransparencyClient

    Typed API to access the key transparency subsystem using an existing unauthenticated chat connection.

    Unlike ChatConnection, key transparency client does not export "raw" send/receive APIs, and instead uses them internally to implement high-level operations.

    Note: Store APIs may be invoked concurrently. Here are possible strategies to make sure there are no thread safety violations:

    • Types implementing Store can be made thread safe
    • KeyTransparencyClient operations-completed asynchronous calls-can be serialized.

    Example usage: 

    var net = new Network(Network.Environment.STAGING, "key-transparency-example");
var chat = net.connectUnauthChat(new Listener()).get();
chat.start();

KeyTransparencyClient client = chat.keyTransparencyClient();

client.search(aci, identityKey, null, null, null, KT_DATA_STORE).get();

    • Constructor Detail

    • Method Detail

      • search

         CompletableFuture<Void> search(ServiceId.Aci aci, IdentityKey aciIdentityKey, String e164, Array<byte> unidentifiedAccessKey, Array<byte> usernameHash, Store store)

        Search for account information in the key transparency tree.

        Only ACI and ACI identity key are required to identify the account.

        If the latest distinguished tree head is not present in the store, it will be requested from the server prior to performing the search via updateDistinguished.

        This is an asynchronous operation; all the exceptions occurring during communication with the server will be wrapped in java.util.concurrent.ExecutionException.

        Possible exceptions include:

        Parameters:
        aci - the ACI of the account to be searched for.
        aciIdentityKey - IdentityKey associated with the ACI.
        e164 - string representation of an E.164 number associated with the account.
        unidentifiedAccessKey - unidentified access key for the account.
        usernameHash - hash of the username associated with the account.
        store - local persistent storage for key transparency-related data, such as the latest tree heads and account monitoring data.
        Returns:

        an instance of CompletableFuture successful completion of which will indicate that the search request has succeeded and store has been updated with the latest account data.

      • updateDistinguished

         CompletableFuture<Void> updateDistinguished(Store store)

        Request the latest distinguished tree head from the server and update it in the local store.

        This is an asynchronous operation; all the exceptions occurring during communication with the server will be wrapped in java.util.concurrent.ExecutionException.

        Possible exceptions include:

        Parameters:
        store - local persistent storage for key transparency related data, such as the latest tree heads and account monitoring data.
        Returns:

        An instance of CompletableFuture representing the asynchronous operation, which does not produce any value. Successful completion of the operation results in an updated state of the store.

      • monitor

         CompletableFuture<Void> monitor(KeyTransparency.MonitorMode mode, ServiceId.Aci aci, IdentityKey aciIdentityKey, String e164, Array<byte> unidentifiedAccessKey, Array<byte> usernameHash, Store store)

        Issue a monitor request to the key transparency service.

        Store must contain data associated with the account being requested prior to making this call. Another way of putting this is: monitor cannot be called before search.

        If any of the monitored fields in the server response contain a version that is higher than the one currently in the store, the behavior depends on the mode parameter value.

        • MonitorMode.SELF - An exception will be thrown, no search request will be issued.
        • MonitorMode.OTHER - A search request will be performed automatically and, if it succeeds, the updated account data will be stored.

        If the latest distinguished tree head is not present in the store, it will be requested from the server prior to performing the search via updateDistinguished.

        This is an asynchronous operation; all the exceptions occurring during communication with the server will be wrapped in java.util.concurrent.ExecutionException.

        Possible exceptions include:

        Parameters:
        mode - Mode of the monitor operation.
        aci - the ACI of the account to be searched for.
        aciIdentityKey - IdentityKey associated with the ACI.
        e164 - string representation of an E.164 number associated with the account.
        unidentifiedAccessKey - unidentified access key for the account.
        usernameHash - hash of the username associated with the account.
        store - local persistent storage for key transparency-related data, such as the latest tree heads and account monitoring data.
        Returns:

        an instance of CompletableFuture successful completion of which will indicate that the monitor request has succeeded and store has been updated with the latest account data.