basis/elevate/elevate-docs.factor

   1 USING: arrays elevate.private help.markup help.syntax
   2 io.launcher kernel strings system words ;
   3 IN: elevate
   4
   5 : $say-shexw ( children -- )
   6     drop "ShellExecuteW" dup "windows.shell32" lookup-word [ ($link) ] [ $snippet ] if ;
   7
   8 ABOUT: elevate
   9
  10 ARTICLE: "elevate" "Elevated permissions API"
  11     "The " { $vocab-link "elevate" } " vocabulary provides abstractions for running programs with elevated (administrator) privileges (permissions). It allows code to relaunch itself or other programs with administrator privileges after requiring a password."
  12     $nl
  13      "This vocabulary is inspired by and ported from " { $url "https://github.com/barneygale/elevate" "Barney Gale's elevate.py" } "."
  14     { $subsections elevate elevated lowered }
  15
  16     "However, there are many caveats: " { $link "elevate.bugs" }
  17 ;
  18
  19 ARTICLE: "elevate.bugs" "Elevate bugs and caveats"
  20     "There are many inherent platform-specific limitations and workarounds in the " { $vocab-link "elevate" } " elevated privileges API. This article explains and documents them for the curious, future maintainers, or those who run into problems."
  21     { $heading "macOS" }
  22     "On Apple macOS, an Applescript command is attempted for a graphical method before " { $snippet "sudo" } ". Sometimes, this command appears to execute incorrectly due to the group of the user owning the calling process. On macOS, " { $snippet "sudo" } " suffers the drawback mentioned below for applications which do not have a TTY connected."
  23     { $heading "Linux, *BSD and other Unix-likes" }
  24     "On Linux, " { $snippet "gksudo" } ", " { $snippet "kdesudo" } ", and " { $snippet "pkexec" } " are all attempted graphical methods before " { $snippet "sudo" } "."
  25     { $list
  26         { { $snippet "pkexec" } " is the preferred and most secure graphical authentication method on Linux. It is undesirable for Factor applications, because unless a certain rare global registry value is set, " { $snippet "pkexec" } " does not set the " { $snippet "$DISPLAY" } " environment variable, and thus cannot launch graphical applications despite being a graphical program itself. It is tried after " { $snippet "gksudo" } " and " { $snippet "kdesudo" } " but before " { $snippet "sudo" } "." }
  27         { { $snippet "gksudo" } " and " { $snippet "kdesudo" } " are deprecated, but still present on most GTK- and KDE-based systems, respectively. GTK is more widespread than KDE so " { $snippet "gksudo" } " is tried before " { $snippet "kdesudo" } ". These old-fashioned methods ensure that the launched application can be graphical, so they are preferred for Factor." }
  28         { { $snippet "sudo" } " is the final and most robust strategy tried on Linux. It is text-based, so it requires the calling process to have an active and accessible terminal (TTY) for user authentication. If the calling Factor application was started from the desktop graphical shell rather than from a TTY, this method will fail." }
  29     }
  30     "On other Unix-like or POSIX-like operating systems, " { $snippet "sudo" } " is the only consistently popular method of authentication, and it suffers the same drawback on other Unix-likes as on Linux."
  31     { $heading "Windows" }
  32     { "On Windows, the FFI word " { $say-shexw } " is used with the verb " { $snippet "runas" } " to force the new process to run with User Account Control." }
  33 ;
  34
  35 HELP: elevated
  36 { $values { "command" { $or array string } } { "replace?" boolean } { "win-console?" boolean } { "posix-graphical" boolean } }
  37 { $description
  38     "Spawn a process from the command " { $snippet "command" } " with superuser (administrator) privileges. If the calling process does not already have superuser privileges, it will request them by a number of platform-specific methods."
  39     $nl
  40     "If " { $snippet "replace?" } " is " { $link t } ", the calling Factor process will be replaced with the command (but see Notes)."
  41     $nl
  42     "Windows-specific: If " { $snippet "win-console?" } " is " { $link t } ", a new console window will " { $emphasis "always" } " be spawned for the resulting process, regardless of " { $snippet "replace?" } "."
  43     $nl
  44     "Mac and Linux-specific: If " { $snippet "posix-graphical?" } " is " { $link t } ", a graphical password method will be attempted before " { $snippet "sudo" } "."
  45     $nl
  46     "If the calling process is already run as superuser, nothing happens. The input command is left on the stack, placed into a "{ $link process } " inside an "{ $link array } "."
  47 }
  48 { $notes
  49     { $list
  50         { "On Windows, " { $snippet "replace?" } " has the effect of killing (with " { $link exit } ") the calling process after spawning the command because there is no " { $snippet "exec" } " equivalent in Windows." }
  51     }
  52 }
  53 { $errors
  54     { $link elevated-failed } " when all strategies fail."
  55     $nl
  56     "Any errors thrown by " { $link run-process } "."
  57 } ;
  58
  59 HELP: elevate
  60 { $values { "win-console?" boolean } { "posix-graphical" boolean } }
  61 { $description "Relaunch the current Factor process with superuser privileges. See " { $link elevated } " for an explanation, as the semantics are identical." } ;
  62
  63 HELP: lowered
  64 { $description "Give up all superuser rights, returning a process to normal userspace."
  65 { $notes "If the process is running as \"real superuser\", (not an impersonation), nothing happens." $nl "If the process is running as an unprivileged user, nothing happens." }
  66 }
  67 { $errors { $link lowered-failed } " when giving up superuser rights failed." } ;