Skip to main content

Message Decryption

Guide​

After learning about generating your private key and public key, the private key will be used when processing data on partner side, including decryption. There are two main algorithm that will be used on the encryption and/or decryption process:

  1. RSA OAEP 256 is used to encrypt and decrypt secret key. Secret key is random generated 32 bytes of characters that will be used as material in the second algorithm. This algorithm need public key when encrypt, and need private key when decrypt.
  2. AES 256 GCM is used to encrypt or decrypt the content. This material need the secret key from previous algorithm as cipher. The encrypted result is divided into two component, Cipher text and nonce. Nonce or initial vector is random factor that can be extracted from sequence of bytes of decoded message as suffix in the last 12 bytes. Otherwise, cipher text is the rest of the bytes excluding nonce. For full explanation how this algorithm works you can refer to these link about AES and GCM.
  3. Encoding Method that will be used to represent the encrypted data is base64.

This is the step by step decryption process for secret key and content message.

Encryption Step by Step

Encrypted Data​

When receive the data from our API or webhook that need to be decrypted, the payload will show json field as below:

...
"encryption": {
    "secret": "K6mT7ybBa35HbUBuJgOYWek53jMWw5BSXsWy0f3pQ8EgFnXUxIZk9Z6PrcUT037zL6e+pjCJxIViSTr78kH7InZ/2mOaP1bNc5bQ22yZReNwXSHUOtD1pUUmIzkaV7Lxuq+jssD1+0Rd/QTc9bomyQngSf6txQjiH/ckT5B9+Dc3QelVkKGt6pmFC6GlpyCW2YQavnkN8psCS5y691XkrM1ankEUw8e4HcKyF8+GqSsVt1hQtyV7fHkFFnmTHqcMWDMAwVG1leskBlH6lJAIcN+O02ixVlm+SYGbnXEFPgYGkelR0Hc3Sd9t6kdgYa6pdBVYLoL2wQpClsQKGgaIyVdJBxXhNKkRlFtAOuV3xPx+ykZc5dnOH4iQuwBX+SvaGYQY4xbwIzVt5nNfGrqHuiHma+E38UshhShMVhyUc7qbC+PtFVRHcMrqY5dEmHx4xB2vMoTFKV9Prgp315dPMX13SKuF03//AqWkGpG2/yjBYfZ6mq6ywK2m18rscK9IKc5ATbBBmODB4S1aNinuYX/H3UHOKWl3mycFKtrb2vet4muhHnnKuw9Y/3QCIo2+W89aFbIkh9V8MfGkvpmCRM3X1FLsV4mU8vBf7nTg6kI8SbrUmtF+bEU770LtO/hlk9/wquZPMgd+hHL33jyWFUW1Sc9cKiDXlPM0",
    "content": "gYxYeHU9/bcJyxUqqrUaPYHQRlKRJHus6x1Ifv9E1XoZ5QQ7FUym5g4elNiCrzKfBqSXV1iOdP0zDN+EwniLEvIRVzwFubxIqdps32KP4ZOjrRp2U+3JdMlw8SAiu0DERfDNkwVHhiNzG8fwMvV4FRj4U2yRB7Y=",
},
...

Before processing these two encryption, data must be decoded from base64 to raw bytes. Encrypted Secret can be decrypted using partner private key and the result will be sequence of 32 random bytes. Otherwise, Encrypted Content can only be decrypted using characters with length of 32 bytes secret key.

Secret Key​

Secret Key is sequence of random bytes that exactly have 32 bytes length as characters. This secret key can be obtained by decrypting secret field from the response using RSA OAEP 256.

You can try to encrypt secret using our script based on openssl that can be downloaded here. To use the script you should set the file as executeable using this command (use sudo if necessary) : 

chmod +x encrypt-secret.sh

Here is the example:

> ./encrypt-secret.sh test.public.txt 123456789012345678901234567890as

