Configuring Phone Password Manager

In order for Phone Password Manager to use questions and answers from Bravura Pass to authenticate users, the following conditions must be met:

Using the default question set

Bravura Pass is shipped with a pre-defined question set, DEFAULT_PREDEFQSET, that contains three questions that can be used for Phone Password Manager authentication:

Adding question sets

If you do not want to use the default question set (DEFAULT_PREDEFQSET) for touch-tone authentication, or if you want to strengthen the authentication process, you can add more Phone Password Manager specific question sets.

To do this:

Add questions

In order for a question to be suitable for touch-tone authentication, it must have the following characteristics:

If you are defining a new question for which a sound file does not exist by default, the question’s Description field must be formatted as: DEFAULT_PREDEFQSET_<QID> . This formatting is mandatory in order to associate a new question to it’s respective sound file.

The QID defined in the description field is used to uniquely address the sound files on the IVR, and should be unique to every custom question you wish to define.

See Adding custom authentication questions for more information on defining custom Phone Password Manager authentication questions.

Record question vocals for new questions

When users call into the Phone Password Manager, the system plays vocals (sound files) that prompt the users to prove their identities by keying in numerical answers to the questions that they have configured in Bravura Pass .

Phone Password Manager is shipped with vocals for each numeric question in the default pre-defined question set (DEFAULT_QSET). If you have added additional questions for touch-tone authentication you must record a vocal for each new question, in each supported language.

Vocal files must be named QD-PREDEFINED_<QID>.wav, and must be located in the <instance>\audio\<lang>-<locale> directory on the Phone Password Manager server. Note that the value of:

See Managing audio files for more information on Phone Password Manager audio files.

To set up voice print enrollment:

Phone Password Manager is now configured and ready for users to enroll via a PIN.

The tone of your voice varies each time you authenticate against your voice print. If your voice sounds too different from your voice print, Bravura Pass might not be able to properly authenticate you.

The following options, located in idtel.cfg or tpm.cfg, help you configure the sensitivity thresholds, and the recording time for voice print authentication.

If you change the values of these options in idtel.cfg, then you must restart the Phone Password Manager service.

To test voice print enrollment:

See also

Registering a Voice Print for Authentication via Phone in the end user documentation.

Use the vpcmd program, installed with Phone Password Manager, to test the generation or verification of voice print audio files.

View vpcmd usage information .

The vputil program is installed with Phone Password Manager and helps to clean the voice print database by removing enrollment data for users who do not have a valid Bravura Pass profile.

View vputil usage information .

The Speech Service can be configured using the following options, which are located in the idtel.cfg file:

Use the voicebuild program to create audio .wav files based on a vocal script .txt file using SAPI.

View voicebuild usage information .

Auto-answer mode is the default mode. IVR calls are answered by default, call logic scripts run and audio plays according to the scripts.

Inbound mode is similar to auto-answer mode, but instead of calls being answered by default, calls are only answered if the PSLang function "setHookOff" is triggered. This allows calls to be answered selectively.

The "setHookOff" PSLang function for this call mode is specified in the psynch.psl script .

In this example, the inbound call is answered if the callerID is "123":

if ( $callerID == "123" )
{
  setHookOff();
}

The callerID is one of several global variables that contain information about the current call. See Writing call logic scripts for details on call logic global variables.

Outbound mode allows the IVR system to make outbound calls, and is configured in the psynch.psl script. When this is configured, the IVR system can forward the call to another phone number. Once the call is received, it proceeds according to the call logic scripts.

The phone number to which the calls are forwarded is specified in the psynch.psl script .

For example:

for( var $i = 0; $i < 30; $i++ )
  {
  sleep( 1000 );
  }
$ret = MakeCall( "9,403-2737373", 30, $errbuf );
log( "MakeCall returned: " + $ret + ", error: " + $errbuf );

In order for outbound mode to function, idtel.cfg must be modified as follows:

Before the function "TransferCall" can be added to Phone Password Manager to support call transfers, you must complete the following configuration:

Next:

To configure Phone Password Manager to use the SIP protocol:

Add the following script into psynch.psl :

if( $digits == "<telephone number|extension number>" ) 
  { 
    $ret = TransferCall( "<Telephone Password Manager server address>", $errbuf ); 
    log( "TransferCall returned: " + $ret + ", error: " + $errbuf ); 
    return 1; 
  }

To test the configuration:

To configure Phone Password Manager to use the H323 protocol:

Add the following script into psynch.psl script:

if( $digits == "<telephone number|extension number>" ) 
  { 
    $ret = TransferCall( "TA:<Telephone Password Manager server address>", $errbuf ); 
    log( "TransferCall returned: " + $ret + ", error: " + $errbuf ); 
    return 1; 
  }

To test the configuration:

Before the bridge transfer function can be added to Phone Password Manager, you must change the ipDTMFmode setting in idtel.cfg:

ipDTMFmode = 6

This enables the DTMF key after a connection has been established.

If you are using a softphone, then you must:

Next:

Configure bridge transfers .

If you are configuring the bridge-demo2.psl script, then you must specify the help desk number as follows:

var $HelpDeskNumber = "SIP:<Server IP>";

