JEDI Windows API » manifest

Elevate application on Vista with JWSCL

Christian Wimmer — Tue, 18 Mar 2008 13:00:44 +0000

This little article shows you how to elevate an application using JWSCL.
There are two possible ways to elevate an application :

Elevate the application from the beginning
Elevate special parts of your application

Both ways needs a manifest to be included into your application.

1. Elevate the application from the beginning

The easiest way to elevate an application is to tell Windows to do it for you. This is done by applying a manifest.

A manifest is a text resource that tells Windows what needs to be prepared before your application starts. This includes theme support and privileges your application needs. Developers maybe know it from Windows XP where it enables themed window controls.

Telling Windows to start your application as an administrator is done by using “requireAdministrator” as required security level in the manifest. However the code below is just an excerpt. You can get a full version of the manifest with a warning.

>
>
level="requireAdministrator"/>
>
>

If you are going to use this manifest in your application, you have to consider that your application needs to be elevated all the time. Thus users without administrator access cannot launch your application at all.

However there is a second way which does not need a manifest at all. Some applications do start their own process with elevated rights. They start a second instance, close the actual one and go on elevated.
Examples are :

the Taskmanager can elevate itself by clicking “Show processes from all users”
ProcessExplorer

JWSCL contains a unit called JwsclElevation which provides the necessary functions to allow this simple elevation.

function JwShellExecute(const hWnd: HWND; FileName, Parameters,
Directory: TJwString; ShowCmd: Integer): HINST;
This function just works like the usual ShellExecute but let’s you elevate any program or your application. The return value In the following way you can start the command line prompt with elevated privileges.

var hProc : THandle;
begin
hProc := JwShellExecute(0, ‘cmd’, ”, ”, SW_SHOW);
if hProc <> 0 then
CloseHandle(hProc);

The developer version (revision > 317) does have some more extension, less bugs and a different behavior.

function JwShellExecute(const hWnd: HWND;
FileName,
Parameters,
Directory: TJwString;
ShowCmd: Integer;
Flags : TJwShellExecuteFlags = [sefNoClosehProcess]): HANDLE;

Let me list the differences :

JwShellExecute raises EJwsclWinCallFailedException when the call to ShellExecuteEx fails.
The new optional parameter Flags controls some aspects
- sefNoUi does not allow ShellExecute to show error messages on the user’s screen
- sefIgnoreElevationIfNotAvailable. Usually JwShellExecute checks whether the user is already elevated and if so just starts the application. However this call will fail on preVista systems. If this flag is set the function will not fail on preVista systems and just execute the application.
- sefFixDirWithRunAs. ShellExecute ignores the directory parameter if it is called with the “runas” verb. However with this flag set, the JEDI function uses a trick to start the application in the correct directory. In this way there maybe a command window visible.
- sefNoClosehProcess. The newer version of JwShellExecute closes the returned process handle for you if this flag is not set. If you need that process handle (e.g. waiting for the process to end) you should remove it.
The return value is a handle to the process. It is now automatically closed for your if you do not deny it through the flag parameter.

The following code shows how to start the application with elevated privileges from whithin the same app.

var NewProcessHandle : HANDLE;
begin
try
NewProcessHandle := JwShellExecute(ForeGroundWindow,
ParamStr(0), Parameter, Directory, SW_NORMAL,
[sefNoUi, sefFixDirWithRunAs,
sefIgnoreElevationIfNotAvailable, sefNoClosehProcess]);
except
On E : EJwsclWinCallFailedException do
begin
LastError := E.LastError;
//do error stuff here
exit;
end;
end;
//make sure the app has started
if NewProcessHandle <> 0 then
begin
//wait for the app to be initialized and read to get user input
//or just remove it – what you like
WaitForInputIdle(NewProcessHandle, yourTimeHere);
CloseHandle(NewProcessHandle);
//terminate your application here
end;
…

2. Elevate special parts of your application

To elevate special parts of your application is the prefered way for a Vista application. This is done by separate the parts of your application that needs administrative rights, into an external process. We do not need to create a new application and do the inter-process communication stuff. Windows Vista uses an external COM process for this task. So the solutions goes with a COM DLL that we have to implement. In addition to that we also have to add a manifest – of course.

>
>
level="asInvoker"/>
>
>

I will not tell the whole story about how to create a COM DLL and do all the stuff that has to be done. You should read Aleksander Oven’s tutorial how to accomplish that.
I’m going to show you how you can use the JWSCL methods.

