gecko/other-licenses/nsis/Contrib/UAC/UAC Readme.html

223 lines
11 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head>
<title>UAC plug-in readme</title>
<script type="text/javascript">
function NavGL(q){window.open("http://www.google.com/search?hl=en&btnI=I&num=2&q="+escape(q));return 0;}
</script>
<style type="text/css">
html,body {background-color:#FFF; color:#000;}
a:link, a:visited, a:active {color:#00F;}
h2 {border-bottom:0.1em solid #000;}
#docHdrHdln{text-align:center;}
.importanttxt {color:#e00;}
.code {font-family:monospace;}
.nsisvar {color:#C00;}
.str {color:#390}
.inifile {background-color:#EEE;border:1px solid #000;padding:0.2em;}
.inicomment {background-color:#f5f5c5;color:#555;}
table.piexport {text-align:left;margin-bottom:1em;}
table.piexport td {vertical-align:top;}
table.piexport table.ret {padding:0;margin:0;border:0;}
</style>
</head><body>
<h1 id="docHdrHdln">UAC plug-in</h1>
<code><pre>
Interactive User (MediumIL) Admin user(HighIL)
+++[Setup.exe]++++++++++++++ +++[Setup.exe]++++++++++++++
+ + + +
+ ***[.OnInit]************ + + ***[.OnInit]************ +
+ * UAC::RunElevated >---+-+------>+ * * +
+ * NSIS.Quit() * + + * * +
+ ************************ + + ***********||*********** +
+ + + || +
+ + + \/ +
+ ***[Sections]*********** + + ***[Sections]*********** +
+ * * + /--+-+-< UAC::Exec * +
+ ************************ + | + ************************ +
+ + | + +
+ Win32.CreateProcess() <-+----/ + +
+ + + +
++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++
</pre></code>
<h2>Contents</h2>
<ul>
<li><a href="#exports">Plugin Functions</a>
<li><a href="#lang">Language support</a>
<li><a href="#knownissues">Known Issues</a>
<li><a href="#glossary">Glossary</a>
</ul>
<a name="exports"><h2>Plugin Functions</h2></a><div class="CntSec"><p>
Every function will try to emulate the basic NSIS instruction (of similar name) when UAC::RunElevated has not "succeeded" or running on a system that does not support elevation (Win9x/NT4)</p>
<table class="piexport"><tr><th colspan=2>UAC::RunElevated</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code (0 on success, 1223 if user aborted elevation dialog, anything else should be treated as a fatal error)</td></tr>
<tr><td><span class="nsisvar">$1</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0</span>:
<table class="ret">
<tr><td>0</td><td>UAC is not supported by the OS</td></tr>
<tr><td>1</td><td>Started a elevated child process, the current process should act like a wrapper (Call Quit without any further processing)</td></tr>
<tr><td>2</td><td>The process is already running @ HighIL (Member of admin group)</td></tr>
<tr><td>3</td><td>You should call RunElevated again (This can happen if a user without admin priv. is used in the runas dialog)</td></tr>
</table>
</td></tr>
<tr><td><span class="nsisvar">$2</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0 && <span class="nsisvar">$1</span>==1</span>: ExitCode of the elevated fork process (The NSIS errlvl is also set)</td></tr>
<tr><td><span class="nsisvar">$3</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0</span>: 1 if the user is a member of the admin group or 0 otherwise</td></tr>
</table></td></tr>
<tr><td>Description:</td><td>Allows non-admin/UAC.LUA users to re-spawn the installer as another user and UAC.Admin users to elevate.</td></tr>
</table>
<!--table class="piexport"><tr><th colspan=2>UAC::RunElevatedAndProcessMessages <i style="font-size:smaller;">(Experimental)</i></th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><i>See UAC::RunElevated</i></td></tr>
<tr><td>Description:</td><td>Version of UAC::RunElevated that can be called from a page</td></tr>
</table-->
<table class="piexport"><tr><th colspan=2>UAC::Unload</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td></td></tr>
<tr><td>Description:</td><td>Cleanup, you must call this function in .OnInstFailed, .onUserAbort and .OnInstSuccess</td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::Exec</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ExecWait</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ShellExec</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:Verb&gt; &lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
</table></td></tr>
</table>
<table class="piexport"><tr>
<th colspan=2>UAC::ShellExecWait</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:Verb&gt; &lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
</table></td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::IsAdmin</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> (BOOL) result</td></tr>
<tr><td>Description:</td><td>Check current thread/process token for a non-deny admin group SID entry</td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::ExecCodeSegment</th></tr>
<tr><td>Parameters:</td><td>&lt;INT:NSISFunctionAddress&gt;</td></tr>
<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
<tr><td>Description:</td><td>Calls NSIS function in LUA/outer instance (If you use instructions that alter the UI or the stack/variables in the code segment (StrCpy,Push/Pop/Exch,DetailPrint etc.) they will affect the hidden wrapper installer and not "your" installer instance)</td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::StackPush</th></tr>
<tr><td>Parameters:</td><td>&lt;STR:String&gt;</td></tr>
<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
<tr><td>Description:</td><td>Push to outer instance stack (For use with UAC::ExecCodeSegment)</td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::GetOuterHwnd</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> HWNDPARENT of outer instance</td></tr>
<tr><td>Description:</td><td>For use with ${UAC.RunElevatedAndProcessMessages}</td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::SupportsUAC</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td><span class="nsisvar">$0</span> !=0 if supported</td></tr>
<tr><td>Description:</td><td>Check if the OS supports UAC (And the user has UAC turned on) <span class="importanttxt">This function only tests if UAC is active, will return 0 on NT5 even though runas is implemented on those platforms, will also return 0 on NT6+ if UAC is off. You should only call this function during testing, NOT to determine if you can call UAC::RunElevated</span></td></tr>
</table>
<table class="piexport"><tr><th colspan=2>UAC::GetElevationType</th></tr>
<tr><td>Parameters:</td><td></td></tr>
<tr><td>Returns:</td><td>
<table class="ret">
<tr><td><span class="nsisvar">$0</span></td><td><a href="#" OnClick="return NavGL('TOKEN_ELEVATION_TYPE Enumeration')">TOKEN_ELEVATION_TYPE</a>:
<table class="ret">
<tr><td>0</td><td>Unsupported/Failed (ErrorFlag is also set)</td></tr>
<tr><td>1</td><td>TokenElevationTypeDefault: User is not using a split token (UAC disabled)</td></tr>
<tr><td>2</td><td>TokenElevationTypeFull: UAC enabled, the (current) process is elevated</td></tr>
<tr><td>3</td><td>TokenElevationTypeLimited: UAC enabled, the process is not elevated</td></tr>
</table>
</td></tr>
</table></td></tr>
</table>
</div>
<a name="lang"><h2>Language support</h2></a><div class="CntSec">
<p>If the plugin is built with FEAT_CUSTOMRUNASDLG_TRANSLATE (Enabled by default),
you can extract a file named <span class="str">UAC.LNG</span> to <span class="nsisvar">$pluginsdir</span>.
It is a ini file with the following sections:
</p><pre class="inifile">
[MyRunAsCfg]
<span class="inicomment">;Set to 1 to disable the radio button</span>
DisableCurrUserOpt=
<span class="inicomment">;Set to 1 to hide the radio button</span>
HideCurrUserOpt=
[MyRunAsStrings]
DlgTitle=Hello There!
HelpText=Just do your thing!
<span class="inicomment">;Label for current user radio button, %s is replaced with result of GetUserNameEx(NameSamCompatible,...)</span>
OptCurrUser=Self service (%s)
OptOtherUser=Run as someone:
UserName=Who:
Pwd=PIN:
OK=Okey!
Cancel=No Way</pre>
</div>
<a name="knownissues"><h2>Known Issues</h2></a><div class="CntSec">
<ul>
<li>UACPI.KI#1: DetailPrint in outer process is ignored
<li>UACPI.KI#2: Elevation can fail if the installer is located on a remote share that requires authentication
</ul>
</div>
<a name="glossary"><h2>Glossary</h2></a><div class="CntSec">
<ul>
<li>AAM: Admin Approval Mode
<li>IL: Integrity level (Part of the new MIC/WIC security levels added to NT6)
<li>LUA: Limited/Least-privilege User Account
<li>MIC: <a href="http://en.wikipedia.org/wiki/Mandatory_Integrity_Control">Mandatory Integrity Controls</a> (Now known as WIC)
<li>UAC: User Account Control (Part of the UAP umbrella)
<li>UAP: User Account Protection
<li>WIC: <a href="http://www.securityfocus.com/infocus/1887">Windows Integrity Controls</a>
<li>Win32 error code: Standard windows error codes, ERROR_???
</ul>
</div>
</body></html>