⬅ ︎Back

Security Preamble

World-Check One deals with sensitive customer/supplier data in its role as a Know Your Customer/Anti-Money Laundering compliance tool. Security of this information is therefore paramount, for which LSEG employs a variety of mechanisms to ensure data is kept private, and is only accessible by authorised parties. This document details all the information security mechanisms currently employed.

Data in transit

The World-Check One API is exposed as a REST/JSON web service. Request and response messages are sent as plain text, encrypted over the wire via HTTPS.

Authentication, authorization and message integrity

A World-Check One API user will be assigned two access tokens: an API key, and a symmetric secret key known only by the API user and the LSEG World-Check One system. These keys are generated by World-Check One and made available to World-Check One administrators via the user administration interface.

All requests made by an API user to the World-Check One API service need to include the user’s API key, as well as be signed with a message authentication code (MAC). Specifically, this is expected to be a keyed-hash message authentication code (HMAC), which is calculated using a combination of the request message contents and the API user’s secret key. Detailed information on how to generate an appropriate HMAC are included below.

A request’s HMAC is used for two main purposes:

  • to verify the integrity of the request’s contents

  • to verify the identity of the requesting API user corresponding to the given API key.

Messages are further validated by timestamps, to help guard against replay attacks. Messages are only considered valid if they are processed at the point in time corresponding to their Date request header. A small buffer is used in this calculation to allow for minor clock drifts, discrepancies between client and server clocks, and data transfer round trip times. It is advised that when integrating with the World-Check One API, the machines involved in API communication are properly time synchronised via NTP to help prevent any message validity issues.

Once a request has been successfully verified for a particular user, the operation is further authorised in the same manner as any other operation within the World-Check One system. This means API users are only able to access and operate on data that is visible to them, based on their group and role assignments. This authorisation process is identical for API users and users accessing the World-Check One web application.

The following image is a high-level overview of the information flows involved with the World-Check One API.

World-Check One API information flow
Figure 1. Security of information flows within the World-Check One API

Message Authentication Code overview

An API user’s secret key is used to produce a HMAC for every request made to the World-Check One API, however the secret key itself is never transmitted within the contents of an API request. Once an API key and user secret pair have been made available to an API user, it becomes the responsibility of the API user to ensure the secret key is only ever accessible to that user alone.

In the event of an API key/secret pair being compromised, a new pair can be requested from a World-Check One administrator. Once a new key pair is assigned, all keys previously assigned to the user will be considered invalid, and HMACs created using the old keys will fail verification.

Upon receiving an API request, World-Check One will validate the request’s HMAC and will only treat the request as valid for further processing if the HMAC is correct. Every request message needs to have a HMAC present; if the code is missing or invalid for some reason, the request will be rejected as HTTP 401 Unauthorized, and discarded.

Message Structure

Prior to sending a request to the World-Check One API, an API user will need to calculate the corresponding HMAC, and add it to the request message in the appropriate header. The World-Check One API expects HMACs to be represented within a HTTP request using a similar format to the HTTP signature RFC (currently in draft form at time of writing) - i.e. included in the Authorization HTTP header.

To illustrate what this would look like, given an API key of {API-KEY}, a computed HMAC value of {HMAC-VALUE}, and a Base64-encoded representation of the HMAC of {BASE64-HMAC-VALUE} (i.e. Base64({HMAC-VALUE})), the Authorization header would be:

Authorization: Signature keyId="{API-KEY}",algorithm="hmac-sha256",
   headers="(request-target) host date content-type content-length",
   signature="{BASE64-HMAC-VALUE}"

Note that the list of headers expected to be used as part of the HMAC’s signing text are fixed, so API implementors should not add or remove further headers from the above list. Some flexibility in the list of headers is allowed in terms of the content-type and content-length headers being optional in scenarios where HTTP requests are made that do not contain payloads/bodies.

The World-Check One API differs from the draft HTTP signature RFC in the following ways:

  • Due to limited support from integration libraries & middleware to generate a reliable RFC 3230 Digest header, as well as the requirement to specifically validate HTTP request messages rather than HTTP resource responses, the Digest header is not used as part of the HMAC signing text. If this header is present in a request, it will be ignored by the World-Check One API.

  • The full request body is however included as part of the HMAC signing text. This fact is not relayed within the headers portion of the Authorization header.

HMAC algorithm

The HMAC is created as specified in RFC 2104. Many standard & third-party libraries already implement the HMAC algorithm, for example the javax.crypto.Mac class if implementing in Java. Please refer to the RFC text for specific details on the algorithm if there is a need to implement it without use of a preexisting library. It is advised that integrators check the documentation of their language’s standard libraries to see if a HMAC implementation is already available.