Create your COM Dll and implement the COM interface. This may look like this (from the RunEl example in JWSCL):

uses jwaWindows, ActiveX, Dialogs,
Classes, ComObj, RunElCOM_TLB, StdVcl;

type
TJwRunElevated = class(TTypedComObject, IJwRunElevated)
protected
function RunAppElevated(AppName: PWideChar;
Parameter: PWideChar; Dir: PWideChar;
ClientProcessID: LongWord; out NewThreadHandle: LongWord;
out NewProcessHandle: LongWord;
out ResultValue: LongWord): HResult; stdcall; end;
…

The important stuff comes here.

initialization
TElevationClassFactory.Create(
@ElevationDescription, true,
ComServer, TJwRunElevated,
CLASS_JwRunElevated,
iMultiInstance);

Use the TElevationClassFactory or TJwElevationClassFactory (in developer version > 317) for registering the COM class in Windows. After you registered the COM class using regsvr32 (see Tutorial) you can retrieve an instance of the COM class with JwCoCreateInstanceAsAdmin.

var
ElevatedObject: IJwRunElevated;
Result : HRESULT;
begin
Result := JwCoCreateInstanceAsAdmin(
ForeGroundWindow,
CLASS_JwRunElevated,
IID_IJwRunElevated,
ElevatedObject);

If the thread has already elevated privileges the function JwCoCreateInstanceAsAdmin simply returns an instance without using the elevation prompt.

In developer version (revision > 317) the returned result value can contain information about the status.

ERROR_SUCCESS – No error
(revision > 317) ERROR_CANCELLED – the user has canceled the UAC prompt.
(revision > 317) E_CLASS_IS_NOT_SETUP – the requested COM class has not been setup to be used for elevation.
CoGetObject (if elevation is required) or CoCreateInstance (if elevation is not required) may return an error value

Be warned:
If you try to execute this function on a preVista system, the function is going to fail with EJwsclUnsupportedWindowsVersionException.

You can find the shown source code in the repository of JWSCL. The library has two sample applications that use the technics describes above:

RunEl (JwShellExecute and COM DLL) or Current repository.
VistaElevation (COM DLL). Download JWSCL or Current repository.

Warning:
There is a problem with the manifest scanner on Windows XP. If you try to start an application with a manifest created for Vista you’re goingt to probably have a Blue Screen of Death. So you have to get a correct manifest from here (english translation).

Tell me how you liked this blog entry by adding a comment.

Why aren’t dialogs themed in elevated COM methods.

Christian Wimmer — Fri, 14 Mar 2008 14:07:33 +0000

I found this question in the borland mailinglist:

… I get my dialog and all runs well – *except* I’ve lost theming
on this particular dialog. This means the application’s main windows shows
up correctly themed, the progress dialog does not. I’ve already added the
XP manifest to the progress dialog, too, but to no avail so far.

A theme is only applied if an EXE or DLL file has a manifest that explicitly enables theme support. If Windows cannot find this manifest, the process is only shown with the regular window design.

However the Vista elevation is done by creating a COM object and offers its methods through a seperate process. A seperate process is necessary because the same process cannot get assigned the ncessary administrator token. In our case a service in the service container svchost.exe has the task to host the COM object. The contained service is called dllhost.exe (service name: “COMSysApp”) and does not run until requested. It does not matter whether the service is deactivated or not because it is started directly by svchost.

The COM method and the dialog will run in the process space of the newly elevated dllhost.exe. And because there is no manifest information in this file you cannot get a themed dialog layout.

So how can you get a themed dialog anyhow?

The task is done by using the basic principles of COM. COM knowns Callback interfaces and other stuff. By using a Callback interface you can turn around the server – client principle.

Define a well known interface that is implemented by the client only. But also known to the server.
Add a parameter to your elevated COM method that receives a pointer to this interface.
Before calling an elevated method, create the interface and
apply a pointer to the method’s parameter you added.
Call the method and use the methods in the given callback interface. COM will automatically transfer the method calls to your non-elevated process. In this way you can create themed windows, do window management stuff (progress bar) and eventually close the window.

If you prefer to read code instead of text you should study this code excerpts.

Define a callback interface for your client and add it to the server’s TypeLib. Delphi will generate code for it automatically in a file called _TLB.pas (TLB Header). Do not create the interface by using the Delphi’s ActiveX expert. Just add it manually.

