Threema-Android-mirror/domain/libthreema/threema-protocols/src/remote-secret.md

Remote Secret Subprotocol

This protocol provides an optional protection layer for customers using Threema Work, cryptographically guarding access to application storage with the help of a Remote Secret stored on the Work server.

With this mechanism it is possible to remotely block access to the application storage, temporarily or permanently. Given a timely response, it allows to prevent data theft, e.g. when a device has been stolen.

Terminology

• RS: Remote Secret (Key)
• RSH: Remote Secret Hash
• RSHID: Remote Secret Hash tied to an Identity
• RSAT: Remote Secret Authentication Token

Storage Protection

Generally, all stored data that can be protected by the Remote Secret feature should be protected by it. With the following exceptions:

• RSAT
• RSH/RSHID
• Identity/Safe/Data backups¹
• When using RSHID: The user's Threema ID
• For OnPrem: Cached OPPF file²

Due to significant platform differences, the concrete implementation depends on the respective platform.

¹: Customers that want to prevent access to backups without RS are advised to disable backups via MDM.

²: The domain rules and Work server URL from the OPPF file are required to access the Remote Secret endpoint securely.

Activation

The following steps are defined as the Remote Secret Activate Steps:

1. If storage is already protected by the Remote Secret feature, abort these steps.
2. Let RS be a random key.
3. In a loop:
   1. Call the Remote Secret Create endpoint with RS.
   2. If the received status code is 401 and indicates invalid credentials, prompt the user to enter their Work credentials and continue with the next loop iteration.
   3. If the received status code is not 200 or could not be decoded, exceptionally abort these steps.
   4. Extract RSAT and RSH/RSHID from the response.
4. Apply RS to protect inner application storage and store RSAT and RSH/RSHID.

Deactivation

The following steps are defined as the Remote Secret Deactivate Steps:

1. If storage is not protected by the Remote Secret feature, abort these steps.
2. Stop the task that is continuously running the Remote Secret Monitor Steps.
3. Run the Remote Secret Monitor Steps until it yields RS.
4. Remove the protection of inner storage by RS and purge RSAT and RSH/RSHID from storage.
5. Schedule a persistent task bound to the application to run the Remote Secret Delete Steps with RSAT.

The following steps are defined as the Remote Secret Delete Steps:

1. Let RSAT be the RSAT associated to RS the storage was previously protected with.
2. Call the Remote Secret Delete endpoint with RSAT.
3. In a loop:
   1. If the received status code is 401 and indicates invalid credentials, prompt the user to enter their Work credentials and continue with the next loop iteration.
   2. If the received status code is not 200 or 204, log an error and abort these steps.

Monitoring

The following steps are defined as the Remote Secret Monitor Steps:

1. Let interval be 10s, max-failed-attempts be 5 and failed-attempts be 0.
2. In a loop:
   1. Call the Remote Secret Monitor endpoint with RSAT.
   2. If the received status code is 403, run the Remote Secret Lock Steps with reason locked and abort these steps.
   3. If the received status code is 404, run the Remote Secret Lock Steps with reason not found and abort these steps.
   4. If the received status code is not 200 or the response could not be decoded:
      1. If failed-attempts is greater than or equal to max-failed-attempts, run the Remote Secret Lock Steps with reason server error and abort these steps.
      2. Increase failed-attempts by 1.
   5. If the status code is 200 and the response could be decoded:
      1. If the derived RSH/RSHID from RS of the response does not match the stored RSH/RSHID, run the Remote Secret Lock Steps with reason mismatch and abort these steps.
      2. Reset failed-attempts to 0.
      3. Update interval and max-failed-attempts from the response.
      4. If the RS was not yielded before, yield the retrieved RS.
   6. Wait for interval before continuing in the next iteration.

The following steps are defined as the Remote Secret Lock Steps:

1. Let reason be any of the following lock reasons: locked, not found, server error, mismatch.
2. Immediately lock access to the storage and purge any keys from memory.
3. Notify the user according to reason with the option to manually retry.