What is Member Hash

This page describes the Member Hash of the ChannelIO SDK (hereafter referred to as SDK).

What is Member Hash?

Member Hash is a security feature that encrypts the user’s memberId using HMAC-SHA256 to allow only the appropriate user’s boot request. Channel strongly recommended the Member Hash to a user.

Due to the memberId used to boot must be unique and distinguishable, many customer companies use it such as a service ID or email. However, if using such an easy-predictable value is used as memberId. A third party also effortlessly infers another user's memberId.

In this case, a third party could boot the other user's information and steal sensitive information such as phone numbers or chat history.

🚧

Support for website builders

You can use the MemberHash feature on self-developed sites that have installed the SDK directly and on some builders (Cafe24, Makeshop, WordPress).
In general, builders have differences in interlink methods, making it difficult to set up Member Hash.
We are preparing to support some builders that can be set up.

QuickStart

  1. Clicks Channel settings > Security and Develop… > Security.
  2. Clicks [Lookup] to create a new secret key in the User password encryption section.
  3. Set the user's memberId to hash using HMAC-SHA256 as the issued secret key.
1280

❗️

You should be able to keep your secret key safe.

The generated secret key must be able to keep them safe.
We recommend generating the member hash, such as the service's backend server, and passing it to the client.

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 algorithm) {
  try {
    byte[] data = memberId.getBytes();
    SecretKey macKey = new SecretKeySpec(hexify(secretKey), algorithm);
    Mac mac = Mac.getInstance(algorithm);
    mac.init(macKey);
    byte[] digest = mac.doFinal(data);
    byte[] hexBytes = new Hex().encode(digest);
    return new String(hexBytes, StandardCharsets.UTF_8);
  } catch (InvalidKeyException | NoSuchAlgorithmException e) {
    throw new SystemException(e).error(log);
  }
}

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


String memberId = "lucas";
String secretKey = "4629de5def93d6a2abea6afa9bd5476d9c6cbc04223f9a2f7e517b535dde3e25";
String expectedHash = "99427c7bba36a6902c5fd6383f2fb0214d19b81023296b4bd6b9e024836afea2";
String hash = HMACUtil.encode(memberId, secretKey, "HMACSHA256")
$expectedHash = hash_hmac('sha256', 'lucas', pack("H*", '4629de5def93d6a2abea6afa9bd5476d9c6cbc04223f9a2f7e517b535dde3e25'));

// $expectedHash = '99427c7bba36a6902c5fd6383f2fb0214d19b81023296b4bd6b9e024836afea2';

Expected Behavior of Member Hash

When using Member Hash

- Boot as a member user
You must provide the user's memberId and hashed memberId value in the boot request. Channel checks
whether this member hash is a value appropriately generated via HMAC-SHA256.
If it is different from the expected value after checking, you will receive an unauthenticated Error of
BootStatus as a response.

- Boot as an anonymous user
Boot without memberId and memberHash value.

When do not use Member Hash

The memberHash value in bootConfig is ignored.
Boot process does not verify any values.

How to check the secret key and member hash value

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 must activate after completing all Channel SDK settings. SDK may not work if you activate the Member Hash without completing the installation.
  • If the secret key is exposed, reissue it and setup via QuickStart.