Saturday, March 15, 2014

2014-03-15 Saturday - Research: Launching Applications via Custom Protocols

This weekend I'm researching options for integrating a client's custom application so that it can be launched by users from within a browser.  These are the links to the resources that I've found to be of the most interest - hopefully this will be use some use to someone else in the future.

Microsoft Windows / IE Related Notes

Understanding Protocols
http://blogs.msdn.com/b/ieinternals/archive/2011/07/14/url-protocols-application-protocols-and-asynchronous-pluggable-protocols-oh-my.aspx

  • In most cases, the invoked URL is injected to replace the %1 parameter in the registered \Shell\Open\Command.
  • Windows 7 and later also support protocol invocation via the IExecuteCommand::DelegateExecute COM mechanism, instead of using the Shell Open Command. Some browsers do not yet properly support DelegateExecute because they first look for a Shell Open Command in the registry before passing a URL to ShellExecute.
  • Thanks to their simplicity, and to the fact that the Windows ShellExecuteEx function can easily be used to launch such protocols, all major Windows web browsers (IE, Firefox, Chrome, Safari, Opera) support Application Protocols. However, there are some important differences in behavior between browsers.
  • despite their simplicity, Application Protocols have nevertheless been the source of a large number of vulnerabilities over the years, and thus nearly all browsers (except Safari) will prompt the user before launching the specified program.
  • In Internet Explorer 7 and later on Windows Vista and later, launching an application to handle an Application Protocol URL will also consult the Protected Mode Elevation policy for the target executable. By default, this policy is that the user will be prompted for permission to launch the program at the Medium Integrity Level:
  • Another behavior to be aware of is that some callers will decode or encode URLs before passing them along to the target program. For historical reasons, Internet Explorer performs a single percent-decoding pass on the URL before calling ShellExecute; by default IE9 and IE10 still perform this decoding unless the protocol’s registry key contains a REG_DWORD named UseOriginalUrlEncoding with value 0x1. However, the Windows Shell’s Start > Run command performs no such decoding pass.
  • On Windows 8, Apps may use their manifest to register to handle Application Protocols. Protocol activation APIs are more cleanly implemented in Metro-style apps
  • The msProtocols object was removed for the IE10 release preview. Instead use the msLaunchUri api to launch a protocol,
  • Web developers often ask if there’s some way to detect whether the client has a given protocol available. Generally, the answer is no, this isn’t possible

ShellExecuteEx function
http://msdn.microsoft.com/en-us/library/bb762154(v=vs.85).aspx

SHELLEXECUTEINFO structure
http://msdn.microsoft.com/en-us/library/bb759784(v=vs.85).aspx

  • lpParameters: Type: LPCTSTR Optional. The address of a null-terminated string that contains the application parameters. The parameters must be separated by spaces. If the lpFile member specifies a document file, lpParameters should be NULL.
  • lpVerb: Type: LPCTSTR A string, referred to as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. This parameter can be NULL, in which case the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry. The following verbs are commonly used:

