Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add basic secure docs #17577

Merged
merged 4 commits into from
Jul 12, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/_summary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
54 changes: 54 additions & 0 deletions docs/feature_secure.md
Original file line number Diff line number Diff line change
@@ -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 changes: 22 additions & 0 deletions docs/reference_info_json.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}
```