This page describes the Member Hash feature.

What is Member Hash?

Member Hash is a security feature that prevents unauthorized users from booting SDK by hashing memberId using HMAC-SHA256. We highly recommend enabling the Member Hash feature for your Channel.

Since it is crucial for the memberId used for booting to be unique and distinguishable, it is common practice to use the service ID or email as the user's memberId. Using such easily-predictable values as memberId may let malicious third-party users to compromise the ID and gain access to a user's chat histories and contact information.

🚧

Support for website builders

You can utilize the Member Hash feature on self-hosted websites with manually installed SDKs, as well as on websites hosted by some website builder providers, such as Cafe24, Makeshop, and WordPress.

For other website builder providers, we are actively working on expanding the integration of Member Hash.

QuickStart

1. Navigate to Channel settings > Security and Development > Security.
2. Click [Lookup] to see a new secret key in the User password encryption section.
3. Hash the user's memberId with HMAC-SHA256 using the secret key.

❗️

Keep the secret key secure

The secret key should be stored in a location inaccessible to the client. If a client is responsible for creating a member hash from the memberId, a malicious user might attempt to generate a member hash using the secret key. We recommend generating the member hash from a place where the secret key is kept hidden from public such as a backend server, and sending the generated member hash to the client without exposing the secret key.

Example of HMAC hashing

Below we provide examples of memberId hashing in four languages (JavaScript, Python, Java, and PHP).

Glossary of Terms

• memberId : The identification of User
• secretKey : A secret key issued by channel
• expectedHash : The expected value that encoded memberId via secret key.

const crypto = require('crypto');

const memberId = 'lucas';
const secretKey = '4629de5def93d6a2abea6afa9bd5476d9c6cbc04223f9a2f7e517b535dde3e25';
const expectedHash = "99427c7bba36a6902c5fd6383f2fb0214d19b81023296b4bd6b9e024836afea2";

const hash = crypto.createHmac('sha256', Buffer.from(secretKey, 'hex'))
                .update(memberId)
                .digest('hex');

import hmac
import hashlib
import binascii

member_id = "lucas"
secret_key = "4629de5def93d6a2abea6afa9bd5476d9c6cbc04223f9a2f7e517b535dde3e25"
expected_hash = "99427c7bba36a6902c5fd6383f2fb0214d19b81023296b4bd6b9e024836afea2"
hash = hmac.new(
    binascii.unhexlify(bytearray(secret_key, "utf-8")),
    msg=member_id.encode('utf-8'),
    digestmod=hashlib.sha256
).hexdigest()

public static String encode(String memberId, String secretKey, String algorithms) {
  try {
    Mac mac = Mac.getInstance(algorithms);
    mac.init(new SecretKeySpec(hexify(secretKey), algorithms));

    byte[] hash = mac.doFinal(memberId.getBytes());

    StringBuilder sb = new StringBuilder(hash.length * 2);
    for (byte b: hash) {
      sb.append(String.format("%02x", b));
    }

    return sb.toString();
  }catch (Exception e) {
    throw new RuntimeException(e);
  }
}

private static byte[] hexify(String string) {
  return DatatypeConverter.parseHexBinary(string);
}

$expectedHash = hash_hmac('sha256', 'lucas', pack("H*", '4629de5def93d6a2abea6afa9bd5476d9c6cbc04223f9a2f7e517b535dde3e25'));

// $expectedHash = '99427c7bba36a6902c5fd6383f2fb0214d19b81023296b4bd6b9e024836afea2';

Expected Behavior of Member Hash

When Member Hash is enabled for your Channel

- Boot as a member user

You must include both the user's memberId and its corresponding hashed value in the boot request. The Channel will verify whether the provided member hash was correctly generated using HMAC-SHA256. If the hash does not match the expected value, the response will result in an 'unauthenticated error' as a BootStatus.

- Boot as an anonymous user
If you intend to boot as an anonymous user, do not include both memberId and memberHash values.

When Member Hash is disabled for your Channel

The memberHash value in bootConfig is ignored. Any verification process is skipped.

Lookup secret key and verify generated member hash

You can find the secret key in Channel Settings > Security & Development > User Data Encryption. Click the Lookup button to retrieve the secret key.

• You can reissue the secret key through the refresh button on the right side of the text field.
• By clicking "Check your member hash", you can verify that the hash value of a member is appropriately encoded with a given secret key.

Troubleshooting

• Member Hash should be activated after all end-users finishes their update of Channel SDK to a version that have completed member hash settings. SDK will stop its functionality if member hash is not set up.
• If the secret key is compromised, see QuickStart to revoke.