EML Security Documentation

EML Security

Overview

The EML Security documentation describes how we utilise two encryption schemes to help tighten our communication security and enable us to pass json payloads securely between our systems and web services.

If you are not familiar with cryptography here are some definitions to get you started:

Algorithms

An algorithm is basically a procedure or a formula for solving a data snooping problem. An encryption algorithm is a set of mathematical procedure for performing encryption on data. Through the use of such an algorithm, information is made in the cipher text and requires the use of a key to transforming the data into its original form. This brings us to the concept of cryptography that has long been used in information security in communication systems.

Cryptography

Cryptography is a method of using advanced mathematical principles in storing and transmitting data in a particular form so that only those whom it is intended can read and process it. Encryption is a key concept in cryptography - It is a process whereby a payload is encoded in a format that cannot be read or understood by an eavesdropper. The technique is old and was first used by Caesar to encrypt his messages using Caesar cipher. A plain text from a user can be encrypted to a ciphertext, then send through a communication channel and no eavesdropper can interfere with the plain text. When it reaches the receiver end, the ciphertext is decrypted to the original plain text.

Cryptography Terms

  • Encryption: It is the process of locking up information using cryptography.
  • Decryption: The process of unlocking the encrypted information using cryptographic techniques.
  • Ephemeral Key: A secret like a password used to encrypt and decrypt information.

Encryption Schemes

Symmetrical Encryption

This is the simplest kind of encryption that involves only one secret key to cipher and decipher information. Symmetrical encryption is an old and best-known technique. It uses a secret key that can either be a number, a word or a string of random letters. It is blended with the plain text of a payload to change the content in a particular way. The sender and the recipient should know the secret key that is used to encrypt and decrypt the payload. As a standard EML uses the algorithm of AES-128 for symmetric encryption.

The main disadvantage of the symmetric key encryption is that all parties involved have to exchange the key used to encrypt the data before they can decrypt it, and becuase of this EML uses a combination of both encryption schemes by encrypting Ephemeral Key with the asymmetric public key.

Asymmetrical Encryption

Asymmetrical encryption is also known as public key cryptography, which is a relatively new method, compared to symmetric encryption. Asymmetric encryption uses two keys to encrypt a plain text. Secret keys are exchanged over the Internet or a large network. It ensures that malicious persons do not misuse the keys. It is important to note that anyone with a secret key can decrypt the payload and this is why asymmetrical encryption uses two related keys to boosting security. A public key is made freely available to anyone who might want to send you a payload. The second private key is kept a secret so that you can only know.

A payload that is encrypted using a public key can only be decrypted using a private key, while also, a payload encrypted using a private key can be decrypted using a public key. Security of the public key is not required because it is publicly available and can be passed over the internet. Asymmetric key has a far better power in ensuring the security of information transmitted during communication.

PIN Change Encryption

EML PIN Management API requires all payloads to be securely encrypted using the following encryption process outlined below;

Authentication

An access token is required to consume the methods for the Transaction Simulator API. Refer to the Authentication documentation for further details on OAuth 2.0 and use the EML Token APIopen in new window documentation as a reference to obtaining an access token.

Environments Endpoints

Beta https://beta.emerchants.com.au/3.0/pinProduction https://ws.emerchants.com.au/3.0/pin

Encryption Process

  1. EML Issues Public Certificate to Partner
  2. Parter Generate AES 128bit Ephemeral Key and IV.
  3. The payload is SecureData in json format, For example,
{
	"otp":"34567801",
	"pin":"2378"
 }
  1. Encrypt the payload using AES. Padding Mode is PKCS#7 and Cipher Mode uses CBC
  2. Encrypt the ephemeral key using RSA public key. RSA padding mode is oaepSHA256 (SHA256) or oaepSHA512 (SHA512). Padding mode is defaulted to oaepSHA256 if not specified.
  3. The encrypted payload returned in json format. All binary data are hex encoded. For example,
{
  "encrypted_data": "ECF51D7E8C968ABDC85265BF82524A8F901ABB7EC27DA8438BEF547A786102D1",
    "public_key_fingerprint": "C42A1DADFC20F865FEBFCE471A7BF1E16D9C2A14",
    "encrypted_key": "536F1CD41D8CF12850D5BE23066E1A73A0E079923C7FB9F5A9F77248656FD9DA9E2E06945772B1858B30F59AAF1BA795B0A0F1E0125BF562DB4F0DBE4CC2D0B7CF965E994F4073297C6EE6F48C49D0545AA53FD79497711EAD6B4D45267323F3C4E9EA8CD29F18CDA87A7D599326BDC63C76DD61BDF76BA530FC7422E0C3D96D9FA2A8ADEA7B4BF678BEE512E2505F742A288E32B45316A6E2887503E9F5C5A5C76B61F55E61F8CF5D9AB8EDDFF9D5AB1091030D7E9DD1094DA9ED1B6873F52DDA5E18410E6393947334624F99B1354C5B63E333E61A67D7F6CD25FB24B64736D7EF4550C1E86F2D8AD10EC91842CD46D73B38E18BD0546B558F91AC92F8E41738B2D533D23F121BCB69E191E9E477B9ABD426DABB4D9EEDF1F5580D713293818D8633D882A9F1E5D3A4635E167F68E924222027A26E5FBB0061F0572DA00FA60C6884C385312279DD617BE48D6C4087B8FA86122E6AABDBDECBFA875266EBF199725C47715900C7130B4A0AA0705BC98E666DC5C9AA90E101FDFB6CD7854DFE10743C35D62AC1234B731084AEB977E9B84B617D903CB5F5AF3B7E9B354851A6C0B842E44E3E82F9F2D78D0B957424FFBDB4920767BF925C1988F144BD9D9B52A1E4F266C8BBF16702B44D157E7D838F85A543B4A6BC5D9AD6505C996DB86636C440128DFEB288B58CDE82D0BF8D882CDB5FAD48102B4F7A5C733B9F28135CD0",
    "oaep_hashing_algorithm": "SHA256",
    "iv": "17BE6277913939168162CA26088601A2"
}