Where <Server IP> is the IP address for the outbound call to the help desk user. This address should connect to the softphone which can receive a call from Phone Password Manager.

Modify the idtel.cfg file as follows:

You can record a call that has been transferred to the help desk by a bridge transfer. This function is controlled by the recorder-demo.psl script, which is located in the samples directory. The recorded call produces a wav file.

This script is provided to help test the bridge transfer function .

Both sides of a call (caller and automated voice) are recorded. However, it is possible to write a script to record the callers on two different lines. The "RecordFileEx" function has the ability to record two time slots simultaneously.

To configure call recording, you must modify idtel.cfg to assign an outbound mode channel for recorder-demo.psl and to start the recording. It is recommended that you do so under guidance from Bravura Security staff.

Optionally, you can configure the bridge transfer script to play on-hold music or other programming while a user is waiting in queue. See bridge-demo1.psl or bridge-demo2.psl for details.

To view the logs for the unlock operation:

See full details on the Event log report .

To view the logs for the reset operation:

See full details on the Self service password changes report .

If you run into problems with your voice board:

If Phone Password Manager is having problems with hangup events on a digital network system, and you have correctly completed all configuration steps outlined in this manual, then there is probably a misconfiguration on the Dialogic card. This problem should not happen on digital network systems. If it is happening, contact the support department of your Dialogic hardware supply company, or purchase support services from a third-party company.

If Phone Password Manager is having problems with hangup events, and the Dialogic card is connected with analog CO lines or analog PBX lines:

If you hear dead air instead of the welcome message, then upgrade to the latest Dialogic System Release Software Updates. This issue can also be caused by improper audio file configuration.

If no sound is played to users who connect, or there are certain menu options for which the sound files are not being played, it is possible that your audio file configuration is incorrect. Phone Password Manager organizes audio files in the following directory structure:

<Instance>\audio\

If this directory structure is disturbed, or any of the audio files themselves are missing, then the system will not be able to locate those files for playback to the user. This error can be easily diagnosed by reviewing the system logs, which will include a message such as:

Warning: Cannot open C:\Program Files (x86)\Bravura Security\Telephone Password Manager\<instance>\audio\en-us\<filename>.wav, errno: 2

This error indicates that Phone Password Manager was unable to locate the audio files in their usual directory.

Asterisk® audio files

When using an Asterisk® server, Phone Password Manager needs to upload the locally-stored audio files onto the Asterisk® server. Phone Password Manager will only initiate this file synchronization if it cannot find the following directory on the Asterisk® server:

\var\lib\asterisk\sounds\HiTPM\

To force Phone Password Manager to update the Asterisk® server’s audio files: delete the directory listed above, restart the Phone Password Manager service, and place a call to the IVR.

In the system services menu, you should see:

If the Phone Password Manager Service fails to start:

If Phone Password Manager cannot return requests properly due to slow network speeds, then you can modify the "SoapTimeout" registry key:

HKLM\SOFTWARE\Bravura Security\Bravura Security Fabric\<instance>\\Idapi\

Modify the "SoapTimeout" registry key by increasing the value. The default setting for this value is 60000 milliseconds, which is one minute.

If Phone Password Manager cannot connect to the softphone system, try switching audio codecs in idtel.cfg . The codec in Phone Password Manager must match the supported codecs of your softphone system.

If Phone Password Manager fails unexpectedly, it is possible the Dialogic license is expired or invalid. You may see an error message like the following:

2013-01-15 07:54:59.532.2056 - [] idvoip.exe [3292,3180] Warning: gc_Start,
GC ErrorValue: 0x8c - The start procedure of a call control library failed,
CCLibID: 0 - GLOBALCALL, CC ErrorValue: 0x8c - The start procedure of a
call control library failed
2013-01-15 07:54:59.532.2093 - [] idvoip.exe [3292,3180] Debug: Failed to
initialize GlobalCall Libraries
2013-01-15 07:54:59.532.3090 - [] idvoip.exe [3292,3180] Error: Failed to
InitGC, service terminated

To resolve this, update the Dialogic license, then restart the Phone Password Manager service. See the Dialogic documentation for details on updating a license.

Phone Password Manager is fully functional with newer versions of the SoX utility, however Phone Password Manager expects SoX versions equal to or earlier than those shipped with Asterisk® when checking for the existence of a SoX installation. This version mismatch can impede the installation and function of Phone Password Manager with Asterisk.

To resolve this issue, log into the Asterisk® server as root, or escalate to root. Execute the following commands in the Unix terminal, in order:

cp 'which sox' 'which sox'2
echo '#!/bin/bash' > 'which sox'
echo '[ "$1" = "--version" ] && echo "sox: Version 0.0.0" || sox2 $*' >> 'which sox'

This change will reconfigure how SoX responds when asked to display its version, allowing Phone Password Manager to install with newer versions of SoX.

An issue in trying to follow the logged events from the scripts, common to other PSLang usage in Bravura Security Fabric , such as ssh/telnet/cmd/ps expect scripts, is that PSLang logs the line in the script that records the log entry, but not the file.The filename can theoretically be added in file-specific interpreted log functions that wrap the built-in (compiled) log function, but that has not been done in samples shipped with Bravura Security Fabric .