type
IMyCallback = interface(IUnknown)
[MYCALLBACK_GUID]
procedure ACallBackMethod(DataFromServer : …); safecall;
end;
//We do not need a CoClass

IMyCallback interface is known to both the server and the client, because we use the TLB Header in the client and the server. The client will implement and the server will receive a pointer to it and then call the included method ACallBackMethod everytime it wishes to do so.

The server implements a method to allow a callback interface to be passed to it.

type
IServerInt = interface(IDispatch)
[ISERVERINT_GUID]
procedure DoStuffThatNeedsCallBack(const Callback: IMyCallback;…) safecall;
end;
//TypeLib editor also declares a CoClass called CoServerInt

Of course you have to implement both interfaces: IServerInt and IMyCallback. However IServerInt is implemented on server side and IMyCallback is only implemented on the client side.

On client side (namely your application) write..

uses …, ComSrv,ComObj;
type
TMyCallback = class(TComObject, IMyCallback)
procedure ACallBackMethod(DataFromServer : …); safecall;
end;

…

Install the COM object anywhere before you’re going to use it.

TComObjectFactory.Create(ComServer,
TMyCallback, Class_MyCallback,
‘MyCallback’, //Classname
‘Description here’,
ciMultiInstance);

After all implement the callback method…

procedure TMyCallback.ACallBackMethod(DataFromServer : …);
begin
//do stuff on the non-elevated client side
end;

…and anywhere you like, call the method to use our Callback interface.

var Server : IServerInt;
Callback : IMyCallback;
begin
Server := CoServerInt.Create;
Callback := TMyCallback.Create as IMyCallback;

Server.DoStuffThatNeedsCallBack(Callback, …);
end;

I’m using TComObject and TComObjectFactory on the client side , because this way works for console applications, too. If you need the possibilities of TAutoIntfObject, you will have to write a standalone COM server with TApplication. However this is not necessary here. The method ACallBackMethod will be run in the client’s process space rather than the elevated helper process. You can check whether the callback method runs in the correct process (elevated or not?) with the following code.

procedure TMyCallback.ACallBackMethod(DataFromServer : …);
var Token : TJwSecurityToken;
begin
Token := TJwSecurityToken.CreateTokenEffective(TOKEN_QUERY or TOKEN_READ);
try
if Token.RunElevation = 0 then
ShowMessage(‘Process is NOT Elevated: ‘+IntToStr(GetCurrentProcessId))
else
ShowMessage(‘Process is Elevated: ‘+IntToStr(GetCurrentProcessId));
finally
Token.Free;
end;
end;

Second way, still on the client side:
If you already have a form class, you can add the interface to it.

type
TForm1 = class(TForm, IMyCallback)
protected
procedure ACallBackMethod(DataFromServer : …); safecall;
end;

Instead of creating the COM object, you pass a self-pointer to the method parameter.

procedure TForm1.OnButtonClick(…);
var Server : IServerInt;
Callback : IMyCallback;
begin
Server := CoServerInt.Create;

Server.DoStuffThatNeedsCallBack(Self, …);
end;

Be aware that in a multi thread environment, you have to make sure that resources in that specific form are accessed only by one thread at a time.

Eventually the server side calls the methods within the callback interface:

uses …, ComSrv,ComObj;

type
TServerIntImpl = class(TAutoObject, IServerInt)
procedure DoStuffThatNeedsCallBack(const Callback: IMyCallback;…) safecall;
end;

…
procedure TServerIntImpl.DoStuffThatNeedsCallBack(const Callback: IMyCallback;…)
begin
…
Callback.ACallBackMethod(…);
end;

…
initialization
TAutoObjectFactory.Create(ComServer, TMyCallback,
Class_MyCallback, ciMultiInstance);

The callback method will be called in the context of the client. So it will not be elevated. This is because there is no ordinary method call here. COM will pack the function stack and all its parameter into a stream, send it to the client, unpack it and restore a proper function stack to be executed. This happens in the client process of course.
Get more information about COM callbacks here.

Aside from the themed dialog problem you never should show window elements in such an elevated method. There is no need to it. All window elements can be displayed by using standard user rights. They do not need Administrator rights; otherwise we had to logon as Administrator.
However you only should do stuff that needs Administrator privileges in these COM methods. The more code you add to the method the more likely a bug may lead to a security risk. So simply call your function that needs Administrator rights, get the results and go back to Standard user rights. There is really no need to display a window with Administrator privilege.

Tell me how you liked this blog entry by adding a comment.