summaryrefslogtreecommitdiff
path: root/docs/feature_secure.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/feature_secure.md')
-rw-r--r--docs/feature_secure.md54
1 files changed, 54 insertions, 0 deletions
diff --git a/docs/feature_secure.md b/docs/feature_secure.md
new file mode 100644
index 0000000000..ee774b05a8
--- /dev/null
+++ b/docs/feature_secure.md
@@ -0,0 +1,54 @@
+# Secure
+
+The secure feature aims to prevent unwanted interaction without user intervention.
+
+?> Secure does **not** currently implement encryption/decryption/etc and should not be a replacement where a strong hardware/software based solution is required.
+
+### Unlock sequence
+
+To unlock, the user must perform a set of actions. This can optionally be configured to be multiple keys.
+
+* While unlocking all keyboard input is ignored
+* Incorrect attempts will revert back to the previously locked state
+
+### Automatic Locking
+
+Once unlocked, the keyboard will revert back to a locked state after the configured timeout.
+The timeout can be refreshed by using the `secure_activity_event` function, for example from one of the various [hooks](custom_quantum_functions.md).
+
+## Usage
+
+Add the following to your `rules.mk`:
+
+```make
+SECURE_ENABLE = yes
+```
+
+## Keycodes
+
+| Key | Description |
+|------------------|--------------------------------------------------------------------------------|
+| `SECURE_LOCK` | Revert back to a locked state |
+| `SECURE_UNLOCK` | Forces unlock without performing a unlock sequence |
+| `SECURE_TOGGLE` | Toggle directly between locked and unlock without performing a unlock sequence |
+| `SECURE_REQUEST` | Request that user perform the unlock sequence |
+
+## Configuration
+
+| Define | Default | Description |
+|-------------------------|----------------|---------------------------------------------------------------------------------|
+|`SECURE_UNLOCK_TIMEOUT` | `5000` | Timeout for the user to perform the configured unlock sequence - `0` to disable |
+|`SECURE_IDLE_TIMEOUT` | `60000` | Timeout while unlocked before returning to locked - `0` to disable |
+|`SECURE_UNLOCK_SEQUENCE` | `{ { 0, 0 } }` | Array of matrix locations describing a sequential sequence of keypresses |
+
+## Functions
+
+| Function | Description |
+|---------------------------|----------------------------------------------------------------------------|
+| `secure_is_locked()` | Check if the device is currently locked |
+| `secure_is_unlocking()` | Check if an unlock sequence is currently in progress |
+| `secure_is_unlocked()` | Check if the device is currently unlocked |
+| `secure_lock()` | Lock down the device |
+| `secure_unlock()` | Force unlock the device - bypasses user unlock sequence |
+| `secure_request_unlock()` | Begin listening for an unlock sequence |
+| `secure_activity_event()` | Flag that user activity has happened and the device should remain unlocked |