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.
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, theDigest
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 theAuthorization
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.