Setting a new PIN for the card

Overview

debiX offers the possibility to set a new PIN for 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/start-set-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 set.

{
  "cardId": {
    "bankClearingNumber": 5000,
    "cardNumber": 123456,
    "cardType": 1,
    "cardSeqNumber": 1,
    "cardExpiry": {
      "month": "06",
      "year": "23"
    }
  }
}

Response for `/cards/start-set-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.

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

JWS Payload:

{
  "serverEphPubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElr8UU0x4ElGxRC7sQtVzxyWsJjDiLzxec7DJ5+efwDhiv4oCUpVsl571KIUqU02GcJrUiJq5QppA1vKJmq8tTQ==",
}

Request to `/cards/set-pin`

{
  "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 set. The ephemeral public key of the issuer is used to perform a Diffie-Hellman key exchange and determine the shared encryption secret. The shared encryption secret is used to encrypt the PIN.

{
  "clientEphPubKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElr8UU0x4ElGxRC7sQtVzxyWsJjDiLzxec7DJ5+efwDhiv4oCUpVsl571KIUqU02GcJrUiJq5QppA1vKJmq8tTQ==",
  "encryptedData": "xHux2M6KEDXMso53O7e1FN2ilKsXmjL/3jSj9PyzfNRSO2tIth2AzLUQMCc1/2cDP/D4a+3TIw==",
  "cardId": {
    "bankClearingNumber": 5000,
    "cardNumber": 123456,
    "cardType": 1,
    "cardSeqNumber": 1,
    "cardExpiry": {
      "month": "06",
      "year": "23"
    }
  }
}

The unencrypted data contains the PIN.

{
  "pin": "123456"
}

Response for `/cards/set-pin`

If setting the PIN has been successful, the response is an HTTP code 204.

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 start-set-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 set the PIN

Both requests /cards/start-set-pin and /cards/set-pin are required every time a PIN is set.

Create a JWS with the cardId.
Add the thumbprint of the certificate (base64 URL-encoded) to the JWS Header (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8).
Sign the JWS with the private key from the setup (debiX must have the corresponding certificate to verify the signature).
Make the POST request to /cards/start-set-pin.
Verify the signature of the response with the debiX certificate.
Extract the X509-encoded serverEphPubKey and decode it with base64.
Create an ephemeral public/private key pair on the issuer's side with:
- algorithm: EC
- elliptic curve: secp256r1
Determine the shared secret via the key agreement protocol and key derivation function with:
- The issuer's own ephemeral private key generated in point 7 and the serverEphPubKey extract mentioned in point 6.
- Bouncy Castle Algorithm: ECCDHwithSHA256KDF
- Use the serverEphPubKey as additional shared information for ECDH with cofactor: see "sample-code" in the Downloads section.
Determine key and iv:
- key: sharedSecret[0, 16]
- iv: sharedSecret[16, 32]
Encrypt the PIN
- Algorithm: AES/GCM/NoPadding
- AES GCM Tag Length: 16
Create a JWS with cardId, the encryptedData (containing the PIN) and the clientEphPubKey (X509-encoded public key generated in point 7, encoded with base64).
Add the thumbprint of the certificate (base64 URL-encoded) to the JWS Header (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8).
Sign the JWS with the private key from the setup (debiX must have the corresponding certificate to verify the signature).
Make a POST request to /cards/set-pin.
HTTP response code 204 shows that the PIN has been successfully set.

debiX certificates validity

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

Test environment: 05.12.2032
Production environment: 18.01.2025

Overview​

Protocol​

Request to /cards/start-set-pin​

Response for /cards/start-set-pin​

Request to /cards/set-pin​

Response for /cards/set-pin​

Setup​

How to make the requests to set the PIN​

debiX certificates validity​