Custom Protocol Handling — How To

The best way to make your browser or website to run a local application!

The following article explains how to handle custom protocol in different operation systems and launching applications using custom browser protocols.

Introduction

As most of you already know, most of the operation systems today knows how to handle a call to a very specific list of protocols.

Examples,

• All operation system will automatically suggest your default browser for http or https protocols. there for, running https://<website-url> from your command prompt can even open your browser.
• Providing mailto://<some-address> URL will automatically opened you mail application.
• Providing callto://<phone-number> URL may open you caller application if you have one
• More pre-defined protocols can be found here

You can also define you own protocol handlers if you wish.
It’s one of the nicest way to make your browser to run a local application.

popup appears when calling custom URI (right-side)

Motivation

Enrich your environment with more protocols or ever replace current protocol with you own implementation can provide a lot of granularity to your products.
Image you are writing a parental control application and you wish to replace any http/https call with your own application as a proxy.
Or, imagine you would like to make sure an internal application is running in the background from you website.

If you asked “how can I run an exe file on my computer from html or javascript in your site” than here you will find the answer.

Windows

Windows OS stores its protocols in it registry, the registry structure look like this:

HKEY_CLASSES_ROOT 
  alert 
    (Default) = "URL:Alert Protocol" 
    URL Protocol = "" 
    DefaultIcon 
      (Default) = "alert.exe,1" 
    shell 
      open 
        command 
          (Default) = "C:\Program Files\Alert\alert.exe" "%1"

you can add your protocol following these instructions:

• Windows + R key (or Start menu + cmd prompt)
• Type regedit and click Enter.
• Search for HKEY_CLASSES_ROOT directory and follow the below to add your protocol
• Add directory name as you protocol name in HKEY_CLASSES_ROOT.
  (this is the protocol name later be used)
• Add an anonymous¹ entry typed REG_SZ with the title of your applications.
  (It will be shown in any popup of the browser, should be user friendly)
• Add an entry named URL Protocol typed REG_SZ without any value.
• Add directory named shell in you new protocol directory
• Add directory named open in the shell directory above
• Add and entry named command in the open directory above.
• Add an anonymous entry typed REG_SZ with the path of your application executable

Done!

Now you can open your browser and run your-protocol-name://<some parameters> and your application will immediately be executed.

Copy-Paste Example

Open Windows Shell (as administrator) and run these lines

reg add HKEY_CLASSES_ROOT\my-prot /t REG_SZ /d "My Description" /f
reg add HKEY_CLASSES_ROOT\my-prot /v "URL Protocol" /t REG_SZ /d "" /f
reg add HKEY_CLASSES_ROOT\my-prot\shell /f
reg add HKEY_CLASSES_ROOT\my-prot\shell\open /f
reg add HKEY_CLASSES_ROOT\my-prot\shell\open\command /t REG_SZ /d c:\Windows\notepad.exe /f

Run my-prot:// and see notepad is being opened.

Note: For more information regarding custom protocol you can refer here

Linux

Linux OS stores its protocols in a files/directory hierarchy over the disk, which looks like this:

~/.local/share/applications/<application-mime-file>.desktop
~/.local/share/applications/mimeapps.list

You can add your own protocol following these instructions:

• Create an empty properties file named <my-proc>.desktop under ~/.local/share/applications/ directory
• add the following text into you file, modify the names accordingly:

[Desktop Entry]
Name=<my-proc>
Exec=/path/to/application-binary %u
Type=Application
Terminal=true
MimeType=x-scheme-handler/<my-proc>;

• Open ~/.local/share/applications/mimeapps.list and add line under [Default Applications] sections with the following text:
  (If the section doesn’t exist add this line anyway)

x-scheme-handler/<my-proc>=<my-proc>.desktop

• From linux terminal run:

> update-desktop-database ~/.local/share/applications

Done!

Now you can open your browser and run your-protocol-name://<some parameters> and your application will immediately be executed.

Copy-Paste Example

Open one of you text editors and create a file named my-terminal.desktop in ~/.local/share/applications/ and paste this:

[Desktop Entry]
Name=my-terminal
Exec=bash
Type=Application
Terminal=true
MimeType=x-scheme-handler/my-terminal;

In linux’s terminal run:

> echo x-scheme-handler/my-terminal=my-terminal.desktop >> ~/.local/share/applications/mimeapps.list
> update-desktop-database ~/.local/share/applications

Provide this URL my-terminal:// to your browser and see linux’s terminal being opened.

Security Risks

As you’ve seen in the examples above, any browser or external application can run your registered application (handler) under custom protocol.

The registered application must handle the varied amount of data and verify the input is correct as it may get input from an un-trusted sources.

Make sure your application line / path to binary isn’t exposed to any command injections, example, customer can provide the following input as an argument:

abcde;format-disk

In this example, your application will have abcde as an input and your operation system may translate the above to another execution line named format-disk.

To summarize,

Using custom protocols handler is a very nice way to run applications from browser or website, its commonly used if you need an engine/server to be run locally on the host machine for your site.

Enjoy!

Please assist with sharing this article, share you gratitude by comment/applaud and feel free to share your note so we can approve the article.

¹ Anonymous entry is a registry entry with empty name