# Poynt Device Remote Key Loading

Poynt Terminal Remote Key Loading requires the Terminal to have a Device Signing Certificate (RSA 2048 Key Pair) and the corresponding Trusted CA Chain, to be able to exchange Terminal Encryption Keys (P2PE/PIN) with Poynt Remote Key Management System (RKMS).

Please refer to Poynt Device Object Signing Specification for information on how to load a Device Signing Certificate for all Terminals at the manufacturing facility.

Poynt Remote Key Loading consists of 3 specific requests & responses to establish secure connection, exchange and validation of the keys. The following diagram outlines the overall process flow of the Remote Key Loading process.

Remote Key Loading Process

# Prerequisites

Terminal must be Object Signed and supports all the necessary methods as described in the Poynt Device Object Signing Specification document.

# Remote Key Loading APIs

The following are the methods that must be provided by the card reader to support Remote Key Loading process. These methods are defined as part of IPoyntPaymentSecuritySPI.aidl and must be implemented by the Card Reader provider in order to be compatible with Poynt Remote Key Loading process.

# eraseAllKeys()

This command is used to erase all PCI keys on the card reader that are related to PIN and Data Encryption. This includes all Key Protection Keys, DUKPT Keys, Master/Session Keys, etc. This command MUST NOT erase the Device Signing Certificate (RSA 2048 Key Pair).

# Input Params

  • Callback - where the result of erasing all keys is returned. Following are the 2 methods defined in the callback.

    • onSuccess()

    • onError(PoyntError error)

# Output Params

Callback onSuccess() or onError() as appropriate.

# Error Conditions

  • Unable to erase keys due to permission error, return error

    • PoyntError.ERASE_KEYS_FAILURE

# initiateRemoteKeyLoading()

This method is used to initiate remote key loading requests by providing RKMS signing and encryption certificates retrieved from the Poynt RKMS system. Card readers must verify the given RKMS Signing and encryption certificates, and store them for subsequent operations. The previously loaded CA Trust chain is used for the RKMS Signing and Encryption Certificate verification.

# Input Params

  • RKMS Signing Certificate - Certificate used to sign the remote key loading messages

  • RKMS Encryption Certificate - certificate used to encrypt the session key used to exchange terminal keys

  • Secure nonce - Random data (nonce) of length 8 used for replay detection

  • Callback - where the result of RKMS certification verification is returned. Following are the 2 methods defined in the callback.

    • onSuccess()

    • onError(PoyntError error)

# Output Params

When the RKMS Signing and Encryption Certificates are validated successfully, returns a onSuccess() callback otherwise onError().

# Error Conditions

  • If RKMS certificate validation failed, return error

    • PoyntError.RMKS_CERT_VALIDATION_FAILED
  • If saving of RKMS certificates failed, return error

    • PoyntError.REMOTE_KEY_INITIATION_FAILED
  • If secure nonce has been used in the session already, return error

    • PoyntError.NONCE_REPLAYED

# generateDeviceKeyRequest()

This method is used for the terminal to request keys from the RKMS server. The key request must include a TR34 block containing the Session Key that is used to encrypt the terminal keys in the subsequent commands. The Session Key is encrypted with the RKMS Encryption Certificate loaded in the initiateRemoteKeyLoading() method above.

# Input Params

  • Callback - where the key request is returned. Following are the 2 methods defined in the callback.

    • onSuccess()

    • onError(PoyntError error)

# Output Params

Card readers must generate a session key used for key exchange with RKMS. The session key is packaged in TR-34 format encrypted with RKMS encryption certificate.

The response to onSuccess() callback must return the following parameters:

  • onSuccess(String sessionKey,int maxKeysToReturn,String signingPaddingMethod, String nonce) -- where,

    • Session key in the form of a TR-34 blob encrypted using RKMS Encryption Certificate

    • Max number of keys to return in one request (eg. 10)

    • Signing Padding Method: 1 or 2

      • 1 -- PKCS1v1.5 (recommended)

      • 2 -- PSS

    • Random data (nonce) of length 8 used for replay detection

# Error Conditions

  • If no RKMS Signing and Encryption Certificates are found, return error

    • PoyntError.NO_RKMS_CERTS_FOUND
  • If session key generation failed, return error

    • PoyntError.RKL_SESSION_KEY_GENERATION_FAILED
  • If key request generation failed, return error

    • PoyntError.RKL_KEY_REQUEST_GENERATION_FAILED

# loadDeviceKeyResponse()

This method is used to load the keys from RKMS. The input contains the keys encrypted with the Session Key sent in the Key Request.

# Input Params

  • encryptedKey - HEX-ASCII encoded ASN.1 Structure, which contains a sequence of TR-31 key blocks - please see Appendix for details.

  • Secure nonce - random data (nonce) of length 8 used for replay detection

  • Signing Padding Method - Signing Padding Method (1 or 2)

    • 1 -- PKCS1v1.5

    • 2 -- PSS

  • Salt length - Optional PSS padding

  • Callback - where the result of key request response is returned. Following are the 2 methods defined in the callback.

    • onSuccess()

    • onError(PoyntError error)

# Output Params

When the encryption keys are validated and loaded successfully, returns a onSuccess() callback, otherwise onError().

