Add basic secure docs (qmk#17577)

nolanseaton · Jan 23, 2023 · aa4e5b4 · aa4e5b4
1 parent a0abbb9
commit aa4e5b4
Show file tree

Hide file tree

Showing 3 changed files with 67 additions and 27 deletions.
diff --git a/docs/_summary.md b/docs/_summary.md
@@ -84,7 +84,7 @@
     * [One Shot Keys](one_shot_keys.md)
     * [Pointing Device](feature_pointing_device.md)
     * [Raw HID](feature_rawhid.md)
-    * [Send String](feature_send_string.md)
+    * [Secure](feature_secure.md)
     * [Sequencer](feature_sequencer.md)
     * [Swap Hands](feature_swap_hands.md)
     * [Tap Dance](feature_tap_dance.md)

diff --git a/docs/feature_secure.md 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 |
diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md
@@ -239,38 +239,24 @@ Example:
 
 The device version is a BCD (binary coded decimal) value, in the format `MMmr`, so the below value would look like `0x0100` in the generated code. This also means the maximum valid values for each part are `99.9.9`, despite it being a hexadecimal value under the hood.
 
-### Encoders
+### Secure
 
-This section controls the basic [rotary encoder](feature_encoders.md) support.
+The following options can be configured:
 
-The following items can be set. Not every value is required.
-
-* `pin_a`
-  * __Required__. A pad definition
-* `pin_b`
-  * __Required__. B pad definition
-* `resolution`
-  * How many pulses the encoder registers between each detent
-
-Examples:
+|Key               |Description                                                                      |
+|------------------|---------------------------------------------------------------------------------|
+|`unlock_sequence` | Timeout for the user to perform the configured unlock sequence - `0` to disable |
+|`unlock_timeout`  | Timeout while unlocked before returning to locked - `0` to disable              |
+|`idle_timeout`    | Array of matrix locations describing a sequential sequence of keypresses        |
 
-```json
-{
-    "encoder": {
-        "rotary": [
-            { "pin_a": "B5", "pin_b": "A2" }
-        ]
-    }
-}
-```
+Example:
 
 ```json
 {
-    "encoder": {
-        "rotary": [
-            { "pin_a": "B5", "pin_b": "A2", "resolution": 4 }
-            { "pin_a": "B6", "pin_b": "A3", "resolution": 2 }
-        ]
+    "secure": {
+        "unlock_sequence": [ [0,0], [0,1] ],
+        "unlock_timeout": 5000,
+        "idle_timeout": 60000
     }
 }
 ```