Field-level Encryption
Learn how to encrypt sensitive data while making an authorisation request
Cards Connect requires field-level encryption (FLE) for the sensitive fields in the authorisation request body. FLE ensures that the sensitive details cannot be read if the data is sniffed during the transport of data. In the current version, Cards Connect requires Card Details and Billing Details objects under the Authorisation request to be encrypted.
FLE is based on the Json Web Encryption (JWE) standard. Encrypted fields are sent to Cards Connect in the form of JWE tokens, with the JWE payload containing the data elements to be protected. For example, the cardDetails
object in the Authorisation Request is the payload of the JWE token contained in the field cardDetailsEnrypted
.
The JWE token is generated using the Cards Connect public key. The public key must be downloaded from the respective API and stored for use until the key expiry date is reached. Once the key has expired, a new public key must be downloaded from the same API.
Encryption Fundamentals
Cards Connect maintains public/private elliptic curve key pairs (1 generated per week with 2 week lifespan)
Standard JSON Web Token (JWT) libraries can be used to generate JWE tokens. The specific parameters required are:
- Key exchange algorithm: ECDH-ES+A256KW (Elliptic Curve Diffie-Hellman Ephemeral Static key agreement protocol with Advanced Encryption Standard (AES) Key Wrap using a 256-bit key)
- Encryption algorithm: A256GCM (Advanced Encryption Standard (AES) with a 256-bit key)
Encryption Process
- Cards Connect maintains a set of public/private elliptic curve key pairs (CCPri - CCPub) that are refreshed on a weekly basis, with each pair having a lifespan of two weeks.
- Download Cards Connect public key (CCPub) via an API endpoint.
- Encrypt the
cardDetails
andbillingDetails
fields in the payload by with the following specifications:- Key exchange algorithm: ECDH-ES+A256KW (Elliptic Curve Diffie-Hellman Ephemeral Static key agreement protocol with Advanced Encryption Standard (AES) Key Wrap using a 256-bit key)
- Encryption algorithm: A256GCM (Advanced Encryption Standard (AES) with a 256-bit key)
- Generate the encrypted token using the Cards Connect public key (CCPub)
Updated 3 months ago