Skip to main content

Retrieving sensitive card credentials

Overview​

debiX offers the possibility to retrieve sensitive card credentials, such as the FPAN or CVV/CVC. This data must be protected with an extra layer of uninterrupted encryption. Both the calling and debiX server must be in a PCI-compliant environment. The implemented protocol ensures that each message is encrypted with a completely new key. This mitigates the risk of compromising all past and future messages in the event of a key loss (forward secrecy).

Protocol​

The client sends a JWS (JSON Web Signature). The content of the request (JWS Header and Payload) is signed with the private key of the issuer. debiX holds the matching certificate to verify the request.

Request to /cards/credentials​

The JWS Header has a base64-URL-encoded fingerprint of the used certificate. This fingerprint is used to select the correct certificate, at a time when the issuer switches from a certificate which soon expires to a new certificate.

{
  "typ": "JWT",
  "x5t#S256": "0kO7ZVqOEXJwO_B9xojGVluewsey142_E47De5uoMSc",
  "alg": "ES256"
}

The JWS Payload contains the cardId of the card for which the sensitive data is to be retrieved. The ephemeral public key of the issuer is used to perform a Diffie-Hellman key exchange and determine the shared encryption secret.

{
  "clientEphPubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElr8UU0x4ElGxRC7sQtVzxyWsJjDiLzxec7DJ5+efwDhiv4oCUpVsl571KIUqU02GcJrUiJq5QppA1vKJmq8tTQ==",
  "cardId": {
    "bankClearingNumber": 5000,
    "cardNumber": 123456,
    "cardType": 1,
    "cardSeqNumber": 1,
    "cardExpiry": {
      "month": "06",
      "year": "23"
    }
  }
}

Response​

The response contains an unsecured JWS with the encrypted sensitive data and the ephemeral public key of the debiX server.

The JWS Header denotes that it is not signed.

{
  "typ": "JWT"
  "alg": "none"
}

JWS Payload:

{
  "serverEphPubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElr8UU0x4ElGxRC7sQtVzxyWsJjDiLzxec7DJ5+efwDhiv4oCUpVsl571KIUqU02GcJrUiJq5QppA1vKJmq8tTQ==",
  "encryptedData": "xHux2M6KEDXMso53O7e1FN2ilKsXmjL/3jSj9PyzfNRSO2tIth2AzLUQMCc1/2cDP/D4a+3TIw=="
}

Once the data is unencrypted it contains the FPAN and CVV.

{
  "fpan": "1234567812345678",
  "cvv": "123"
}

Setup​

The issuer's certificate needs to be passed to debiX beforehand. It must be valid for at least 2 years and contain a public key with one of the supported encryption algorithms (see the next section Cryptography, keys and algorithms).

Cryptography, keys and algorithms​

The Elliptic Curve Diffie-Hellman (ECDH) key agreement protocol is used to secure this data exchange. It makes sure, that the key to encrypt the sensitive data is never transmitted. Each ephemeral ECC key-pair and its derived shared secret must only be used for one transmission, thus guaranteeing forward secrecy. The requesting client additionally signs the JWS request, making enabling debiX to authenticate it with the client's certificate.

  • ECC means elliptic curve cryptography.
  • ECDH is used as a key agreement protocol where the ephemeral keys and the shared secret are used only in a single transmission.
    • secp256r1 / prime256v1 / P-256 is the elliptic curve used for the ephemeral key pair.
  • 'ANSI X9.63 KDF with SHA256' is the function to derive a key from the shared DH secret.
  • 'AES GCM without padding' (AES/GCM/NoPadding) is used to encrypt the sensitive data.
  • SHA-256 is used as a hashing algorithm.
  • The issuer signs the JWS request with one the following signing algorithms:
    • RS256, RS384, RS512, PS256, PS384, PS512 (private key size should be at least 2048 bit)
    • ES256 (recommended), ES384, ES512
    • EdDSA (Ed25519)

How to make a request​

  1. Create an ephemeral public/private key pair on the issuer's side with the following:
    • algorithm: EC
    • elliptic curve: secp256r1
  2. Create a JWS with cardId and clientEphPubKey (the X509-encoded public key, encoded with base64 generated in point 1).
  3. Add the thumbprint of the certificate (base64url encoded) to the JWS Header (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8).
  4. Sign the JWS with the private key from the setup (debiX must have the corresponding certificate to verify the signature).
  5. Make a POST request to /cards/credentials.
  6. Extract the X509-encoded serverEphPubKey and decode it with base64.
  7. Determine the shared secret via the key agreement protocol and key derivation function with:
    • The issuer's own ephemeral private key generated in point 1 and the serverEphPubKey
      • Bouncy Castle Algorithm: ECCDHwithSHA256KDF
  8. Determine the key and iv:
    • key: sharedSecret[0, 16]
    • iv: sharedSecret[16, 32]
  9. Decrypt the encryptedData with key and iv.
    • Algorithm: AES/GCM/NoPadding
    • AES GCM Tag Length: 16