The Hyperswitch Card Vault (Repository Link), is a highly performant and a secure locker to save sensitive data such as credit card details, bank account details etc. 

It is designed in a polymorphic manner to handle and store any type of sensitive information enabling your application to store a customer's payment method details in a processor agnostic manner. Its usage can also be extended to securely store customer information. 

Hyperswitch Card Vault is built to be a GDPR compliant personal identifiable information (PII) storage system and to be fully compliant with PCI DSS requirements for securely storing card information.

The core objective of tokenization is to minimize the access touchpoints of the actual payment card details and replace it with a randomly generated token, which is an unique identifier that ties back the card information. This token is then used for processing transactions, and the sensitive card details are stored securely in a centralized system and maintained by the payment orchestrator, payment service or other trusted third parties.

Here’s some more context as to how credit card tokenization works in general:

Initiation:

When a user adds their payment card to a digital wallet, a payment app, or an online service, the actual card details are sent to a tokenization service.

Tokenization Process:

  • The tokenization service generates a random token that is associated with the user's card details.

  • The token, not the actual card details, is stored on the user's device and on the server of the service provider.

Transaction Processing:

  • When the user initiates a transaction, the token is sent to the payment gateway or processor instead of the actual card details.

  • The payment gateway then maps the token to the real card details stored in its secure database.

Authorization:

The payment processor authorizes the transaction using the real card details.

The token itself is meaningless to potential attackers, as it is just a reference.

Secure Storage:

The actual card details are stored securely in a centralized, highly protected environment, reducing the risk of data breaches

How does Tartarus work?

​Locker usage flow​


  • Your application communicates with Tartarus via a middleware.

  • All requests and responses to and from the middleware are signed and encrypted with the JWS and JWE algorithms providing end-to-end encryption.

  • The locker supports CRD APIs on the  /data and /cards endpoints - API Reference​

  • Cards are stored against the combination of merchant and customer identifiers.

  • Internal hashing checks are in place to avoid data duplication.

This approach of using a middleware offers two key advantages: separation of application code and encryption logic, and the ability to extend the API without additional code for encrypting other APIs

Key Hierarchy

Master Key - AES generated key to that is encrypted/decrypted by the custodian keys to run the locker and associated configurations.

Custodian Keys - AES generated key that is used to encrypt and decrypt the master key. It is broken into two keys (key 1 and key 2) and available with two custodians to enhance security.

Key Hierarchy of Tartarus

For PCI-DSS Compliance, sensitive card data stored in the application undergoes multi-layered encryption. Encryption policies are set at the merchant level, complemented by 2FA authentication to unlock the locker. KMS encryption further secures the keys for locker access. Communication between the application and the card vault is encrypted using JWE + JWS at the middleware level.

Key techniques in our locker for high performance and simplicity:

  • Encryption Trait: We've created a generic trait to define various encryption algorithms, allowing for future compatibility. Currently, it covers KMS, JWE + JWS, and AES encryption, each serving distinct purposes.

  • zeorize: To prevent unencrypted storage of card details, we use StrongSecret, ensuring data is zeroed from memory once it leaves the locker application.

  • Validations: Data input undergoes efficient validation with minimal overhead. For instance, our card number verification (using the Luhn algorithm) takes only around 50-60ns, optimizing performance.

  • tower-http: Leveraging the tower crate's middleware ecosystem, we enhance security with specific APIs. For example, we implement rate limiting on the delete card API.

Also here’s a quick look at the performance benchmark for the card vault to run the Luhn’s algorithm:

​The catch here is that you have to be a PCI compliant entity to be able to handle the raw card details of your customers. The effort to obtain PCI compliance is often exaggerated and we have tried to reduce the effort involved considerably for someone who’s starting afresh with relatively low transaction volumes. You can learn more about the levels of PCI compliance here. Having said that, managing your own card vault is a great way to de risk your payments stack and exercise more control over how you run your payment operations