From the compiled PSLang functions, the emitted SOAP API calls have to reach the SOAP endpoints provided by idapisoap on the Bravura Security Fabric server.

Increasing tpm.exe's logging to Verbose (99 ), logs both the outgoing API calls and the returning answers (the entire SOAP XML of the call/response with some sensitive fields starr(*)ed out for privacy). At that point the troubleshooting moves over to the Bravura Security Fabric server's idapisoap and idapi services.

Log analysis

Bad Phone Password Manager config file

In the Phone Password Manager server's idmsuite.log, after you start the Telephone Password Manager service, there should be no logged entries containing:

Can not parse config file

If there are such entries, the line mention is malformed and has to be fixed.

Usually, the error location (file, line and position in the config file, as well as what is missing or found more than expected), are mentioned on the logged entry.

Bad API password

On the Phone Password Manager server you can see entries such as:

2023-12-14 10:19:44.533.2542 - [] idvoip.exe [4144,4468] Warning: Failed to LocalLogin, sessdat has not been updated

That means that the password is misconfigured in Phone Password Manager's service\pushpass.cfg

At the same time, on the Bravura Pass server that receives the API login operation, you will see entries like:

2023-12-14 10:19:57.201.2003 - [] idapi.exe [7120,7664] Warning: Login failed:
   
 invalid password specified for [_API_USER_TPM].

To fix that:

Network Address Translation (NAT) has been always a problem for Session Initiation Protocol (SIP).

Most problems are caused by the peer side (user side) network.

Make sure the SIP client software supports STUN & UPnP protocol.

Also make sure the UDP port 5060 - 5080 and 10000 - 20000 are allowed on both sides of network.

When SOAP API commands fail to be sent to the Bravura Pass instance, or if the Bravura Pass instance logs some error or warning, you'll find them in a default Phone Password Manager logging like this, from the Phone Password Manager service (idvoip):

2023-12-14 10:19:44.533.2542 - [] idvoip.exe [4144,4468] Warning: Failed to LocalLogin, sessdat has not been updated

or:

2023-12-05 10:21:33.914.5137 - [] idvoip.exe [8508,9016] Warning: Error [Can not parse
      config file [D:\Program Files\Bravura Security\Telephone Password Manager\hidpwm\service\pspushpass.cfg]. Error [[Line: 30, Pos:
      3]: Parse error: expected ';'].]

Warnings such as the following are expected and can be ignored, if the unavailable functionality is not used in the affected implementation.

2023-12-12 09:46:01.439.3620 - [] idvoip.exe [1288,7272] Warning: Failed to load library
      [VC_Database.dll].  Error [126]
   
_2023-12-12 09:46:01.439.3635 - [] idvoip.exe [1288,7272] Info: Voice print functionality
      disabled

On the Bravura Pass server, from idapisoap.exe or idapi.exe , for example:

2023-12-14 10:19:57.201.2003 - [] idapi.exe [7120,7664] Warning: Login failed: invalid password specified for [_API_USER_TPM].

On the Phone Password Manager side, increase logging to Debug level , to see both the SOAP outgoing message (SND) and the SOAP message Bravura Pass sends back (RCV), for example:

2023-11-15 11:08:29.384.7518 - [] idvoip.exe [4596,6852] Verbose: SND:<?xml version="1.0"
      encoding="UTF-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><Login
      xmlns="http://www.hitachi-id.com/idapi"><request xmlns:a="http://schemas.datacontract.org/2004/07/idapi" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><a:sessdat></a:sessdat><a:userid>_API_USER_TPM</a:userid><a:password>***</a:password><a:isadmin>1</a:isadmin><a:options></a:options></request></Login></s:Body></s:Envelope>
   

For a successful login, a sessdata item will be returned (RCVed), as well as a Success message and a "0"(zero) value for the returncode of the operation:

_2023-11-15 11:08:29.384.7546 - [] idvoip.exe [4596,6852] Verbose: RCV:<s:Envelope
      xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><LoginResponse xmlns="http://www.hitachi-id.com/idapi"><LoginResult><errmsg xmlns="http://schemas.datacontract.org/2004/07/idapi">Success</errmsg><rc xmlns="http://schemas.datacontract.org/2004/07/idapi">0</rc><sessdat xmlns="http://schemas.datacontract.org/2004/07/idapi">73bb9a4b-46bb-4944-8d64-7f53ee87e55b</sessdat></LoginResult></LoginResponse></s:Body></s:Envelope>

Note that:

If you want to test the SND operations, Bravura Security recommends using a SOAP client such as SoapUI or postman. For a complete connection test, such SOAP clients have to be run from the Phone Password Manager server.

If company policy doesn't allow installing such clients for testing, you could try using Powershell instead:

If the correct password for the used API profile was successfully tested with idapitool , yet Phone Password Manager itself fails to Login into Bravura Pass with the same encrypted password, there's likely a difference in encryption keys between the Bravura Pass and Phone Password Manager instance. Use the same encryption keys on both servers, and the same product version of Phone Password Manager and Bravura Pass .