User/Device Authorization

Submitted by Michael on #1

This functionality is only available when the VirtualHere server has been purchased

Scripting is now also supported on the VirtualHere Windows Server using batch files instead of bash scripts, the return codes are identical to the linux/osx values as described below

The ClientAuthorization script

VirtualHere supports user authorization whereby specific users can be granted/denied access to specific devices. This is useful for example to protect remote access to security dongles by certain users, or limit the number of shared devices per user.

Make sure the VirtualHere Server is not running, then add the clientAuthorization setting to the server configuration file. This setting specifies the bash script to run to perform authorization and passes it specific parameters replaced at runtime with actual values for the current user and the device they are attempting to use. The CLIENT_ID is passed in by the VirtualHere client to the server. It is automatically set to the same username used to login to the current operating system session under Windows / OSX / Linux. OR you can ask for the username by returning 3 from the clientAuthorization script

Once the config.ini file is changed and the server started, you can modify the authorization script at any time without restarting the server

  • $VENDOR_ID$ - The USB Device vendor id, in hex e.g "05ac"
  • $PRODUCT_ID$ - The USB Device product id in hex hex e.g "12a4"
  • $CLIENT_ID$ - The format is <full name><space><open bracket><username><close bracket> .eg "John Smith (jsmith)"
  • $CLIENT_IP$ - e.g "192.168.2.60"
  • $CLIENT_HOSTNAME$ - e.g "WIN10-DEVELOP"
  • $PRODUCT_SERIAL$ - This is the USB Device serial number e.g "2c89237021"
  • $PASSWORD$ - This setting is optional and is the password entered by the user when attempting to use the device. The password is encoded as an MD5 hash value
  • $DEVPATH$ - The device path on the server e.g /sys/bus/usb/devices/1-1
  • $NICKNAME$ - The nickname of the device (if set)
  • $NUM_BINDINGS$ - the number of devices this user is currently using.

Example 1 : Linux Example

For example, the following setting specifies the bash script auth.sh to perform authorization and passes it 9 runtime parameters (all on one line)

clientAuthorization=/home/root/auth.sh "$VENDOR_ID$" "$PRODUCT_ID$" "$CLIENT_ID$" "$CLIENT_IP$" "$PRODUCT_SERIAL$" "$PASSWORD$" "$DEVPATH$" "$NICKNAME$" "$NUM_BINDINGS$"

Create a new file called auth.sh in the directory specified in the line above (e.g /home/root) and add the following example code (This code will deny access to everyone except the username "michael" with a password "mypassword"). Change it to suit your needs.

#!/bin/bash
# Example script for performing basic user authorization for virtualhere
# Also includes a simple password protection mechanism for accessing a device
# Return 3 if the user needs to provide a username AND password (or the password is incorrect) to use the device
# Return 2 if the user needs to provide ONLY a password (or the password is incorrect) to use the device. The username defaults to the client OS username
# Return 1 if the user is allowed to access this device
# Return 0 if the user is not allowed to access this device
# Parameters are passed in as:
# $1 = VENDOR_ID
# $2 = PRODUCT_ID
# $3 = CLIENT_ID
# $4 = CLIENT_IP
# $5 = PRODUCT_SERIAL
# $6 = PASSWORD
# $7 = DEVPATH
# $8 = NICKNAME
# $9 = NUM_BINDINGS
logger "Authorizing -> '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$9'"
# "mypassword" = "34819d7beeabb9260a5c854bc85b3e44" as an MD5 hash
if [ "$6" == "34819d7beeabb9260a5c854bc85b3e44" ]; then
echo "Password ok"
else
exit 2
fi
if [[ "$3" == *"(michael)"* ]]; then
logger "Authorized!"
exit 1
else
logger "NOT authorized"
exit 0
fi

Save the file and give it execute permissions chmod +x /home/root/auth.sh

Now when you start the server it will call this script every time a client attempts to Use a device. You can use the other parameters passed in to perform more specific authorization, for example using the device product ID or client IP or password based on the type of device and so forth.

Example 2 : Windows Example

Here is a example script that performs the same function as the Linux script above. Change the username from michael to your username. Try using a device first, let it fail and look in the log.txt file for all the details you can compare on.

Put this line into the config.ini after you have stopped and exited the VirtualHere Windows server (change path to where you will put the auth.bat file)

clientAuthorization=C:/Users/michael/auth.bat "$VENDOR_ID$" "$PRODUCT_ID$" "$CLIENT_ID$" "$CLIENT_IP$" "$PRODUCT_SERIAL$" "$PASSWORD$" "$DEVPATH$" "$NICKNAME$" "$NUM_BINDINGS$"

Then put this in the auth.bat file:

@echo off
rem Example script for performing basic user authorization for virtualhere in windows
rem Also includes a simple password protection mechanism for accessing a device
rem Return 3 if the user needs to provide a username AND password (or the password is incorrect) to use the device
rem Return 2 if the user needs to provide only a password (or the password is incorrect) to use the device
rem Return 1 if the user is allowed to access this device
rem Return 0 if the user is not allowed to access this device
rem Parameters are passed in as:
rem %1 = VENDOR_ID
rem %2 = PRODUCT_ID
rem %3 = CLIENT_ID
rem %4 = CLIENT_IP
rem %5 = PRODUCT_SERIAL
rem %6 = PASSWORD
rem %7 = DEVPATH
rem %8 = NICKNAME
rem %9 = NUM_BINDINGS
rem for help debugging this script, look in the file log.txt to see the arguments passed in
rem and the result of the IF statements below
echo %1 > log.txt
echo %2 >> log.txt
echo %3 >> log.txt
echo %4 >> log.txt
echo %5 >> log.txt
echo %6 >> log.txt
echo %7 >> log.txt
echo %8 >> log.txt
echo %9 >> log.txt
rem "mypassword" = "34819d7beeabb9260a5c854bc85b3e44" as an MD5 hash
rem go here https://passwordsgenerator.net/md5-hash-generator to determine the MD5 hash for the password you want to use
IF %6=="34819d7beeabb9260a5c854bc85b3e44" (
  echo "Password ok" >> log.txt
) ELSE (
  echo "Password invalid" >> log.txt
  exit 2
)
ECHO %3 | FIND "(michael)" >Nul
if errorlevel 1 (
  echo "NOT authorized" >> log.txt
  EXIT 0
) ELSE (
  echo "Authorized!" >> log.txt
  exit 1
)

Example 3 : A more complicated Linux Example

Thanks to user ben at wildblue de, here is an advanced configuration script with logging and detailed authentication

Example 4: An example of generating a unique daily password for device access (Thanks to user phassmann!)

1. Put this on a webpage the user visits first (Note for myowncryptcode replace that with a made up secret key)

<?php
$d = date("Ymd")."myowncryptcode";
echo "Password is: ".crc32($d);
?>

2. Put this in the auth.sh script on the server

#!/bin/sh
logger "Authorizing -> '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$9'"
		code=myowncryptcode
		checksum="$(date '+%Y%m%d')${code}"
		crc="$(echo -n "$checksum" | gzip -c | tail -c8 | hexdump -n4 -e '"%u"')"
		hash="$(echo -n "$crc" | md5sum )"
		pass="${hash%%??}"
#Set a password if a special device used by VendorID
#if [ $1 = "0529" ]
#	then
#		pass="f09730023eacbc6e5f1827db89fca2db"
#	fi
#AutoLogin by Username
#if [ $3 = "(Patrick)" ]
#	then
#				exit 1
#	fi
#Autologin by IP
#if [ $4 = "84.187.157.22" ]
#	then
#				exit 1
#	fi
if [ $6 = $pass ]
	then 
		exit 1
		echo "Entered Pass ok:	$6"
		echo "Login ok!"
	else
		exit 2
		echo "Entered Pass failure:	$6"
	fi

The ClientDeauthorization script

The ClientDeauthorization setting is identical to the ClientAuthorization script but is called when a user disconnects from a device. The parameters sent to the script are identical to the ClientAuthorization script except the script is not required to return a value of 1 or 0. Using both the ClientAuthorization and ClientDeauthorization script makes it easy to track user-device usage e.g for logging and accounting purposes.

The OnDeviceKick script

When a client runs in adminstrator mode (using the -a argument when starting the client) the administrator can kick another user off a device by right clicking on the in-use device and selecting "Disconnect from User". If you would like to restrict which administrators can kick which users of which devices you can use the OnDeviceKick setting in the server config.ini file to specify a script to run to determine the action to be taken. This script is similar to the scripts above but should return 1 if the user can be kicked from the device and 0 otherwise.

For example, the following setting specifies the bash script onDeviceKick.sh and passes it 8 runtime parameters (all on one line)

onDeviceKick=/home/root/onDeviceKick.sh "$VENDOR_ID$" "$PRODUCT_ID$" "$KICKER_ID$" "$KICKER_IP$" "$CLIENT_ID$" "$CLIENT_IP$" "$PRODUCT_SERIAL$" "$DEVPATH$" "$NICKNAME$"

Create a new file called onDeviceKick.sh in the directory specified in the line above (e.g /home/root) and add the following example code (This code will deny administrator kicking abilities to everyone except the username "michael"). Change it to suit your needs.

#!/bin/bash
# Example script for controlling who can kick off a user from a device,
# this script blocks all administrators from kicking except for michael
# Return 1 if the user can be kicked off the in-use device
# Return 0 if the user can NOT be kicked off an in-use device
# Parameters are passed in as:
# $1 = VENDOR_ID
# $2 = PRODUCT_ID
# $3 = KICKER_ID
# $4 = KICKER_IP
# $5 = CLIENT_ID
# $6 = CLIENT_IP
# $7 = PRODUCT_SERIAL
# $8 = DEVPATH
# $9 = NICKNAME
logger "OnDeviceKick -> '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$9'"
f [[ "$3" == *"(michael)"* ]]; then
logger "OK"
exit 1
else
logger "No"
exit 0
fi

Save the file and give it execute permissions chmod +x /home/root/onDeviceKick.sh

Now when you start the server it will call this script every time an administrator attempts to Disconnect from User a device. You can use the other parameters passed in to perform more specific qualification, for example using the device product ID or client IP and so forth.