nrgcw7CSN/xStO8gt52dLAS9/GiRmB8yIgtOLh+NbA/4a335tBgfA/DJ66HWKCtgB2U3gh1+FuWCMjfPfLaPQkrMVcfMc2ocaLGk25FqRVjDtDTIHorUzAfMiRGWs3jSFbwepcfTDW0Cy3U5dKrTci/p4OmraJYaKUzgYxVFvLsCmDawkKrrtCBbp2U8ITefq3TJwCrbBnu4Tm4payqQCi2y01EGgczGmtcIP3jHxA0h8oo5dUojxF7VeA+weB5fCGT96spst8oSKb2+kh1ZnhjG+2YmNMAu2U0T/S3D9cY5ANuAnsIV1RK6SBqcVJhEOSfQpiVWgFAm4q24/T0EWzKbS0kScAwEkl0vVw7eimQh/al++c88sorLH6+T+K04aJDvnn0c4cSYBAOg6QRGd8yc9f5lE9DlpKMSJTbUPsRB2X7Dr4t6ILTIuX4LcoEGFzChLqbFQT0EEgYwdntqqEWtsslLhvA4T47J4nZ4FNVg70CHaK/8jxNiS/4OatXnBUNiVdwwtjlICmvSI2wU2R7HHYupbC5xJuu0YkvRM6z49rlEWyik+UEYjPt7yYModIwKTkfebiuQkuM0bvySHSwK8aYhdzN+iffq1tvK4Jd6idd1lSXOiNpaxRjBpCo4Xt7642pT7ycKbWYeNWcFlel+R3vDU3Bhli6P51hKMns=

Also we provide based on openssl to decrypt secret using our script that can be downloaded here. Make sure the openssl version is 1.1.1 or newer. To use the script you should set the file as executeable using this command (use sudo if necessary) :

chmod +x decrypt-secret.sh

After that you can run either command below:

./decrypt-secret.sh <private_key> <encypted_content> <optional:output_file>

Here is the example:

> ./decrypt-secret.sh test.private.txt pmhEIVuc+ZrrJalQolxyDITZo7PqnTzluZJnKJWEJzXOWgHpDpx+/ijstSJ0wQPllQcjoIJ7yG3Q7HTq6KEeH18VfmAfRCFIzm/pGeNYvckGxHmXJLaZvq4uZB3Nx2nh1WCGw4Zsxy9RLrGMm8IslvzM5T8i/8+cFoM9gvsk9WQq3vyc8j/8lwGE1lHvhD0dmxpKzTDGhP3h5M+H6VACTP77Kz1blO1Oyn/rE7xaqr+zWDEkq/OBSqvZrTxGpJbPt+GcJq9yqq8gQu0ks6h3SEcEtZRmO9kL/UY62XmMgKiQe+1sKO/fpIetDqf4/2Bf5C2SEF2X0BtBG47hC9oLwipgfPtjto8RBFpIcFxJgP75V39lBTAWIMXPNec7b+OWdx/4Fqdj9lvVJV8ez1WIBzCVUVRbBpxz6rbqv3sKhn2xHYkFNENniPLVRIkn1QgGO7HOe7H0yClWjEEoJsSIvxdqIXRAKqdtfLPDL8dSMxSqmjxfOn7fZ51N42JwLWH3bdhScVFpFekl4pXUIOHMjpXPvxPwF9s2s9VQtXO7f9i8f3K5qBOBXbeVmSch2kxF6V+y0gABCcJ8yuMOgYUKdq05aAecSm3UfNcej3ygRXrpeBpuwrG4zHh6Y4CVB2l5d5FnZBnU6uFP3UgeyUIkxw/pxfF8fDc9oNDjvx9koSU=

079423bc31698dbaf2d6f49973301b97

Message Content​

The second algoritm need the sequence of characters with the size of 32 bytes that already decrypted from previous algorithm. These characters are needed to create AES GCM cipher.

After decoding content field from the response to bytes, decoded bytes consist of two components Nonce / Initial Vector and Cipher Text.

  1. Nonce is suffix of decoded bytes from the last 12 bytes as random factor. Nonce will be used as material when decryption process.
  2. Cipher text is the the rest of the bytes excluding nonce. This is the main material in decryption process.

The materials to execute AES 256 GCM are cipher from secret key, cipher text, and nonce. The overall process can be slightly different depending on the programming language that was used by partner, but the materials and algorithm is absolute and standarize to get the right result.

Here is the sequence of each components:

decoded message = cipher text + nonce (12 bytes)

You can implement this algorithm in your system to get the correct message. Encryption message and secret key will be random each time they generate eventhough the real message is the same.

IMPORTANT NOTE For some library and/or programming language, e.g. PHP (minimum version 7.1) and Java, the required parameter need additional parameter called tag / mac. The length of this component is 16 bytes.

Here is the sequence of each components when using tag:

decoded message = cipher text + tag (16 bytes) + nonce (12 bytes)

You can download the example here

Decryption Process 101​

Decryption Process 101

Have a feedback?