PageRenderTime 75ms CodeModel.GetById 20ms app.highlight 18ms RepoModel.GetById 32ms app.codeStats 0ms

/admin/win/nsi/nsis_uac/UAC Readme.html

http://github.com/tomahawk-player/tomahawk
HTML | 222 lines | 187 code | 30 blank | 5 comment | 0 complexity | 6883d6d47aa8f3dd8667e066f93f099c MD5 | raw file
  1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2<html><head>
  3<title>UAC plug-in readme</title>
  4<script type="text/javascript">
  5function NavGL(q){window.open("http://www.google.com/search?hl=en&btnI=I&num=2&q="+escape(q));return 0;}
  6</script>
  7<style type="text/css">
  8html,body {background-color:#FFF; color:#000;}
  9a:link, a:visited, a:active {color:#00F;}
 10h2 {border-bottom:0.1em solid #000;}
 11#docHdrHdln{text-align:center;}
 12.importanttxt {color:#e00;}
 13.code {font-family:monospace;}
 14.nsisvar {color:#C00;}
 15.str {color:#390}
 16.inifile {background-color:#EEE;border:1px solid #000;padding:0.2em;}
 17.inicomment {background-color:#f5f5c5;color:#555;}
 18table.piexport {text-align:left;margin-bottom:1em;}
 19table.piexport td {vertical-align:top;}
 20table.piexport table.ret {padding:0;margin:0;border:0;}
 21</style>
 22</head><body>
 23<h1 id="docHdrHdln">UAC plug-in</h1>
 24
 25
 26<code><pre>
 27Interactive User (MediumIL)        Admin user(HighIL)
 28+++[Setup.exe]++++++++++++++       +++[Setup.exe]++++++++++++++
 29+                          +       +                          +
 30+ ***[.OnInit]************ +       + ***[.OnInit]************ +
 31+ * UAC::RunElevated >---+-+------>+ *                      * +
 32+ * NSIS.Quit()          * +       + *                      * +
 33+ ************************ +       + ***********||*********** +
 34+                          +       +            ||            +
 35+                          +       +            \/            +
 36+ ***[Sections]*********** +       + ***[Sections]*********** +
 37+ *                      * +    /--+-+-< UAC::Exec          * +
 38+ ************************ +    |  + ************************ +
 39+                          +    |  +                          +
 40+  Win32.CreateProcess() <-+----/  +                          +
 41+                          +       +                          +
 42++++++++++++++++++++++++++++       ++++++++++++++++++++++++++++
 43</pre></code>
 44
 45
 46<h2>Contents</h2>
 47<ul>
 48<li><a href="#exports">Plugin Functions</a>
 49<li><a href="#lang">Language support</a>
 50<li><a href="#knownissues">Known Issues</a>
 51<li><a href="#glossary">Glossary</a>
 52</ul>
 53
 54
 55
 56
 57
 58
 59<a name="exports"><h2>Plugin Functions</h2></a><div class="CntSec"><p>
 60Every 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>
 61
 62<table class="piexport"><tr><th colspan=2>UAC::RunElevated</th></tr>
 63<tr><td>Parameters:</td><td></td></tr>
 64<tr><td>Returns:</td><td>
 65	<table class="ret">
 66	<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>
 67	<tr><td><span class="nsisvar">$1</span></td><td><span class="code">If <span class="nsisvar">$0</span>==0</span>:
 68		<table class="ret">
 69		<tr><td>0</td><td>UAC is not supported by the OS</td></tr>
 70		<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>
 71		<tr><td>2</td><td>The process is already running @ HighIL (Member of admin group)</td></tr>
 72		<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>
 73		</table>	
 74		</td></tr>
 75	<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>
 76	<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>
 77	</table></td></tr>
 78<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>
 79</table>
 80<!--table class="piexport"><tr><th colspan=2>UAC::RunElevatedAndProcessMessages <i style="font-size:smaller;">(Experimental)</i></th></tr>
 81<tr><td>Parameters:</td><td></td></tr>
 82<tr><td>Returns:</td><td><i>See UAC::RunElevated</i></td></tr>
 83<tr><td>Description:</td><td>Version of UAC::RunElevated that can be called from a page</td></tr>
 84</table-->
 85
 86<table class="piexport"><tr><th colspan=2>UAC::Unload</th></tr>
 87<tr><td>Parameters:</td><td></td></tr>
 88<tr><td>Returns:</td><td></td></tr>
 89<tr><td>Description:</td><td>Cleanup, you must call this function in .OnInstFailed, .onUserAbort and .OnInstSuccess</td></tr>
 90</table>
 91
 92<table class="piexport"><tr>
 93<th colspan=2>UAC::Exec</th></tr>
 94<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
 95<tr><td>Returns:</td><td>
 96	<table class="ret">
 97	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
 98	</table></td></tr>
 99</table>
100<table class="piexport"><tr>
101<th colspan=2>UAC::ExecWait</th></tr>
102<tr><td>Parameters:</td><td>&lt;INT:ShowWindow&gt; &lt;STR:App&gt; &lt;STR:Parameters&gt; &lt;STR:WorkingDir&gt;</td></tr>
103<tr><td>Returns:</td><td>
104	<table class="ret">
105	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
106	<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
107	</table></td></tr>
108</table>
109<table class="piexport"><tr>
110<th colspan=2>UAC::ShellExec</th></tr>
111<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>
112<tr><td>Returns:</td><td>
113	<table class="ret">
114	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
115	</table></td></tr>
116</table>
117<table class="piexport"><tr>
118<th colspan=2>UAC::ShellExecWait</th></tr>
119<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>
120<tr><td>Returns:</td><td>
121	<table class="ret">
122	<tr><td><span class="nsisvar">$0</span></td><td>Win32 error code, 0 on success (ErrorFlag is also set on error)</td></tr>
123	<tr><td><span class="nsisvar">$1</span></td><td>Exitcode of new process</td></tr>
124	</table></td></tr>
125</table>
126
127<table class="piexport"><tr><th colspan=2>UAC::IsAdmin</th></tr>
128<tr><td>Parameters:</td><td></td></tr>
129<tr><td>Returns:</td><td><span class="nsisvar">$0</span> (BOOL) result</td></tr>
130<tr><td>Description:</td><td>Check current thread/process token for a non-deny admin group SID entry</td></tr>
131</table>
132
133<table class="piexport"><tr><th colspan=2>UAC::ExecCodeSegment</th></tr>
134<tr><td>Parameters:</td><td>&lt;INT:NSISFunctionAddress&gt;</td></tr>
135<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
136<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>
137</table>
138
139<table class="piexport"><tr><th colspan=2>UAC::StackPush</th></tr>
140<tr><td>Parameters:</td><td>&lt;STR:String&gt;</td></tr>
141<tr><td>Returns:</td><td>[None] (ErrorFlag is set on error)</td></tr>
142<tr><td>Description:</td><td>Push to outer instance stack (For use with UAC::ExecCodeSegment)</td></tr>
143</table>
144
145<table class="piexport"><tr><th colspan=2>UAC::GetOuterHwnd</th></tr>
146<tr><td>Parameters:</td><td></td></tr>
147<tr><td>Returns:</td><td><span class="nsisvar">$0</span> HWNDPARENT of outer instance</td></tr>
148<tr><td>Description:</td><td>For use with ${UAC.RunElevatedAndProcessMessages}</td></tr>
149</table>
150
151<table class="piexport"><tr><th colspan=2>UAC::SupportsUAC</th></tr>
152<tr><td>Parameters:</td><td></td></tr>
153<tr><td>Returns:</td><td><span class="nsisvar">$0</span> !=0 if supported</td></tr>
154<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>
155</table>
156
157<table class="piexport"><tr><th colspan=2>UAC::GetElevationType</th></tr>
158<tr><td>Parameters:</td><td></td></tr>
159<tr><td>Returns:</td><td>
160	<table class="ret">
161	<tr><td><span class="nsisvar">$0</span></td><td><a href="#" OnClick="return NavGL('TOKEN_ELEVATION_TYPE Enumeration')">TOKEN_ELEVATION_TYPE</a>:
162		<table class="ret">
163		<tr><td>0</td><td>Unsupported/Failed (ErrorFlag is also set)</td></tr>
164		<tr><td>1</td><td>TokenElevationTypeDefault: User is not using a split token (UAC disabled)</td></tr>
165		<tr><td>2</td><td>TokenElevationTypeFull: UAC enabled, the (current) process is elevated</td></tr>
166		<tr><td>3</td><td>TokenElevationTypeLimited: UAC enabled, the process is not elevated</td></tr>
167		</table>	
168		</td></tr>
169	</table></td></tr>
170</table>
171
172</div>
173
174
175
176
177
178<a name="lang"><h2>Language support</h2></a><div class="CntSec">
179<p>If the plugin is built with FEAT_CUSTOMRUNASDLG_TRANSLATE (Enabled by default), 
180you can extract a file named <span class="str">UAC.LNG</span> to <span class="nsisvar">$pluginsdir</span>. 
181It is a ini file with the following sections:
182</p><pre class="inifile">
183[MyRunAsCfg]
184<span class="inicomment">;Set to 1 to disable the radio button</span>
185DisableCurrUserOpt=
186<span class="inicomment">;Set to 1 to hide the radio button</span>
187HideCurrUserOpt=
188
189[MyRunAsStrings]
190DlgTitle=Hello There!
191HelpText=Just do your thing!
192<span class="inicomment">;Label for current user radio button, %s is replaced with result of GetUserNameEx(NameSamCompatible,...)</span>
193OptCurrUser=Self service (%s)
194OptOtherUser=Run as someone:
195UserName=Who:
196Pwd=PIN:
197OK=Okey!
198Cancel=No Way</pre>
199</div>
200
201<a name="knownissues"><h2>Known Issues</h2></a><div class="CntSec">
202<ul>
203<li>UACPI.KI#1: DetailPrint in outer process is ignored
204<li>UACPI.KI#2: Elevation can fail if the installer is located on a remote share that requires authentication
205</ul>
206</div>
207
208
209<a name="glossary"><h2>Glossary</h2></a><div class="CntSec">
210<ul>
211<li>AAM: Admin Approval Mode
212<li>IL: Integrity level (Part of the new MIC/WIC security levels added to NT6)
213<li>LUA: Limited/Least-privilege User Account
214<li>MIC: <a href="http://en.wikipedia.org/wiki/Mandatory_Integrity_Control">Mandatory Integrity Controls</a> (Now known as WIC)
215<li>UAC: User Account Control (Part of the UAP umbrella)
216<li>UAP: User Account Protection
217<li>WIC: <a href="http://www.securityfocus.com/infocus/1887">Windows Integrity Controls</a>
218<li>Win32 error code: Standard windows error codes, ERROR_???
219</ul>
220</div>
221
222</body></html>