Sample Payloads

POST /pin/initiate

{
   "eaid": "TH5803VR7",
   "device_id":"device id",
   "ip_address":"49.255.157.198",
   "communication_method":"sms"
 }

POST /pin/validate

{
   "device_id":"device id",
   "ip_address":"49.255.157.198",
   "operation_id": "e6327ee5-803a-4f6e-9658-eac0434222ac",
    "encrypted_data": "ECF51D7E8C968ABDC85265BF82524A8F901ABB7EC27DA8438BEF547A786102D1",
    "public_key_fingerprint": "C42A1DADFC20F865FEBFCE471A7BF1E16D9C2A14",
    "encrypted_key": "536F1CD41D8CF12850D5BE23066E1A73A0E079923C7FB9F5A9F77248656FD9DA9E2E06945772B1858B30F59AAF1BA795B0A0F1E0125BF562DB4F0DBE4CC2D0B7CF965E994F4073297C6EE6F48C49D0545AA53FD79497711EAD6B4D45267323F3C4E9EA8CD29F18CDA87A7D599326BDC63C76DD61BDF76BA530FC7422E0C3D96D9FA2A8ADEA7B4BF678BEE512E2505F742A288E32B45316A6E2887503E9F5C5A5C76B61F55E61F8CF5D9AB8EDDFF9D5AB1091030D7E9DD1094DA9ED1B6873F52DDA5E18410E6393947334624F99B1354C5B63E333E61A67D7F6CD25FB24B64736D7EF4550C1E86F2D8AD10EC91842CD46D73B38E18BD0546B558F91AC92F8E41738B2D533D23F121BCB69E191E9E477B9ABD426DABB4D9EEDF1F5580D713293818D8633D882A9F1E5D3A4635E167F68E924222027A26E5FBB0061F0572DA00FA60C6884C385312279DD617BE48D6C4087B8FA86122E6AABDBDECBFA875266EBF199725C47715900C7130B4A0AA0705BC98E666DC5C9AA90E101FDFB6CD7854DFE10743C35D62AC1234B731084AEB977E9B84B617D903CB5F5AF3B7E9B354851A6C0B842E44E3E82F9F2D78D0B957424FFBDB4920767BF925C1988F144BD9D9B52A1E4F266C8BBF16702B44D157E7D838F85A543B4A6BC5D9AD6505C996DB86636C440128DFEB288B58CDE82D0BF8D882CDB5FAD48102B4F7A5C733B9F28135CD0",
    "oaep_hashing_algorithm": "SHA256",
    "iv": "17BE6277913939168162CA26088601A2"
 }

POST /pin/execute

{
  "device_id":"device id",
  "ip_address":"49.255.157.198",
  "operation_id": "e6327ee5-803a-4f6e-9658-eac0434222ac",
   "encrypted_data": "ECF51D7E8C968ABDC85265BF82524A8F901ABB7EC27DA8438BEF547A786102D1",
   "public_key_fingerprint": "C42A1DADFC20F865FEBFCE471A7BF1E16D9C2A14",
   "encrypted_key": "536F1CD41D8CF12850D5BE23066E1A73A0E079923C7FB9F5A9F77248656FD9DA9E2E06945772B1858B30F59AAF1BA795B0A0F1E0125BF562DB4F0DBE4CC2D0B7CF965E994F4073297C6EE6F48C49D0545AA53FD79497711EAD6B4D45267323F3C4E9EA8CD29F18CDA87A7D599326BDC63C76DD61BDF76BA530FC7422E0C3D96D9FA2A8ADEA7B4BF678BEE512E2505F742A288E32B45316A6E2887503E9F5C5A5C76B61F55E61F8CF5D9AB8EDDFF9D5AB1091030D7E9DD1094DA9ED1B6873F52DDA5E18410E6393947334624F99B1354C5B63E333E61A67D7F6CD25FB24B64736D7EF4550C1E86F2D8AD10EC91842CD46D73B38E18BD0546B558F91AC92F8E41738B2D533D23F121BCB69E191E9E477B9ABD426DABB4D9EEDF1F5580D713293818D8633D882A9F1E5D3A4635E167F68E924222027A26E5FBB0061F0572DA00FA60C6884C385312279DD617BE48D6C4087B8FA86122E6AABDBDECBFA875266EBF199725C47715900C7130B4A0AA0705BC98E666DC5C9AA90E101FDFB6CD7854DFE10743C35D62AC1234B731084AEB977E9B84B617D903CB5F5AF3B7E9B354851A6C0B842E44E3E82F9F2D78D0B957424FFBDB4920767BF925C1988F144BD9D9B52A1E4F266C8BBF16702B44D157E7D838F85A543B4A6BC5D9AD6505C996DB86636C440128DFEB288B58CDE82D0BF8D882CDB5FAD48102B4F7A5C733B9F28135CD0",
   "oaep_hashing_algorithm": "SHA256",
   "iv": "17BE6277913939168162CA26088601A2"
}