@sudoplatform/sudo-secure-communications
    Preparing search index...

    Interface SecurityModule

    Key backup, restore and interactive device verification services.

    In the secure communications offering, each device stores their own keys. To seamlessly continue conversations across multiple devices, the keys must be replicated across those devices. Verified devices automatically remain in sync with each others keys, so it's important to design apps that encourage users to keep their devices verified.

    Client can verify devices with two mechanisms:

    1. Key backup and restore. In this method, client keys are encrypted with a "backup key" and uploaded to the server. The keys can later be "recovered" on other devices using the same backup key. This backup gives the device access to other previous session keys.

    2. Interactive verification. In this method, two devices can verify their keys out of band using emoji matching. In the case tha verification is happening between the same handle of two different devices, the unverified device becomes verified and will then gain access to session keys from their other devices.

    interface SecurityModule {
        acceptVerificationRequest(
            input: AcceptVerificationRequestInput,
        ): Promise<void>;
        approveVerification(input: ApproveVerificationInput): Promise<void>;
        cancelVerification(input: CancelVerificationInput): Promise<void>;
        createBackup(input: CreateBackupInput): Promise<string>;
        declineVerification(input: DeclineVerificationInput): Promise<void>;
        getBackupState(input: GetBackupStateInput): Promise<BackupState>;
        isVerified(input: IsVerifiedInput): Promise<boolean>;
        onSessionVerificationChanged(
            input: OnSessionVerificationChangedInput,
        ): void;
        onVerificationRequestReceived(
            input: OnVerificationRequestReceivedInput,
        ): void;
        recover(input: RecoverInput): Promise<void>;
        requestVerification(input: RequestVerificationInput): Promise<void>;
        resetBackupKey(input: ResetBackupKeyInput): Promise<string>;
        rotateBackupKey(input: RotateBackupKeyInput): Promise<string>;
        startVerification(input: StartVerificationInput): Promise<void>;
    }

    Implemented by

    Index

    Methods

    acceptVerificationRequest approveVerification cancelVerification createBackup declineVerification getBackupState isVerified onSessionVerificationChanged onVerificationRequestReceived recover requestVerification resetBackupKey rotateBackupKey startVerification

    Methods

    • Accept a verification request from another device.

      Parameters

      Returns Promise<void>

    • Approve a verification request. Users must check the contents of the [InteractiveVerificationState.ReceivedVerificationData] to ensure the emojis match before approving.

      Parameters

      Returns Promise<void>

    • Cancel the current verification at any time.

      Parameters

      Returns Promise<void>

    • Create a server-side, encrypted backup of client keys for the user. After creation, keys are automatically uploaded to the backup so this only has to be called once.

      Parameters

      Returns Promise<string>

      a backup key, to be used with the [recover] method to recover keys from the server backup.

    • Decline a verification request.

      Parameters

      Returns Promise<void>

    • Get the current state of the encrypted server backup.

      Parameters

      Returns Promise<BackupState>

      the current backup state

    • Convenience method to check if the current session is verified.

      Parameters

      Returns Promise<boolean>

      true if the current session is verified, false otherwise

    • Recover client keys from a server-side backup.

      Parameters

      Returns Promise<void>

    • Begin an interactive verification flow by requesting verification to another verified, online device.

      Parameters

      Returns Promise<void>

    • Resets the backup. This replaces the server side backup with current keys known to this device. This will result in data loss of previous messages encrypted with keys from the previous backup not known to this device. All other devices associated with this user will become unverified.

      Parameters

      Returns Promise<string>

      a new backup key, to be used with the [recover] method to recover keys from the server backup.

    • Rotate backup keys. The previous backup key is invalidated and replaced with a new one. Only verified sessions can execute this command.

      Parameters

      Returns Promise<string>

      a new backup key, to be used with the [recover] method to recover keys from the server backup.

    • Start interactive verification. This can only occur after the other device has accepted the verification request. Either device can start the verification.

      Parameters

      Returns Promise<void>

    Settings

    Member Visibility

    On This Page

    Methods