Problems
Widgets - Security

Sphere Engine Problems Widget provides mechanisms for secure integration. A fully secured widget can be embedded only on selected websites (i.e., on websites in an appropriate domain) and the communication between the client's system and the Sphere Engine system is fully reliable (i.e., unauthorized people are unable to falsify or fabricate communication).

Checking the source

Using a list of defined web addresses on which a widget can be embedded as a security measure minimizes the risk of unauthorized use of the widget. It is a method that's the simplest and the fastest to configure. It doesn't require any additional mechanisms. It is recommended to use the signature mechanism to ensure full protection of the widget.

You can define the list of allowed addresses on the Menu > Problems > Widgets > WIDGET NAME > Widget settings page in the Sphere Engine client panel. In the Allow the widget to be used only at the following addresses configuration field, you can specify one or multiple addresses, for example:

yoursite.com
yoursite.com/some/path
your-other-site.com
http://yoursite.com
https://yoursite.com

The Sphere Engine system verifies HTTP requests from end-users using the client's system (i.e., the page where the widget is embedded). Only requests directed to addresses in the list of defined addresses are accepted.

Signature

In a production environment, we recommend using the signature security measure that fully protects the widget from unauthorized use. The signature verification feature must be enabled in advance by selecting the Secure the widget option in Sphere Engine client panel: Menu > Problems > Widgets > WIDGET NAME > Widget settings.

The use of a signature for communication between the client's system and the Sphere Engine system increases the overall security level. It eliminates the possibility of unauthorized access to the widget (preventing even complex and difficult attempts at acquiring access by preparing fake HTTP requests) and guarantees the reliability of transmitted data.

Signature parameters

Signature generation is based on selected widget parameters and additional signature parameters:

• hash - unique widget ID in the Sphere Engine system. It can be found in the Unique hash field in Sphere Engine client panel: Menu > Compilers > Problems > WIDGET NAME > Widget settings,
• se_secret - secret key which is the basis for the security of the signature. It can be found in th Shared secret field in Sphere Engine client panel: Menu > Problems > Widgets > WIDGET NAME > Widget settings,
• se_user_id (optional) - unique (for a given widget) ID of the end-user of the widget (i.e., the person solving the task),
• se_nonce (optional) - unique session ID for a given widget.

Signature generation algorithm

The signature generation procedure can be divided into the following steps:

• Normalization by sorting parameter names in alphabetical order. For example:
  [hash, se_user_id, se_secret, se_nonce] ➡ [hash, se_nonce, se_secret, se_user_id],
• Conjunction by saving the parameters and their values ​​in the form of a string with the following format:
  param1=value1&param2=value2&...&paramN=valueN
  for example:
  hash=XYZ&se_nonce=12345&se_secret=CIPHER&se_user_id=bradpitt,
• Encoding to the application/x-www-form-urlencoded format using UTF-8 encoding,
• Hashing using the SHA-256 algorithm which is available for the majority of popular programming languages ​​(in the standard library or as part of an additional library).

Pseudocode of the algorithm that generates the signature

generate_signature(params) {
    // Normalization
    params = sort(params);

    // Conjunction with Encoding
    seq = [];
    foreach p in params {
        seq += key(p) + "=" + urlencode(value(p), "utf-8"); 
    }

    // Hashing
    return sha256(join("&", seq));
}

Implementation of the algorithm that generates the signature in PHP

function generate_signature($params) {
    ksort($params);

    $seq = [];
    foreach ($params as $k => $v) {
        $seq[] = $k . "=" . urlencode($v);
    }

    return hash("sha256", implode("&", $seq));
}

Implementation of the algorithm that generates the signature in Python

def generate_signature(params):
    keys = sorted(params.keys())

    seq = []
    for k in keys :
        seq.append(k + "=" + urllib.parse.quote_plus(params[k]))

    return hashlib.sha256("&".join(seq).encode('utf-8')).hexdigest()

Attaching a signature

The signature and the values ​​of all parameters used to generate it (except the se_secret parameter which should remain secret) should be attached to the embedded widget in the form of the appropriate HTML attributes with the data- prefix:

• data-widget for the hash parameter,
• data-user-id for the se_user_id parameter,
• data-nonce for the se_nonce parameter,
• date-signature for the signature.

An example of HTML code used to embed a widget prepared to support the signature

<div class="se-widget"
    data-id="widget-secured-by-signature"
    data-widget="XYZ"
    data-signature="e85b12137f76526ca6804625fc4e2093a0750fc6c6c158fc2be210ac5"
    data-user-id="bradpitt"
    data-nonce="e9838cc0819d713b3670df7adb0079a3">
</div>

The sender uses the selected parameters of the message (or even the entire message) along with the key when creating the signature. The generated signature is attached to the message and sent to the recipient.

The recipient, who also has access to the key, repeats the procedure of creating the signature. The received message is authorized, if the signature sent by the sender is identical to the signature generated by the recipient.