From 83fd4cec996990fee8fa2deb2fb841a74d2a36a8 Mon Sep 17 00:00:00 2001 From: Federico Terzi Date: Wed, 15 Apr 2020 18:39:40 +0200 Subject: [PATCH] Add a security overview. Fix #182 --- SECURITY.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8e57bc6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,46 @@ +# Security + +Espanso has always been designed with a strong focus on security. +In the following section, there is an overview of the critical security +components. + +If you have any doubt, don't hesitate to contact me. + +## Architecture + +In its most basic form, a text expander is composed of two parts: + +* A **global key detector** that intercepts the keys pressed by the user, +in order to determine if a trigger was typed. + +* A **key injection mechanism** that injects the +final text into the current application, a process known as *expansion*. + +At this point, some of you may think that espanso is acting as a keylogger, +due to the *global key detector* we mentioned before. The good news is, **it's not!** + +While espanso detects key presses as a keylogger would do, +**it doesn't log anything**. Moreover, to further reduce risks, espanso only +stores in memory the last 3 chars by default (you can change this amount by +setting the `backspace_limit` parameter in the config) and this is needed +to allow the user to correct wrongly typed triggers by pressing backspace, +up to 3 characters. + +The matching part is implemented with an efficient [data structure](https://github.com/federico-terzi/espanso/blob/master/src/matcher/scrolling.rs) +that keeps track of the compatible matches in a "rolling" basis. So that in the worst case scenario, +the longest sequence of chars kept in memory would be equal to the longest trigger. + +And of course, if you don't trust me you can examine all the code! That's +the wonderful thing about open source :) + +### Implementation + +The *global key detector* is implemented on top of various OS-dependent APIs, in particular: + +* On Windows, it uses the [RawInput API](https://docs.microsoft.com/en-us/windows/win32/inputdev/raw-input). +* On macOS, it uses [addGlobalMonitorForEvents](https://developer.apple.com/documentation/appkit/nsevent/1535472-addglobalmonitorforevents). +* On Linux, it uses the [X Record Extension](https://www.x.org/releases/X11R7.6/doc/libXtst/recordlib.html). + +## Reporting Security Issues + +To report a security issue, please email me at federicoterzi96[at]gmail.com \ No newline at end of file