Security Credentials

Your application has three types of mandatory credentials:

• A Client ID and Client Secret for authentication.
• Message Level Encryption for encryption and non-repudiation.
• A Digital Signature to certify that only the organisation holding the private key is the one that has signed the payload.

Connectivity

Transport Layer Security - SSL Certificate

The connection between your organisation and HSBC relies on a security protocol to encrypt the communication. The protocol used is SSL (Secure Sockets Layer) via HTTPS over the Internet.

A SSL Digital Certificate is used when you request an HTTPS connection to HSBC. This certificate contains the public key needed to begin the automatic SSL handshake which involves the generation of shared secrets to establish a uniquely secure connection.

In summary, with an HTTPS connection, all communications are securely encrypted between the customer and HSBC. This is commonly known as Transport Layer Security (TLS) or (communication) channel security, where a "tunnel" is established between two parties (customer and HSBC) so as to ensure encryption and secure communication.

SSL certificates are essential for securing API communications and protecting sensitive data exchanged between HSBC and your organization. To ensure the integrity of the API requests and responses, please regularly check the validity of the SSL certificate. Given that SSL Digital Certificates have expiration dates and need to be renewed frequently, please make sure to verify the validity of the certificate, and its authenticity by checking the certificate's chain of trust in HTTPS connection. This chain of trust typically involves verifying that the certificate has been signed by a trusted Certificate Authority (CA). You will need to ensure your organization has maintained an up-to-date list of trusted CAs before attempting connectivity to our APIs service. Please contact your HSBC representative should you have any questions.

Client ID and Client Secret

These credentials are used for authentication and must be provided in the headers of the HTTP request every time you invoke the Treasury API services. This ensures only authorised and pre-approved organisations can access and utilise our API services.

Message Encryption

In addition to the Transport Layer Security, HSBC adopts additional security on the message being passed through the connection session - called Message or Data Security.

Message Level Encryption provides both your organisation and HSBC, enhanced security for API message payload by using public-key cryptography and asymmetric encryption.

Public key encryption involves a pair of keys known as a public key and a private key which are assigned to an entity that needs to authenticate its identity electronically, or to sign or encrypt data. The public key is published and the corresponding private key is kept secret. Data that is encrypted with the public key can be decrypted only with the corresponding private key.

Public key cryptography enables encryption, decryption and non-repudiation.

The Treasury APIs support asymmetric encryption that uses a public key to encrypt data and a private key to decrypt data. The public key is available in a trusted certificate, whereas the private key is confidential and not shared.

Both you and HSBC need to exchange Public Key Certificate for Message Encryption purposes. This requires a separate pair of keys from the ones used for TLS authentication mentioned above.

You need to provide your HSBC Relationship manager or Client Service manager your public key during setup on our systems.

Where to get the Public Key Certificate?

• In order to use the Treasury API, first generate a set of Production Public and Private PGP Keys. To do this, you can use software such as OpenSSL and PGP.
• You receive HSBC's Public PGP Key via secure email as part of the HSBC Connect Digital setup process.
• Please contact your HSBC Sales or Client Service manager for further details.

How to use the Public Key Certificate?

• You must use HSBC's Public PGP Key to encrypt a message every time you send a request, and/or verify a signed message you have received from us. HSBC will use your Public PGP Key to do the same upon messages sent to you.
• For security purposes, you are required to renew your Public PGP Key every year.

Supported Algorithms

For asymmetric encryption, the HSBC Connect APIs support the RSA and Digital Signature Algorithm (DSA) algorithms.

Validations

The following validations will be performed on the Public key:

Digital Signature

A Digital Signature provides the customer and HSBC an assurance of the origin, identity, and status of the message, as well as an acknowledged consent of the signer. Please sign the payload with your PGP private key as part of the encryption and base64 encoding process.

Return to top