secure.h

 1// Copyright 2022 QMK
 2// SPDX-License-Identifier: GPL-2.0-or-later
 3
 4#pragma once
 5
 6/**
 7 * \file
 8 *
 9 * \defgroup secure Secure API
10 *
11 * \brief Exposes a set of functionality to act as a virtual padlock for your device
12 * ...as long as that padlock is made of paper and it's currently raining.
13 *
14 * \{
15 */
16
17#include <stdint.h>
18#include <stdbool.h>
19
20/** \brief Available secure states
21 */
22typedef enum {
23    SECURE_LOCKED,
24    SECURE_PENDING,
25    SECURE_UNLOCKED,
26} secure_status_t;
27
28/** \brief Query current secure state
29 */
30secure_status_t secure_get_status(void);
31
32/** \brief Helper to check if unlocking is currently locked
33 */
34#define secure_is_locked() (secure_get_status() == SECURE_LOCKED)
35
36/** \brief Helper to check if unlocking is currently in progress
37 */
38#define secure_is_unlocking() (secure_get_status() == SECURE_PENDING)
39
40/** \brief Helper to check if unlocking is currently unlocked
41 */
42#define secure_is_unlocked() (secure_get_status() == SECURE_UNLOCKED)
43
44/** \brief Lock down the device
45 */
46void secure_lock(void);
47
48/** \brief Force unlock the device
49 *
50 * \warning bypasses user unlock sequence
51 */
52void secure_unlock(void);
53
54/** \brief Begin listening for an unlock sequence
55 */
56void secure_request_unlock(void);
57
58/** \brief Flag to the secure subsystem that user activity has happened
59 *
60 * Call when some user activity has happened and the device should remain unlocked
61 */
62void secure_activity_event(void);
63
64/** \brief Flag to the secure subsystem that user has triggered a keypress
65 *
66 * Call to trigger processing of the unlock sequence
67 */
68void secure_keypress_event(uint8_t row, uint8_t col);
69
70/** \brief Handle various secure subsystem background tasks
71 */
72void secure_task(void);
73
74/** \brief quantum hook called when changing secure status device
75 */
76void secure_hook_quantum(secure_status_t secure_status);
77
78/** \brief user hook called when changing secure status device
79 */
80bool secure_hook_user(secure_status_t secure_status);
81
82/** \brief keyboard hook called when changing secure status device
83 */
84bool secure_hook_kb(secure_status_t secure_status);
85
86/** \} */