Ubuntu Manpage: sphinx-x11 - simple script interpreter for integrating password managers with X11

Provided by: pwdsphinx-tools_2.0.3-1_all

NAME

       sphinx-x11 - simple script interpreter for integrating password managers with X11

DESCRIPTION

       sphinx-x11(1) is a simple “script” language interpreter that integrates the SPHINX CLI with X11.

SPHINX-SCRIPT PARAMETERS

       All  sphinx-x11(1)  scripts  expect  a  username  and  a  hostname  as  the  first  and  second parameter
       respectively.

VOCABULARY

• type "text...": types the text into the currently focused X11 window.

• wait-for-click: waits until the user clicks anywhere.

• user: types the username - usually given as the first parameter to the sphinx-script - into the
currently focused X11 window.

• host: types the hostname - usually given as the second parameter to the sphinx-script - into the
currently focused X11 window.

• pwd: gets a password using getpwd(1) and sphinx(1), and types it into the currently focused X11 window.

• otp: calculates the current TOTP pin code using the a TOTP secret stored in sphinx(1) using getpwd(1) ,
which is then typed into the currently focused X11 window.

• tab: types a tabulator into the current X11 window, possibly advancing between form-fields.

• enter: sends an enter key press to the currently focused X11 window, possibly submitting a form.

• gethost: waits for a left mouse-click on a browser window, and then copies the URL from the urlbar into
the clipboard, and then strips it down to the hostname and sets an internal “$host” variable that can
then be used with host or pwd.

• getuser dispatches a sphinx list $host and if more than one user is returned, offers them in a dmenu
widget, if/when one user is found/selected it is set as an internal $user variable which can then used
for verbs like user or pwd.

Any lines not consisting of these tokens are simply ignored.

OTP SUPPORT

       In  this  interpreter/implementation  a  TOTP value is assumed to be stored with a username prefixed with
       otp://, so that a regular login name can co-exist with the according TOTP secret in sphinx.

       For example in a common 2FA login the first pwd operation uses e.g. joe as a username and  then  for  the
       TOTP value it uses otp://joe as the username, which allows for seamless 2FA login.

DEFAULT SCRIPTS

       sphinx-x11(1)  comes  with  5  default  sphinx-scripts (note on debian and derivates instead of a .sphinx
       extension they have a sx11- prefix):

       • pass.sphinx  : gets a password using sphinx(1), types it and submits it.

       • user-pass.sphinx  : gets a password using sphinx(1), types the user, then the password and submits it.

       • user-pass-otp.sphinx  : gets a password, and a TOTP pin code using sphinx(1), first types the username,
         then the password, then submits the form, and finally enters the TOTP pin and submits that as well.

       • otp.sphinx  : gets a TOTP pin code using sphinx(1) and types and submits it.

       • getacc-user-pass.sphinx: waits for a click on a browser window, from  with  it  gets  the  target  host
         value,  then  using  that  uses  sphinx  list to get the users associated with this host, and if one is
         selected, waits for another click in the user input field of a login form, then gets a  password  using
         sphinx(1), types the user, then the password and submits it.

       Each  of these scripts waits for the user to click, then they retrieve the relevant password (and/or TOTP
       token) before inserting it into the form fields, navigating between them with tab  and  enter.   You  are
       welcome to contribute adapted sphinx-scripts for websites that have other login semantics.

EXAMPLE

       As an example the user-pass-otp.sphinx script is explained below:

              #!sphinx-x11

              wait-for-click
              user
              tab
              pwd
              tab
              enter
              wait-for-click
              otp
              enter

       The  first line specifies sphinx-x11(1) as the interpreter.  The script itself then waits for the user to
       click (line 3), then in line 4 inserts the user - which is specified  as  the  first  parameter  to  this
       script.   Line  5 injects a tab so the next form field is selected.  Then pwdsphinx/getpwd is used to get
       the password for user and host - the host being the 2nd parameter to  this  script.   enter  is  used  to
       submit  this form in line 8.  Since this is a new form the script waits (line 9) for the user to click in
       the field where the TOTP value needs to be inserted.  Then in line 10 the TOTP  value  is  queried  using
       pwdsphinx/getpwd,  and  finally  in the last line the TOTP value is submitted by injecting enter into the
       application.

REPORTING BUGS

       https://github.com/stef/pwdsphinx/issues/

AUTHOR

       Written by Stefan Marsiske.

COPYRIGHT

       Copyright   ©   2023   Stefan   Marsiske.    License   GPLv3+:   GNU   GPL    version    3    or    later
       https://gnu.org/licenses/gpl.html.   This  is  free software: you are free to change and redistribute it.
       There is NO WARRANTY, to the extent permitted by law.