ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add basic secure docs (#17577)

Browse source
This commit is contained in:
Joel Challis 2022-07-13 00:06:19 +01:00 • committed by GitHub
parent 2714c70bd7
commit 2a3dd95229
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 77 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/_summary.md
View file

@ -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)

54
docs/feature_secure.md Normal file
View file

@ -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 |

22
docs/reference_info_json.md
View file

@ -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
}
}
```