Product in beta version 🔐We are working on our beta version for Mexico 🇲🇽. Contact your account manager for more information.
Agreements and initial conditions#
Kushki and the merchant hold a session to review the conditions for exchanging keys with third parties. This process requires the merchant's HSM provider to agree to the terms of the key exchange ceremony. If agreed, they establish working mechanisms and secure channels for exchanging sensitive information, and define at least two security officers (SOs) on the merchant's side.The merchant is required to have a Hardware Security Module (HSM) due to the cryptographic key exchange process.
Third-party conditions#
The merchant must be prepared to exchange components with the HSM supplier on behalf of Kushki. Steps to follow:Sign the Kushki HSM provider NDA and obtain access to the portal.
Create and maintain SOs with correct contact details and groups in the portal.
Be prepared to follow the key exchange process as defined in this documentation.
Request and validation of required documentation#
Kushki requests the documentation needed to register the merchant in the HSM service and in the Kushki Console. Once received, Kushki validates it and the process continues.
Generation and sending of Key Encryption Key (KEK) components#
Kushki generates and sends three key components for the Key Encryption Key (KEK), along with their respective Key Check Values (KCV), via the secure channels established above — delivered to the previously defined security officers.When components are shipped, SOs receive an email containing:Key reference information
Contact details (excluding address) of the sending SO
Shipment details and tamper-evident bag serial number
A link to the Portal checklist to complete upon receipt
Depending on the environment, Kushki may send KEK components electronically (test) or physically (live production).
Requirements for SOs before the key exchange#
Registered in the Kushki HSM service portal.
Each participating SO must have an active account.
Placed in the correct SO groups (1, 2, or 3).
Shipping address kept up to date for physical component delivery.
Test environment#
Kushki may ship KEK components by secure electronic means (email, security vault, SFTP). The merchant receives a table like the following:| KEY ID | DESCRIPTION | ALGORITHM | LENGTH | CLEAR TEXT KEY/COMPONENT | KCV |
|---|
| ZMK | Component 1 | 3DES | double | A2F2 9E20 4515 D531 6B2C 32BC 3E58 612F | EF0F99 |
| Double-len | Component 2 | 3DES | double | BA1F 23CD 8529 2C7A 51EC 07A2 EA8A C11F | F23EFF |
| Component 3 | 3DES | double | F70D 38D6 E557 A176 BC4F 1002 3D4C 01E9 | C41DBB |
Live (production) environment#
Kushki ships three security envelopes — one key component printed on paper per envelope — to at least two security custodians who do not report to the same person.Shipping of physical components usually takes approximately two weeks, depending on SO locations.
1.
Email seguridad@kushkipagos.com with subject "KEK component check successful - [MERCHANT_NAME]" and body "Check successful".
2.
SOs complete the receipt confirmation checklist through the Kushki HSM Service Provider Portal (link arrives by email).
Once the component has been activated in the Kushki HSM service portal, SOs must destroy the physical component.
Generation and sending of Base Derivation Keys (BDK)#
Kushki registers the merchant in the Kushki Console, where the merchant obtains:Private-Credential-Id (private key for transactions)
Other relevant configuration
data and one for pin (PIN block) — encrypted with the KEK in TR-31 format, and exchanges them via secure electronic means.Example of a BDK encrypted with KEK in TR-31 format:RD0112B0TX00N00004FD842D565C0BDD9741A3EAB5106A78087A4D0729A56319F32AF9FBFC6FAE0A184DA40D08FA279FBB50E7598936AD18F
BDKs for the production environment are shared via secure electronic means (e.g., 1Password).
Got a suggestion on this documentation? Contact us.