# Error Conditions

  • If secure nonce has been used in the session already, return error

    • PoyntError.NONCE_REPLAYED
  • If encrypted Key is invalid or failed validations, return error

    • PoyntError.RKL_INVALID_KEY_STRUCTURE
  • If key loading failed, return error

    • PoyntError.RKL_KEY_LOAD_FAILED

# generateDeviceKeyValidationRequest()

This method is used to validate the injected keys with the RKMS server. When this method is invoked, card reader must generate the key validation report which is sent to the RKMS server for confirming the loaded encryption keys.

# Input Params

  • Callback - where the key validation report is returned. Following are the 2 methods defined in the callback.

    • onSuccess(String keyVerificationReport, long saltLength, String signingPaddingMethod, String nonce)

    • onError(PoyntError error)

# Output Params

Card readers must generate a key report with the details of the keys loaded in the loadDeviceKeyResponse() method.

The response to onSuccess() callback must return the following parameters:

  • Key verification report - Key Verification ASN.1 structure, hex encoded - please see appendix for details

  • Salt length - optional - PSS padding

  • Signing Padding Method: 1 or 2

    • 1 -- PKCS1 v1.5 (recommended)

    • 2 -- PSS

  • Random data (nonce) of length 8 used for replay detection

# Error Conditions

  • If secure nonce has been used in the session already, return error

    • PoyntError.NONCE_REPLAYED
  • If no encrypted keys are loaded, return error

    • PoyntError.RKL_NO_KEYS_FOUND
  • If key report generation failed, return error

    • PoyntError.RKL_KEY_REPORT_GENERATION_FAILED

# validateDeviceKeyValidationResponse()

This method is used to confirm the keys loaded from the key validation report generated by generateDeviceKeyValidationRequest(). If more keys are available to load, remaining keys are loaded using the same sequence of comments as described above.

# Input Params

  • All keys loaded - if true - all keys confirmed loaded and device is locked, if false - more keys are available to fetch from RKMS

  • Signature - RSA signature of following data, signed by the RKMS signing certificate

    • "BBY" -- if all keys are loaded

    • "BBN"-- if more keys are available

  • Padding method - 1 or 2

    • 1 = PKCS #1 1.5

    • 2.= PKCS #1 PSS

  • Secure nonce - Random data (nonce) of length 8 used for replay detection

  • Salt length - Optional -- PSS padding

  • Callback - where the key validation repose is returned. Following are the 2 methods defined in the callback.

    • onSuccess()

    • onError(PoyntError error)

# Output Params

When the RKMS signature is validated successfully, returns a onSuccess() callback otherwise onError().

# Error Conditions

  • If secure nonce has been used in the session already, return error

    • PoyntError.NONCE_REPLAYED
  • If no key load in progress, return error

    • PoyntError.RKL_NO_KEY_LOAD_IN_PROGRESS
  • If cannot handle more keys to load, return error

    • PoyntError.RKL_KEY_LIMIT_REACHED

# Appendix

# ASN.1 Structure

The format of an ASN.1 Structure used in loadDeviceKeyResponse() is as below:

KeyBlock ::= Sequence
{
 	keyblock version = 1 (INTEGER)
 	Keys ::= Set
 	{
      	keyinfo ::= Sequence
      	{
           	TR31Key = (PRINTABLESTRING)
           	keyType = (INTEGER)
           	ksn = (OCTET STRING) – If keyType is not DUKT 00000000000000000000
           	keySlot = (INTEGER)
           	cryptoMode = (PRINTBLESTRING) - Optional Field
      	}
 	}
 	keyName = (PRINTABLESTRING)
 	keyCheck = (OCTET STRING)
}

Where:

  • TR31Key: X9 TR-31 Key Block encrypted using the TR-34 Session Key as its Key Block Protection Key.

  • keyType: Indicates the type of Key.

    • type 1 (Master Session Key)

    • type 2 (Dukpt Initial Key)

    • type 4 (MAC Key)

    • type 5 (Pin Encryption Key)

    • type 10 (Data Encrytpion Key)

  • ksn: unused, since KSN is included in TR31 Key Block as an optional header

  • keySlot: the destination slot (0-9)

  • keyName: a ASCII string describing the key

  • keyCheck: Key Check Value (2 first byte of the 8-byte zeros encrypted with key-to-be-injected in clear using TDES ECB)

A key of type 1 (Master Session Key) should be inserted in the key slots as a Master Key.

A key of type 2 (Derived Dukpt Initial Key) should be injected as Initial DUKPT key

A key of type 4 (MAC Key) should be injected in the key slots as a "Data MAC Session Key"

A key of type 5 should be injected in the key slots as a "Pin Session Key"

A key of type 10 should be injected in the key slots as a "Data Session Key"

All the keys to be injected will be passed in this ASN.1 structure as TR-31 Key Blocks and all TR-31 Key Blocks in this structure will use the same temporary TR-34 Session Key securely exchanged via the GET KEY REQUEST command.

Note that the TR-34 Session Key is discarded once all the keys are injected successfully or unsuccessfully (for instance due to an incorrect MAC, or invalid KCV).

Last Updated: 9/29/2020, 12:28:59 AM