Specific details on the World-Check One API HMAC implementation are:

  • World-Check One only supports the HMAC-SHA256 variation of the algorithm. This has been selected as a more cryptographically secure hash function than for example MD5 or SHA1, at the expense of a higher CPU generation cost. The World-Check One API is a comparatively low call volume product that deals with sensitive data, making a more secure but higher cost hash function more appealing.

  • SHA256 utilizes a block size of 64 bytes

  • The signing text used as input to the hash function is composed of the following data, formatted in line with the HTTP signature RFC:

    • The HTTP request line

    • The HTTP headers:

      • Content-Length (optional if a request has no payload)

      • Content-Type (optional if a request has no payload)

      • Date

      • Host

    • The full HTTP request payload. Please note this particular field is divergent from the HTTP signature specification.

  • Headers within the signing text should be separated by a single newline character (‘\n’/0x0A) - as per the HTTP signature RFC. Data within the request payload can however be separated by any newline representation; when assembling the signing text, the payload is treated as a verbatim text blob.

For easier work with HMAC authentication a library was provided that contains authorization files for WC1 API written in different programming languages that speed up the integration work with the API.

HTTP request example

To illustrate all these requirements, given the following sample HTTP request:

POST /v2/cases HTTP/1.1
Host: api-worldcheck.refinitiv.com
Date: Tue, 07 Jun 2016 20:51:35 GMT
Content-Type: application/json
Content-Length: 88

{
  "caseId": "my customer ID",
  "name": "John Doe",
  "providerTypes": ["WATCHLIST"]
}

the signing text used as input to the HMAC function would be:

(request-target): post /v2/cases
host: api-worldcheck.refinitiv.com
date: Tue, 07 Jun 2016 20:51:35 GMT
content-type: application/json
content-length: 88
{
  "caseId": "my customer ID",
  "name": "John Doe",
  "providerTypes": ["WATCHLIST"]
}

This example assumes LF line endings (‘\n’/0x0A), and no trailing line ending after the closing bracket in the payload body.

Given the above signing text, if a secret key of “1234” is used, the computed HMAC-SHA256 value would be 224B73FC07571E60E8B8D9BAB8107C656D3171F346B96183C665FD4C5330B85D when printed using hex encoding, or Iktz/AdXHmDouNm6uBB8ZW0xcfNGuWGDxmX9TFMwuF0= when printed using base64 encoding.

The base64 representation is the value that will be included in the Authorization header. In this example, assuming an API key of 4321, the full HTTP request (with populated Authorization header) that will be sent to the API would then be:

POST /v2/cases HTTP/1.1
Host: api-worldcheck.refinitiv.com
Date: Tue, 07 Jun 2016 20:51:35 GMT
Content-Type: application/json
Content-Length: 88
Authorization: Signature keyId="4321",algorithm="hmac-sha256",
   headers="(request-target) host date content-type content-length",
   signature="Iktz/AdXHmDouNm6uBB8ZW0xcfNGuWGDxmX9TFMwuF0="

{
  "caseId": "my customer ID",
  "name": "John Doe",
  "providerTypes": ["WATCHLIST"]
}

Please note that using in request keyword "ON" with special characters or spaces causes the Forbidden error with 403 status code. The reason for the error is related to the AWS Web Application Firewall CrossSiteScripting_BODY rule. Each request that is sent to the LSEG World-Check One API goes through the AWS WAF. There is a set of rules that are applied to request to protect the system from possible exploitation of a wide range of vulnerabilities. CrossSiteScripting_BODY rule inspects the request body for common cross-site scripting (XSS) patterns using the built-in AWS WAF Cross-site scripting attack rule statement. This rule is described here. The keyword "ON" triggers this rule and causes the error.

Data at rest

All data at rest within the World-Check One system, including any data that is created and/or managed via the API, is encrypted via Amazon Aurora DB clusters encryption.

For further information on security features employed within the World-Check One system, as well as information on the product’s data privacy policy, please refer to the LSEG WORLD CHECK ONE : INFORMATION SECURITY & DATA PRIVACY statement included in the supporting documentation package.

Appendix A: Copyright

(c) 2018 - 2023 LSEG. All rights reserved. Republication or redistribution of LSEG content, including by framing or similar means, is prohibited without the prior written consent of LSEG. 'LSEG' and the LSEG logo are registered trademarks and trademarks of LSEG and its affiliated companies.

⬅ ︎Back to Documentation Home