Article

Decrypting the Authentication Token

Learn how Business Chat decrypts an authentication token.

Overview

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 eciesEncryptionCofactorVariableIVX963SHA256AESGCM algorithm.

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

BNY+I93aHVkXnNWKVLdrMJLXpQ1BsyHYoiv6UNi4rDUsRx3sNNhW8FNy9yUwxYprAwwfj1ZkoJ61Fs+SwjIbGPtXi52arvSbPglyBN4uAxtP3VP3LCP4JtSEjdgsgsretA==

Private Key

pX/BvdXXUdpC79mW/jWi10Z6PJb5SBY2+aqkR/qYOjqgakKsqZFKnl0kz10Ve+BP

Encrypted Authentication Token

BDiRKNnPiPUb5oala31nkmCaXMB0iyWy3Q93p6fN7vPxEQSUlFVsInkJzPBBqmW1FUIY1KBA3BQb3W3Qv4akZ8kblqbmvupE/EJzPKbROZFBNvxpvVOHHgO2qadmHAjHSmnxUuxrpKxopWnOgyhzUx+mBUTao0pcEgqZFw0Y/qZIJPf1KusCMlz5TAhpjsw=

To decrypt the authentication token, use the following steps:

  1. Extract the ephemeral public key from the encrypted data.

  2. Derive the public numbers from the ephemeral public key.

  3. Obtain a shared key using an Elliptic Curve Cyrptopgraphy Cofactor Diffie-Hellman (ECC CDH).

  4. Generate the derived key and initial vector by running the shared key through the X9.63 Key Derivation Function with SHA256 hash function.

  5. 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.

Exercise

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:

  • BDiRKNnPiPUb5oala31nkmCaXMB0iyWy3Q93p6fN7vPxEQSUlFVsInkJzPBBqmW1FUIY1KBA3BQb3W3Qv4akZ8kblqbmvupE/EJzPKbROZFBNvxpvVOHHgO2qadmHAjHSg==

Derive the binary for the encrypted data portion and Base64-encode it. The resulting encrypted data string is:

  • afFS7GukrGilac6DKHNTH6YFRNqjSlwSCpkXDRj+

The Base64-encoded encryption tag is:

  • pkgk9/Uq6wIyXPlMCGmOzA==

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.

Exercise

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:

  • x=8706462696031173094919866327685737145866436939551712382591956952075131891462487598200779332295613073905587629438229

  • y=10173258529327482491525749925661342501140613951412040971418641469645769857676705559747557238888921287857458976966474

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:

  • 2lvSJsBO2keUHRfvPG6C1RMUmGpuDbdgNrZ9YD7RYnvAcfgq/fjeYr1p0hWABeif

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:

  • mAzkYatDlz4SzrCyM23NhgL/+mE3eGgfUz9h1CFPhZM=

The last 16-bytes serve as the IV:

  • rV3qrszd0PMPgeRhNnlOYA==

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:

  • afFS7GukrGilac6DKHNTH6YFRNqjSlwSCpkXDRj+

and the IV from Generate the Derived Key and Initial Vector:

  • rV3qrszd0PMPgeRhNnlOYA==

to perform a message authentication code (MAC) validation, include the encryption tag from Extract and Confirm the Ephemeral Public Key:

  • pkgk9/Uq6wIyXPlMCGmOzA==

This yields a plain text string token that you can use for authentication:

  • xXTi32iZwrQ6O8Sy6r1isKwF6Ff1Py

Troubleshooting

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.

See Also

Advanced Authentication

Using Password AutoFill to Authenticate Users

Provide customers with an easy solution to perfom authentication on their iOS devices.