Skip to main content

Getting the PIN for a card

Overview​

debiX offers the possibility to get the PIN of a card. 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. Unlike the card credentials protocol, this exchange requires the responses to be signed as well. This means that the issuer receives the debiX certificate to verify the signature.

Request to /cards/pin​

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 is soon to expire, 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 PIN is to be retrieved and the ephemeral public key of the issuer, which 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 for /cards/pin​

The response is a JWS signed by debiX and contains an ephemeral public key. 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 debiX switches from a certificate which is soon to expire, to a new certificate. The certificates used to check the signature of the signed payload can be found in the Downloads section. There is one for the test environment and one for the production environment. See the debiX certificates validity for the current validity dates of the certificates.

{
  "x5t#S256": "qBEpLqN-S9g7ZipUEkAvoZu_sSfrYCu-ZkdS421h9sU",
  "typ": "JWT",
  "alg": "RS256"
}

JWS Payload:

{
  "encryptedData": "PHPJDBNCeuNmofCeVJf/SECSRYB4q2iaXTus9lKMfEc=",
  "serverEphPubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEfc8SabkMtZk3NXzW7hfrN9oPyTLedscbPzzfk3xY8xpFMQoe3NdwOWaoejYMQeVz0qe8kJcrZSA7SZDJBpi4Ew=="
}

The ephemeral public key of debiX is used to perform a Diffie-Hellman key exchange and determine the shared encryption secret. The shared encryption secret is used to decrypt the PIN.

The unencrypted data contains the PIN.

{
  "pin": "123456"
}

Setup​

The debiX certificate needs to be passed to the issuer beforehand. It must be valid for at least 2 years and contain a 2048-bit RSA public key. This certificate is used to sign the get-pin response

The setup from here also applies:

  • debiX requires an issuer's certificate.
  • For supported encryption algorithms check here.

How to make the requests to get the PIN​

  1. Create an ephemeral public/private key pair on the issuer's side with:
    • algorithm: EC
    • elliptic curve: secp256r1
  2. Create a JWS with the cardId and the clientEphPubKey (X509-encoded public key generated in point 1, encoded with base64).
  3. Add the thumbprint of the certificate (base64 URL-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 the POST request to /cards/pin.
  6. Verify the signature of the response with the debiX certificate.
  7. Extract the X509-encoded serverEphPubKey and decode it with base64.
  8. 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 extract mentioned in point 7.
    • Bouncy Castle Algorithm: ECCDHwithSHA256KDF
    • Use the serverEphPubKey as additional shared information for ECDH with cofactor: see "sample-code" in the Downloads section.
  9. Determine key and iv:
    • key: sharedSecret[0, 16]
    • iv: sharedSecret[16, 32]
  10. Decrypt the encryptedData with key and iv.
    • Algorithm: AES/GCM/NoPadding
    • AES GCM Tag Length: 16

debiX certificates validity​

The certificates to verify the signature of the response given by /cards/pin have the following validity dates in this release:

  • Test environment: 05.12.2032
  • Production environment: 18.01.2025