11.1. Custom Authentication Module

MetaDefender Kiosk allows you to audit the users that transfer data to and from the organization as well as to create a secure dataflow. Commonly used as a checkpoint to protect infrastructure from the risk of removable media devices (such as USB drives, CDs/DVDs, and other portable media), MetaDefender Kiosk allows you to configure detailed content filters for unknown removable devices brought in by employees, contractors, vendors and others.

This section provides instructions for developers who intend to build or integrate their own authentication method of these users into MetaDefender Kiosk. We recommend that you have a strong understanding of C/C++ before reading this section.

The bundled code included in this section is a sample of how the authentication module can be implemented. You should modify the contents in each method described in this section to accommodate your integration needs. You can remove any additional methods in the sample code not described in this section if not needed.

Important: Any configuration pertaining to the custom authentication module are not saved if you uninstall and re-install MetaDefender Kiosk. You must keep a copy of your module before uninstalling and then copy it back to the same directory once your installation or upgrade is complete.

System requirements

The system requirements for implementing custom authentication are as follows:

  • MetaDefender Kiosk 3.2.0 or later

  • Visual Studio 2013 or later

  • NET 4.5 or later for running the Custom Authentication Sample for the sample UI

Deploying and configuring custom authentication

The steps necessary to deploy custom authentication are as follows:

  1. Obtain a custom authentication template package from the OPSWAT Portal downloads.
    Note: Use the template for C++ custom authentication module (vc12).

  2. Implement the custom authentication interface & build the custom authentication module (authenticationModule.dll).

  3. Deploy the custom authentication module.

  4. Configure MetaDefender Kiosk to load and use the custom authentication.

Configuring custom authentication

After successfully building the custom authentication module, you can configure the custom authentication module.

  1. Place the module (authenticationModule.dll) in the expected directory (e.g. <MetaDefender Kiosk Install Directory>\Client\Authentication).

  2. Open the MetaDefender Kiosk Management Console, and go to the Workflows tab.

  3. Go to the Configuration section.

  4. Select Require user authentication, then select Custom Authentication, and click Apply .
    Note: If Custom Authentication does not appear, the authentication module is either named incorrectly or not in the expected directory.

images/download/attachments/31071384/custom_auth_setting.png

Understanding C++ code in the custom authentication template

The following section describes the C++ code in the custom authentication template.

Init

This is the first method called. It allows you to initialize your authentication module.

init

Arguments

Argument

Description

showUI

Output indicates if the authentication module has a UI to display to the user.

  • True: Has a UI.

  • False: Has no UI.

Return value

Value

Description

0

The module initialized correctly.

Non-zero

Initialization failed and the module cannot be used.

Verify

This method initiates the authentication process to run. The return value has nothing to do with if the user is authenticated or not. Instead, it indicates if the authentication process was successful or not.

init

Arguments

Argument

Description

Notes

verifiedID

The ID associated with the user that successfully authenticated. If a user is denied, then this is empty.

Implementer must allocate the memory required.

desktopName

MetaDefender Kiosk uses a second desktop for security reasons. If your authentication process has a UI to display to the user, this will indicate the desktop in which your authentication process will be launched.

Disregard if your authentication process does not require a UI.

password

The verified user’s credentials which allows MetaDefender Kiosk to handle post processing permissions. If you don't want MetaDefender Kiosk to have the user’s permissions, leave this empty.

Implementer must allocate the memory required.

Note: From 3.5.0, if verifiedID is empty, Guest profile will be used.

Return value

Value

Description

0

Verification ran successfully.

Non-zero

Verification failed to run.

Denit

This method is called when MetaDefender Kiosk is shut down. Any resources acquired by your module should be released and any unsaved data should be stored.

init

Arguments

No arguments are required for this function.

Cancel

This method is called when the user tries to cancels while verification is running.

int Cancel
(
)

Arguments

No arguments are required for this function.

Return value

Value

Description

0

The cancel request was accepted.

Non-zero

The cancel request was denied.

FreeString

This method is called to free allocated memory for wchar_t **. MetaDefender Kiosk calls this function when finished with the values allocated by your functionality.

init

Arguments

Argument

Description

Notes

stringToFree

Double pointer to wchar_t

This function must be de-allocated in the same way that memory is allocated.

Return value

Value

Description

0

The allocated memory was successfully released.

Non-zero

The allocated memory failed to be released.

Using the custom authentication tester

The custom authentication testing package includes a file called TestCustomAuthentication.exe that lets you test and troubleshoot your authentication module before using it with MetaDefender Kiosk.

TestCustomAuthentication.exe behaves similarly to the component MetaDefender Kiosk uses to load the authentication module. Since MetaDefender Kiosk runs under a SYSTEM context, you should run the authentication module under SYSTEM as well. Attempting to run the authentication module under any other user may invalidate the module's results. You must run TestCustomAuthenticationModule.exe under SYSTEM to properly load authenticationModule.dll and test the methods.

You can use Windows Sysinternals to run the tool as SYSTEM.

To run the custom authentication tester:

  1. Download PsExec.

  2. Open a command prompt (as an administrator) to where PsExec is installed and enter "PsExec.exe -s cmd.exe"

    images/download/attachments/31071384/image021.jpg

  3. Navigate to the <MetaDefender Kiosk Install Directory>\Client\Authentication directory.

  4. Run TestCustomAuthentication.exe. At all points of method testing, the tester pauses and allows you to control when to move on to the next test.

  5. A PASSED or FAILED result appears.

    images/download/attachments/31071384/image024.jpg