Learn how Business Chat decrypts an authentication token.
To authenticate users, you need to decrypt their encrypted authentication token from the response. The authentication token should include the following:
A 384-bit elliptic curve secp384r1 public key specified in the authenticate request.
An encrypted authentication token, for use by the Customer Service Platform (CSP). You can create the token on the customer's device using the
Encryption Cofactor Variable IVX963SHA256AESGCM
The business or CSP uses the associated private key generated for the request to decrypt and obtain the clear text authentication token.
For more information on authentication, see Sending an Authentication Message.
About the Authentication Token
When a customer successfully completes authenticating with a business, the CSP receives an authentication token. This token includes encrypted information and requires a decryption procedure to retrieve the information to determine the authenticity of the customer.
The authentication token is a Base64-encoded string contained in the JSON payload returned by the interactive message from the Business Chat server. You can find it nested in the interactiveData/data/authenticate/token folder.
The authentication token uses the Elliptic Curve Integrated Encryption Scheme (ECIES). There are several versions for ECIES and keys, and encrypted data are not always compatible between versions. Some applications use a derivative or a subset of a version, so they may not be compatible with other implementations.
Business Chat uses the secp384r1 curve for generating public/private key pairs, and X9.63 for encoding the public keys. Libraries compatible with these standards are available across many languages and platforms.
Before developing the production code for your implementation, you should understand the concepts of encryption and be familiar with the libraries to handle these items on your platform. Some libraries have an abstract cryptographic library that requires deep understanding in order to apply the correct algorithm and parameters. Other libraries implement many methods and are fairly straightforward to use, but require a great deal of research to determine a suitable method for a particular application. Understand these concepts before you begin your production code.
You should validate the compatibility of your particular implementation with the standards by building a comprehensive test. You should also review your implementation with information security experts. It is recommended to perform a security review with an independent security team before deployment.
Decrypt the Authentication Token
In this decryption exercise, you use a Base64-encoded binary data and an X9.63-encoded uncompressed public key. The unsigned scalar private key example has been converted to bytes. The private key is not sent in the request, so businesses can choose any encoding format.
Use the following values so that you can follow along with the exercises. You can use the immediate mode on your favorite language or write sample code on your platform.
- Public Key
HVk Xn NWKVLdr MJLXp Q1Bsy HYoiv6UNi4r DUs Rx3s NNh W8FNy9y Uwx Ypr Awwfj1Zko J61Fs+Swj Ib GPt Xi52arv Sb Pgly BN4u Axt P3VP3LCP4Jt SEjdgsgsret A==
- Private Key
X/Bvd XXUdp C79m W/j Wi10Z6PJb5SBY2+aqk R/q YOjqgak Ksq ZFKnl0kz10Ve+BP
- Encrypted Authentication Token
RKNn Pi PUb5oala31nkm Ca XMB0iy Wy3Q93p6f N7v Px EQSUl FVs Ink Jz PBBqm W1FUIY1KBA3BQb3W3Qv4ak Z8kblqbmvup E/EJz PKb ROZFBNvxpv VOHHg O2qadm HAj HSmnx Uuxrp Kxop Wn Ogyhz Ux+m BUTao0pc Egq ZFw0Y/q ZIJPf1Kus CMlz5TAhpjsw=
To decrypt the authentication token, use the following steps:
Extract the ephemeral public key from the encrypted data.
Derive the public numbers from the ephemeral public key.
Obtain a shared key using an Elliptic Curve Cyrptopgraphy Cofactor Diffie-Hellman (ECC CDH).
Generate the derived key and initial vector by running the shared key through the X9.63 Key Derivation Function with SHA256 hash function.
Perform an AES-GCM decryption using the encrypted data string and initialization vector (IV) obtained in step 4.
The following sections take you through the process of decrypting the authentication token, as detailed in the previous steps.
Extract and Confirm the Ephemeral Public Key
Extract the ephemeral public key from the encrypted data. The authentication token contains several parts:
Byte 0 is 0x04 and indicates an uncompressed key form.
Bytes 0...96 are the ephemeral public key. Note that 0-byte is part of the ephemeral public key in addition to indicating the uncompressed form.
Bytes 97...n-16 are the encrypted data, where n is the length of the authentication token.
Bytes n-15...n-1 are the encryption tag.
When you compute the key on the secp384r1 curve, the key data is 96 bytes (384/8 * 2). The x and y coordinates can have up to 384-bytes.
First, Base64-decode the authentication token string. This results in a 142-byte binary which is the actual authentication token. The first byte, 0x04, indicates the key in an uncompressed form.
Use the Base64 library and binary object manipulation library for your language and platform. Base64-encode the ephemeral public key from the binary form. The following uncompressed ephemeral key should result:
RKNn Pi PUb5oala31nkm Ca XMB0iy Wy3Q93p6f N7v Px EQSUl FVs Ink Jz PBBqm W1FUIY1KBA3BQb3W3Qv4ak Z8kblqbmvup E/EJz PKb ROZFBNvxpv VOHHg O2qadm HAj HSg==
Derive the binary for the encrypted data portion and Base64-encode it. The resulting encrypted data string is:
FS7Gukr Gilac6DKHNTH6YFRNqj Slw SCpk XDRj+
The Base64-encoded encryption tag is:
Save the encrypted data string and tag as these are used in Perform an AES-GCM Decryption.
Derive the Public Numbers
Derive the public numbers from the public key. The public numbers are the x and y coordinates of the elliptic curve used in the encryption process. Use a method within the cryptographic library on your platform to derive these values.
Some libraries pass the secp384r1 curve to the routine as a parameter along with the public key. Other libraries have a method for the secp384r1 that accepts the public key as a parameter. Familiarize yourself with the cryptographic library and apply the best method to this step.
Pass the secp384r1 curve and the ephemeral public key into your cryptography library method for deriving the public numbers.
Continuing from the values in the previous section, you should receive the following two coordinates:
Obtain the Shared Key Using the ECC CDH
To obtain the shared key, perform an ECC CDH operation using the ephemeral public key and the private key. You should get the following shared key after using the ECC CDH operation:
SJs BO2ke UHRfv PG6C1RMUm Gpu Dbdg Nr Z9YD7RYnv Acfgq/fje Yr1p0h WABeif
Generate the Derived Key and Initial Vector
Run the shared key through the X9.63 Key Derivation Function with SHA256 hash function. This results in a 48-byte payload.
Use the initialization vector to perform the decryption in Perform an AES-GCM Decryption.
The first 32-bytes yields the derived key, for this exercise:
Azk Yat Dlz4Szr Cy M23Nhg L/+m E3e Ggf Uz9h1CFPh ZM=
The last 16-bytes serve as the IV:
V3qrszd0PMPge Rh Nnl OYA==
Perform an AES-GCM Decryption
Refer back to the saved values from the first step, Extract and Confirm the Ephemeral Public Key. Use the following encrypted data string:
FS7Gukr Gilac6DKHNTH6YFRNqj Slw SCpk XDRj+
and the IV from Generate the Derived Key and Initial Vector:
V3qrszd0PMPge Rh Nnl OYA==
to perform a message authentication code (MAC) validation, include the encryption tag from Extract and Confirm the Ephemeral Public Key:
Iy XPl MCGm Oz A==
This yields a plain text string token that you can use for authentication:
XTi32i Zwr Q6O8Sy6r1is Kw F6Ff1Py
Decryption fails if the keys or associated tag derived in Generate the Derived Key and Initial Vector are incorrect. Failed decryptions result in rejected tokens, including the associated tag validation.