XSecureLock - X11 screen lock utility
[options] xsecurelock [–
command-to-run-when-locked]
XSecureLock is an X11 screen lock utility designed with the
primary goal of security.
It locks the current X11 session, and only allows unlocking if the
user authenticates to it (typically with the login password).
While locked, it can launch a screen saver process and then waits
for input events. Upon an input event, it displays a login dialog to allow
for unlocking.
Options are set as environment variables prior to invoking
XSecureLock; the following variables are available:
- •
- XSECURELOCK_AUTH: specifies the desired authentication module (the part
that displays the authentication prompt).
- •
- XSECURELOCK_AUTHPROTO: specifies the desired authentication protocol
module (the part that talks to the system).
- •
- XSECURELOCK_AUTH_BACKGROUND_COLOR: specifies the X11 color (see manpage of
XParseColor) for the background of the auth dialog.
- •
- XSECURELOCK_AUTH_SOUNDS: specifies whether to play sounds during
authentication to indicate status. Sounds are defined as follows:
- •
- High-pitch ascending: prompt for user input.
- •
- High-pitch constant: an info message was displayed.
- •
- Low-pitch descending: an error message was displayed.
- •
- Medium-pitch ascending: authentication successful.
- •
- XSECURELOCK_AUTH_FOREGROUND_COLOR: specifies the X11 color (see manpage of
XParseColor) for the foreground text of the auth dialog.
- •
- XSECURELOCK_AUTH_TIMEOUT: specifies the time (in seconds) to wait for
response to a prompt by auth_x11 before giving up and reverting to the
screen saver.
- •
- XSECURELOCK_AUTH_WARNING_COLOR: specifies the X11 color (see manpage of
XParseColor) for the warning text of the auth dialog.
- •
- XSECURELOCK_BLANK_TIMEOUT: specifies the time (in seconds) before telling
X11 to fully blank the screen; a negative value disables X11 blanking. The
time is measured since the closing of the auth window or xsecurelock
startup. Setting this to 0 is rather nonsensical, as key-release events
(e.g. from the keystroke to launch xsecurelock or from pressing
escape to close the auth dialog) always wake up the screen.
- •
- XSECURELOCK_BLANK_DPMS_STATE: specifies which DPMS state to put the screen
in when blanking (one of standby, suspend, off and on, where
“on” means to not invoke DPMS at all).
- •
- XSECURELOCK_BURNIN_MITIGATION: specifies the number of pixels the prompt
of auth_x11 may be moved at startup to mitigate possible burn-in effects
due to the auth dialog being displayed all the time (e.g. when
spurious mouse events wake up the screen all the time).
- •
- XSECURELOCK_BURNIN_MITIGATION_DYNAMIC: if set to a non-zero value,
auth_x11 will move the prompt while it is being displayed, but stay within
the bounds of XSECURELOCK_BURNIN_MITIGATION. The value of this variable is
the maximum allowed shift per screen refresh. This mitigates short-term
burn-in effects but is probably annoying to most users, and thus disabled
by default.
- •
- XSECURELOCK_COMPOSITE_OBSCURER: create a second full-screen window to
obscure window content in case a running compositor unmaps its own window.
Helps with some instances of bad compositor behavior (such as compositor
crashes/restarts, but also compton has been caught at drawing notification
icons above the screen locker when not using the GLX backend), should
prevent compositors from unredirecting as it’s 1 pixel smaller than
the screen from every side, and should otherwise be harmless, so
it’s enabled by default.
- •
- XSECURELOCK_DATETIME_FORMAT: the date format to show. Defaults to the
locale settings.
- •
- XSECURELOCK_DEBUG_ALLOW_LOCKING_IF_INEFFECTIVE: Normally we don’t
allow locking sessions that are likely not any useful to lock, such as the
X11 part of a Wayland session (one could still use Wayland applicatione
when locked) or VNC sessions (as it’d only lock the server side
session while users will likely think they locked the client, allowing for
an easy escape). These checks can be bypassed by setting this variable to
1. Not recommended other than for debugging XSecureLock itself via such
connections.
- •
- XSECURELOCK_DEBUG_WINDOW_INFO: When complaining about another window
misbehaving, print not just the window ID but also some info about it.
Uses the xwininfo and xprop tools.
- •
- XSECURELOCK_DIM_ALPHA: Linear-space opacity to fade the screen to.
- •
- XSECURELOCK_DIM_COLOR: X11 color to fade the screen to.
- •
- XSECURELOCK_DIM_FPS: Target framerate to attain during the dimming effect
of dimmer. Ideally matches the display refresh rate.
- •
- XSECURELOCK_DIM_OVERRIDE_COMPOSITOR_DETECTION: When set to 1, always try
to use transparency for dimming; when set to 0, always use a dither
pattern. Default is to autodetect whether transparency will likely
work.
- •
- XSECURELOCK_DIM_TIME_MS: Milliseconds to dim for when above xss-lock
command line with dimmer is used; also used by wait_nonidle to know when
to assume dimming and waiting has finished and exit.
- •
- XSECURELOCK_DISCARD_FIRST_KEYPRESS: If set to 0, the key pressed to stop
the screen saver and spawn the auth child is sent to the auth child (and
thus becomes part of the password entry). By default we always discard the
key press that started the authentication flow, to prevent users from
getting used to type their password on a blank screen (which could be just
powered off and have a chat client behind or similar).
- •
- XSECURELOCK_FONT: X11 or FontConfig font name to use for auth_x11. You can
get a list of supported font names by running xlsfonts and fc-list.
- •
- XSECURELOCK_FORCE_GRAB: When grabbing fails, try stealing the grab from
other windows (a value of 2 steals from all descendants of the root
window, while a value of 1 only steals from client windows). This works
only sometimes and is incompatible with many window managers, so use with
care. See the “Forcing Grabs” section below for
details.
- •
- XSECURELOCK_GLOBAL_SAVER: specifies the desired global screen saver module
(by default this is a multiplexer that runs XSECURELOCK_SAVER on each
screen).
- •
- XSECURELOCK_IDLE_TIMERS: comma-separated list of idle time counters used
by until_nonidle. Typical values are either empty (relies on the X Screen
Saver extension instead), “IDLETIME” and
“DEVICEIDLETIME ” where n is an XInput device index (run
xinput to see them). If multiple time counters are specified, the idle
time is the minimum of them all. All listed timers must have the same
unit.
- •
- XSECURELOCK_IMAGE_DURATION_SECONDS: how long to show each still image
played by saver_mpv. Defaults to 1.
- •
- XSECURELOCK_KEY_%s_COMMAND where %s is the name of an X11 keysym (find
using xev): a shell command to execute when the specified key is pressed.
Useful e.g. for media player control. Beware: be cautiuous about
what you run with this, as it may yield attackers control over your
computer.
- •
- XSECURELOCK_LIST_VIDEOS_COMMAND: shell command to list all video files to
potentially play by saver_mpv or saver_mplayer. Defaults to find ~/Videos
-type f.
- •
- XSECURELOCK_NO_COMPOSITE: disables covering the composite overlay window.
This switches to a more traditional way of locking, but may allow desktop
notifications to be visible on top of the screen lock. Not
recommended.
- •
- XSECURELOCK_NO_PAM_RHOST: do not set PAM_RHOST to localhost, despite
recommendation
(http://www.linux-pam.org/Linux-PAM-html/adg-security-user-identity.html)
to do so by the Linux-PAM Application Developers’ Guide. This may
work around bugs in third-party PAM authentication modules. If this solves
a problem for you, please report a bug against said PAM module.
- •
- XSECURELOCK_NO_XRANDR: disables multi monitor support using XRandR.
- •
- XSECURELOCK_NO_XRANDR15: disables multi monitor support using XRandR 1.5
and fall back to XRandR 1.2. Not recommended.
- •
- XSECURELOCK_PAM_SERVICE: pam service name. You should have a file with
that name in /etc/pam.d.
- •
- XSECURELOCK_PASSWORD_PROMPT: Choose password prompt mode:
- •
- asterisks: shows asterisks, like classic password prompts. This is the
least secure option because password length is visible.
- •
- cursor: shows a cursor that jumps around on each key press. This is the
default.
-
________|_______________________
___________________|____________
- •
- disco: shows dancers, which dance around on each key press. Requires a
font that can handle Unicode line drawing characters, and FontConfig.
-
┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┗(･o･)┓ ♪ ┏(･o･)┛
┗(･o･)┓ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛ ♪ ┏(･o･)┛
- •
- emoji: shows an emoji, changing which one on each key press. Requires a
font that can handle emoji, and FontConfig.
- •
- emoticon: shows an ascii emoticon, changing which one on each key
press.
- •
- hidden: completely hides the password, and there’s no feedback for
keypresses. This would almost be most secure - however as it gives no
feedback to input whatsoever, you may not be able to notice accidentally
typing to another computer and sending your password to some
chatroom.
- •
- kaomoji: shows a kaomoji (Japanese emoticon), changing which one on each
key press. Requires a Japanese font, and FontConfig.
- •
- time: shows the current time since the epoch on each keystroke. This may
be the most secure mode, as it gives feedback to keystroke based
exclusively on public information, and does not carry over any state
between keystrokes whatsoever - not even some form of randomness.
- •
- time_hex: same as time, but in microseconds and hexadecimal.
“Because we can”.
- •
- XSECURELOCK_SAVER: specifies the desired screen saver module.
- •
- XSECURELOCK_SAVER_RESET_ON_AUTH_CLOSE: specifies whether to reset the
saver module when the auth dialog closes. Resetting is done by sending
SIGUSR1 to the saver, which may either just terminate, or handle this
specifically to do a cheaper reset.
- •
- XSECURELOCK_SHOW_DATETIME: whether to show local date and time on the
login. Disabled by default.
- •
- XSECURELOCK_SHOW_HOSTNAME: whether to show the hostname on the login
screen of auth_x11. Possible values are 0 for not showing the hostname, 1
for showing the short form, and 2 for showing the long form.
- •
- XSECURELOCK_SHOW_USERNAME: whether to show the username on the login
screen of auth_x11.
- •
- XSECURELOCK_SINGLE_AUTH_WINDOW: whether to show only a single auth window
from auth_x11, as opposed to one per screen.
- •
- XSECURELOCK_SWITCH_USER_COMMAND: shell command to execute when Win-O or
Ctrl-Alt-O are pressed (think “other user”). Typical
values could be lxdm -c USER_SWITCH, dm-tool switch-to-greeter,
gdmflexiserver or kdmctl reserve, depending on your desktop
environment.
- •
- XSECURELOCK_WAIT_TIME_MS: Milliseconds to wait after dimming (and before
locking) when above xss-lock command line is used. Should be at least as
large as the period time set using “xset s”. Also used by
wait_nonidle to know when to assume dimming and waiting has finished and
exit.
- •
- XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are
installed for use by saver_xscreensaver.
- •
- XSECURELOCK_XSCREENSAVER_PATH: Location where XScreenSaver hacks are
installed for use by saver_xscreensaver.
Additionally, XSecureLock spawns the
command-to-run-when-locked once locking is complete; this can be used
as a notification mechanism if desired.
The official bug tracker is at
<https://github.com/google/xsecurelock/issues/>.
The code is released unser the Apache 2.0 license. See the LICENSE
file for more details.
xss-lock (1), xautolock (1).
The README.md file included with XSecureLock contains full
documentation.
The XSecureLock source code and all documentation may be
downloaded on <https://github.com/google/xsecurelock/>.