How to handle URI activation (Windows Store apps using C#/VB/C++ and XAML)
http://msdn.microsoft.com/library/windows/apps/Hh779670(v=win.10).aspx

  • Windows allows an app to register to become the default handler for a certain URI scheme name. Both desktop and Windows Store apps can register to be a default handler for a URI scheme name
  • Any app or website can use your URI scheme name, including malicious ones. So any data that you get in the URI could come from an untrusted source. You should never perform a permanent action based on the parameters that you receive in a URI.
  •  If you are creating a new URI scheme name for your app, be sure to follow the guidance in RFC 4395. This ensures that your name meets the standards for URI schemes.

ProtocolActivatedEventArgs class
http://msdn.microsoft.com/en-us/library/windows/apps/windows.applicationmodel.activation.protocolactivatedeventargs.aspx

  • Provides data when an app is activated because it is the app associated with a URI scheme nam
  • JavaScript:  This type appears as WebUIProtocolActivatedEventArgs
    • The received URI is eventArgs.Uri.AbsoluteUri
Application.OnActivated method
http://msdn.microsoft.com/en-us/library/windows/apps/windows.ui.xaml.application.onactivated.aspx

How to handle file activation (Windows Store apps using C#/VB/C++ and XAML)
http://msdn.microsoft.com/en-us/library/windows/apps/hh779669.aspx

Association launching sample
http://code.msdn.microsoft.com/windowsapps/Association-Launching-535d2cec

File type and URI associations model
http://msdn.microsoft.com/en-us/library/windows/apps/hh848047.aspx

Guidelines for file types and URIs (Windows Store apps)
http://msdn.microsoft.com/en-us/library/windows/apps/hh700321.aspx

Guidelines and Registration Procedures for New URI Schemes
http://tools.ietf.org/html/rfc4395

About URL Monikers
http://msdn.microsoft.com/en-us/library/ms775149(v=vs.85).aspx

  • A moniker is a COM object that identifies an object and provides services to allow other components to obtain a pointer to that object. The system-provided moniker class supports asynchronous binding to a Uniform Resource Locator (URL).
  • Monikers connect to and activate objects, whether they are in the same machine or across a network. For example COM uses monikers to establish a network connection. They are also used to identify, connect to, and run OLE compound document link objects. In this case, the link source acts as the moniker provider and the container holding the link object acts as the moniker client.
  • Monikers are used as the basis for linking in OLE. After a moniker is bound to an object, the moniker's IMoniker interface can be used to locate, activate, and access the bound object without having any other specific information on where the actual object is located. The COM moniker architecture provides a convenient programming model for working with URLs. The moniker architecture supports extensible and complete name parsing, as well as printable names. Because URLs frequently refer to resources across high-latency networks, binding a moniker to a URL synchronously impacts performance. This is because the process has to wait for responses from the network before completing the binding. For this reason, the URL moniker class supports asynchronous as well as synchronous binding. For more information, see Creating and Using URL Monikers.

Creating and Using URL Monikers
http://msdn.microsoft.com/en-us/library/aa741006(v=vs.85).aspx

  • szExtraInfo,Behavior of this field is moniker-specific. For URL monikers, this string is appended to the URL when the bind operation is started. Like other OLE strings, this value is a Unicode string that the client should allocate using CoTaskMemAlloc. The URL moniker frees the memory later.
  • szCustomVerb,BSTR specifying a protocol-specific custom action to be performed during the bind operation (only if dwBindVerb is set to BINDVERB_CUSTOM).

BINDINFO structure
http://msdn.microsoft.com/en-us/library/ms774966(v=vs.85).aspx

Asynchronous Pluggable Protocols
http://msdn.microsoft.com/en-us/library/aa767743(v=VS.85).aspx

About Asynchronous Pluggable Protocols
http://msdn.microsoft.com/en-us/library/aa767916(v=vs.85).aspx

  • A URL follows the syntax described in RFC 1738, which specifies a protocol scheme followed by a scheme-specific portion (:).
  •  Uniform Resource Locators (URL)
  • Internet Explorer uses two mechanisms for registering new URL protocol handlers. The first method is to register a URL protocol and its associated application so that all attempts to navigate to a URL using that protocol launch the application (for example, registering applications to handle mailto: or news: URLs). The second method uses the Asynchronous Pluggable Protocols API, which allows you to define new protocols by mapping the protocol scheme to a class.
  • An asynchronous pluggable protocol handler is an apartment-threaded COM object that handles any calls made to the protocol scheme for which it is registered
  • When a client application makes a request, Urlmon looks up the protocol scheme in the registry and creates an instance of the protocol handler registered for that protocol scheme. If the protocol scheme was successfully mapped to the class identifier (CLSID) of a protocol handler, CoCreateInstance is called with that class asking for an IClassFactory interface. An instance of the protocol handler is obtained with IClassFactory::CreateInstance.
  • To register a custom URL protocol, add a key for the protocol scheme of the custom URL protocol to the registry under HKEY_CLASSES_ROOT\PROTOCOLS\Handler\protocol_scheme. Under that key, the string value, CLSID, must be set to the CLSID of the protocol handler.
  • The protocol handler cannot use any Windows messaging to switch back to the thread it was instantiated on, since the protocol handler must work on non-GUI threads.
  • A pluggable MIME filter is an asynchronous pluggable protocol that receives data through a stream, performs some operation on the data, and returns a data stream. The output data might be in a different format from the original stream.

Asynchronous Pluggable Protocol Overviews
http://msdn.microsoft.com/en-us/library/jj650247(v=vs.85).aspx

Registering an Application to a URL Protocol
http://msdn.microsoft.com/en-us/library/aa767914(v=vs.85).aspx

URL Monikers Overviews and Tutorials
http://msdn.microsoft.com/en-us/library/ms775150(v=vs.85).aspx

Handling MIME Types in Windows Internet Explorer
http://msdn.microsoft.com/en-us/library/ms775148(v=vs.85).aspx

MIME Type Detection in Windows Internet Explorer
http://msdn.microsoft.com/en-us/library/ms775147(v=vs.85).aspx
- MIME type Detection Algorithm discussion

FindMimeFromData function
http://msdn.microsoft.com/en-us/library/ms775107(v=vs.85).aspx

Auto-Launching apps using file and URI associations for Windows Phone 8
http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj206987(v=vs.105).aspx

Launcher.LaunchFileAsync(IStorageFile) | launchFileAsync(IStorageFile) method
http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh701471.aspx

Understanding the Protected Mode Elevation Dialog
http://blogs.msdn.com/b/ieinternals/archive/2009/12/01/understanding-internet-explorer-security-protected-mode-elevation-dialog.aspx

Custom URL Protocol for Invoking Application
http://www.codeproject.com/Articles/332206/Custom-URL-Protocol-for-Invoking-Application

Custom HyperLinks Using a Generic Protocol Handler
http://www.codeproject.com/Articles/545083/Custom-HyperLinks-Using-a-Generic-Protocol-Handler

Custom Hyperlinks Using Asynchronous Pluggable Protocols
http://www.codeproject.com/Articles/15634/Custom-Hyperlinks-Using-Asynchronous-Pluggable-Pro

A windows 8 trick: Protocol activation of apps (and the nick app)
http://10rem.net/blog/2012/12/05/a-windows-8-trick-protocol-activation-of-apps-and-the-nick-app

Using protocol handlers as a ultra thin layer of integration
http://jonas.follesoe.no/2007/08/21/using-protocol-handlers-as-a-ultra-thin-layer-of-integration/
- see ProtocolHandlerDemo.zip


Firefox Related Notes

Web-based protocol handlers
https://developer.mozilla.org/en-US/docs/Web-based_protocol_handlers

MozillaZine
Register protocol
http://kb.mozillazine.org/Register_protocol

  • Protocols are registered in the appxmanifest for the project
  • On Windows, protocol registration is done by the operating system

Linux Related Notes

[Ubuntu] Using a custom protocol handler in Firefox to run a shell script?
http://askubuntu.com/questions/161553/using-a-custom-protocol-handler-in-firefox-to-run-a-shell-script

Make a link in the Android browser start up my app?
http://stackoverflow.com/questions/3469908/make-a-link-in-the-android-browser-start-up-my-app
- DO NOT use your own custom scheme

Launch custom android application from android browser
http://stackoverflow.com/questions/2958701/launch-custom-android-application-from-android-browser
- Per Google Engineer: Use an with a element.

Android Intents with Chrome
https://developers.google.com/chrome/mobile/docs/intents
- ...Android lets you launch apps directly from a web page via an Android Intent.
- ...an intent anchor and embed that into the page so the user can launch the app. Flexible approach...and the ability to pass extra information into the app via Intent Extras.

Intents and Intent Filters (see: Extras)
http://developer.android.com/guide/components/intents-filters.html#extras
- Key-value pairs that carry additional information required to accomplish the requested action. Just as some actions use particular kinds of data URIs, some actions also use particular extras
- ...add extra data with various putExtra() methods, each accepting two parameters: the key name and the value...create a Bundle object with all the extra data, then insert the Bundle in the Intent with putExtras()

How to launch external applications using custom protocols (rock:// instead of http://)
https://support.shotgunsoftware.com/entries/86754-How-to-launch-external-applications-using-custom-protocols-rock-instead-of-http-
- python example..
- see last line (beginning with @="\"python\")...call python...handler script
- also see: Registering a Protocol on Linux

Apple OS X References

Launching External Applications using Custom Protocols under OSX
https://support.shotgunsoftware.com/entries/127152

How do I configure custom URL handlers on OS X?
http://superuser.com/questions/548119/how-do-i-configure-custom-url-handlers-on-os-x


Misc. References

W3C HTML5
6.6 System state and capabilities
6.6.1.3 Custom scheme and content handlers
http://www.w3.org/TR/html5/webappapis.html#custom-handlers

http://blogs.msdn.com/b/ieinternals/

http://www.autohotkey.com/board/topic/71831-application-url-launch-local-application-from-browser/
- Application URL is a trick so that you can launch any application on your local computer from your browser
- Both Chromium and Google Chrome do not allow the browser or it's extensions to access local files, so you cannot create an extension that would call a program already on your machine
- In order for this to work, it requires you to add a new registry key to the Windows Registry to register a new URL Protocol.

Chrome doesn’t handle custom protocols correctly - (still ?)
http://superuser.com/questions/451350/chrome-doesnt-handle-custom-protocols-correctly
- see: This can be adjusted in Chrome's Local State file.

http://stackoverflow.com/questions/12471738/protocol-handler

http://stackoverflow.com/questions/2800081/how-to-run-an-external-program-e-g-notepad-using-hyperlink
- see JavaScript example...

http://stackoverflow.com/questions/10568345/why-is-my-applet-throwing-an-accesscontrolexception
- servlet based approach would have security issues...

No comments: