diff options
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/feature_secure.md | 54 | ||||
| -rw-r--r-- | docs/reference_info_json.md | 22 |
3 files changed, 77 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 11f5e1dd51..b7fcddc237 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -84,6 +84,7 @@ * [One Shot Keys](one_shot_keys.md) * [Pointing Device](feature_pointing_device.md) * [Raw HID](feature_rawhid.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 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 | diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 97817164dd..aa59711592 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -238,3 +238,25 @@ 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. + +### Secure + +The following options can be configured: + +|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 | + +Example: + +```json +{ + "secure": { + "unlock_sequence": [ [0,0], [0,1] ], + "unlock_timeout": 5000, + "idle_timeout": 60000 + } +} +``` |