[Security] settings

Applies to the following products: 
Questionmark OnDemand
Questionmark Perception
Questionmark OnPremise
Applies to the following Perception versions: 
Perception 5.7
Perception 5.4
Perception 5.2
Perception 5.1

This section lets you define the security used when calling session.php via PIP.

The security is needed to make sure that the calling program is legitimately able to call the assessment. If you don't use these settings, then a user could call session.php directly themselves and bypass your security.

PIP security uses a special checksum that is added to an assessment URL. This checksum value combines the values of the PIP parameters and a hidden key using a hash algorithm. The algorithm is a complex arithmetic calculation that encrypts the values, preventing access to the hidden key and, therefore, preventing the creation of unauthorized URLs.

This hidden key is set in the PIP file and must be known by the program that is making the call. If the checksum is not calculated correctly, session.php will not run. You can also configure PIP so it can only be called from certain domains and/or IP addresses. If you configure it like this, you can further restrict the authorized devices that can launch assessments via PIP.

You define this security by setting the following parameters in the PIP file:

Setting Description Possible values

HOSTS

This setting restricts PIP calls to defined domains and/or IP addresses. If a request fails to match against any defined domains and/or IP addresses, an Access Denied message will be displayed. If no Hosts item is specified, no check will be done.

This setting can be given one or more of the following values:

  • An IP address with a wild card for the least significant byte. (eg 123.234.56.*)
  • A host name with a wild card for the domain host name (eg *.xyzcompany.com)
  • An IP Address
  • A host domain name (eg main.xyzcompany.com)
  • A combination of any of the above items delimited by spaces

If more than one item is specified, each item will be checked in the order given until a match is found or the end of the list is reached. The result of each check will be logged.

It's recommended you set this value, as it makes it much harder for someone to use a "rogue" program to access assessments by pretending to be an approved program.

Examples of the setup of Hosts within the PIP file follows:

[Security]

Hosts = 123.234.56.*

Hosts = *.xyzcompany.com

Hosts = main.xyzcompany.com 123.234.56.123 *.questionmark.com

LEVEL

The checksum means that the program calling session.php must perform some arithmetic on the parameters to work out a checksum. A hidden key is used which is set in the PIP file and must be known by the calling program. If the checksum is not calculated correctly, session.php will not run.

OnDemand/OnPremise/Perception 5.7

For OnDemand, OnPremise, and Perception 5.7, the recommended setting is:

LEVEL=hmacsha256

With this level of security, the checksum is calculated using the HMAC-SHA256 hashing algorithm. See the Calculating the checksum section below for information about how to calculate the checksum.

Backwards compatibility

For backwards compatibility, the following settings may be used:

LEVEL=2

With this level of security, the checksum should be calculated using the MD5 hashing algorithm. For OnDemand, OnPremise, and Perception 5.7, a checksum calculated using HMAC-SHA256 is also accepted with this security level.

No checksum

The following settings mean that no checksum will be used:

LEVEL=0

LEVEL=none

No setting in the PIP file for LEVEL

...when any of the above three settings that indicate no checksum will be used, assessments that are configured to "Run from Integration" can be launched from any program.

Perception 5.4

For Perception 5.4 and earlier versions, the recommended setting is:

LEVEL=md5

With this level of security, the checksum is calculated using the MD5 hashing algorithm. See the Calculating the checksum section below for information about how to calculate the checksum.

KEY

This is an optional text string that can be added to the data used for the security checksum. If this entry is present and is not blank, then the text must be added to any text used to calculate the checksum. It only applies when LEVEL is set to hmacsha256md5, or 2 for backwards compatibility.

If this value is set to %SERVER.KEY%, the value of the key will be taken from the Server Key setting on the Server Settings page (Administration > Server management > Server settings in OnDemand/OnPremise).

Calculating the checksum

When the security level is set to one of the values that requires use of a checksum, access will only be permitted to the assessment if the call is accompanied by an ACCESS parameter (or any parameter mapped to ACCESS in the [Input] section). The ACCESS parameter must contain a hexadecimal string representing the output (or 'digest') output by the hash algorithm.

HMAC-SHA256

For example, if your PIP file is called secure_test.pip and has LEVEL=hmacsha256 and KEY=sgvtyw7, then an example PIP call might look like the following:

http://www.xyzcompany.com/perception5/session.php?CALL=secure_test.pip& user_name=Steven&Lesson_id=4117626686784785&checksum=fa9df8748475c64712fb813f6358809fbde2839091d4ad7c3fb8bf6981bf2b03

The HMAC-SHA256 algorithm requires two [Input] parameters, a key and a string of characters representing the message. In the above example:

Key sgvtyw7 (taken from the Key setting in the PIP file referenced by CALL)
Message secure_test.pipSteven4117626686784785

Notice how the parameter values are added to the message in the same order as they appear in the URL and that parameter names are ignored. When parameter values contain characters that are escaped in the URL, the escape sequences must be removed before calculating the checksum. For example, a parameter like GROUP=R%26 Dwould contribute the characters R&D to the message string. Extra care is needed with the plus sign character (+) which, unless encoded itself, represents a space in the URL. Because of this, GROUP=Sales+and+Support in a URL would contribute the string Sales and Support to the message (including the space characters).

MD5

For example, if your PIP file is called md5pip_test.pip and has LEVEL=md5 and KEY=sgvtyw7, then an example PIP call might look like the following:

http://www.xyzcompany.com/perception5/session.php?CALL=md5pip_test.pip&user_name=Steven&Lesson_id=4117626686784785& checksum=931472062af794fdf7c73c62632d911d

Unlike HMAC-SHA256, the MD5 algorithm only requires a message parameter. This is calculated in the same way as the HMAC-SHA256 message but with the PIP Key value appeneded:

Message md5pip_test.pipSteven4117626686784785sgvtyw7

Verifying the checksum in PIP NOTIFY calls

The checksum may also be used in the [Callback] section and the [Output] section to validate the data being passed from PIP to the notify URL (specified in the [Settings] section) by setting an entry to have the value %CHECKSUM%. In this case, the receiving program will need to validate the checksum.

The method of verifying the checksum is the same as that of calculating the checksum (described above). The resulting checksum must match the corresponding value of the parameter mapped to %CHECKSUM%. If it doesn't match, then the URL is likely to have been generated by an unauthorized program and the receiving program must not act on the request.