文字列のエンコードとハッシュ

Studioには、スクリプト内でデータのエンコードやハッシュに使用できる関数がいくつか用意されています。エンコードもハッシュも、データを別の形式に変換します。ただし、データの変更方法とそのデータの用途は異なります。

• エンコード：このプロセスは、スクリプトで使用したり、スクリプトから他のシステムに渡したりできる形式にデータを変換します。エンコードでは、スキーム（通常は一般に公開されているメソッド）を使用します。そのため、変換は安全ではありません。しかし、エンコードの目的はデータを安全にすることではなく、受信側のシステムで適切に使用できるようにすることです。エンコードでは、データを逆変換して元の形式に戻すことが可能です。
• ハッシュ：データを固定長の英数字文字列に変換する一方向の処理です。ハッシュ化された文字列はハッシュと呼ばれることもあります。ハッシュはデータの完全性を検証するためによく使われます。2つの同じ文字列を同じアルゴリズムでハッシュ化すると、それらのハッシュは同一になります。同じアルゴリズムで作成された2つのハッシュが一致しない場合、元の文字列も異なることがわかります。このプロセスは、機密データをプレーンテキストで渡すことなく、デジタル署名やパスワードなどのセキュリティデータを検証するために使用できます。

さらに、StudioではOAuthを使った認証もサポートされています。これにより、CXoneと他のシステム間のやりとりにセキュリティを提供することができます。

RestProxy

Studioで文字列のエンコードとハッシュ化を行うには、スクリプトでRESTful APIにアクセスできるサービスRestProxyを使用する必要があります。このサービスは、エンコードやハッシュに使用する関数へのアクセスも提供します。文字列をエンコードやハッシュ化するときに使用できる関数のスニペット例には、すべてRestProxyにアクセスする次のステートメントが含まれています。

ASSIGN restProxy = new UCN.Data.RESTProxy()

変数代入の際に、UCN.Data.RESTProxy()を説明のとおり正確に記述することが重要です。RESTProxy()は、データのエンコードやハッシュを行う関数にアクセスするための関数です。

例

スクリプトで使用できるよう、各関数のSnippetコード例が用意されています。コードは、このヘルプページの各関数を説明するテーブルからもコピーできます。

1. スクリプト例のZIPファイルをダウンロードします。
2. ZIPファイルのコンテンツを解凍します。次の2つのスクリプトが含まれています。

   • EncodeAndHashScriptExample.xmlには、関数をテストできるスクリプト例が含まれています。

   • ExampleSnippetActions.xmlには、このページの各アルゴリズムに対応するスニペットアクションが1つずつ含まれています。各スニペットには、その関数のサンプルコードが含まれています。

3. 両方のXMLファイルをStudioにインポートします。
4. ExampleSnippetActions.xmlファイルのスニペットアクションから、使用する関数のスニペットコードをコピーします。
5. コピーしたコードをEncodeAndHashScriptExample.xmlファイルのスニペットアクションに貼り付けます。
6. シミュレートされたインタラクションを設定し、Start with Traceをクリックします。スニペットエディターウィンドウでデバッガを使用することもできます。どちらのオプションでも、スニペット内の変数の内容の変化を確認できます。

文字列をエンコードする関数

エンコードはデータを別の形式に変換します。大量のデータを伝送する場合や、使用しているプロトコルでは転送できないデータを伝送する場合に使用できます。エンコードされたデータは、元の形式に変換することが可能です。

文字列のエンコードに使える関数は2つあります。どちらもBase64スキームを使ってデータをエンコードします。

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodeThis = "This is the source data."
ASSIGN hashB64 = restProxy.EncodeBase64(encodeThis) 

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodeThis = "https://example.com"
ASSIGN hashB64url = restProxy.EncodeBase64Url(encodeThis) 

文字列をデコードする関数

この関数を使用して、EncodeBase64関数でエンコードされた文字列をデコードします。

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN encodedString = "234sdf"
ASSIGN decodedString = restProxy.DecodeBase64(encodedString) 

文字列を秘密鍵でハッシュ化する関数

ハッシュ関数は、数学的な計算によって固定長の出力文字列を生成します。この出力文字列はハッシュと呼ばれ、ハッシュ化されたデータの真正性を確認するのに役立ちます。ハッシュ関数は、パスワードやデジタル署名などの検証に使用できます。たとえば、パスワードをハッシュ化したものを保存することができます。ユーザーがパスワードを入力した時点でそれをハッシュ化し、保存しておいたパスワードのハッシュ化したバージョンと比較できます。両者が同じであれば、これは正しいパスワードです。

このセクションで説明するハッシュ関数は、すべて鍵付きのハッシュアルゴリズムです。これらはHMAC（ハッシュベースのメッセージ認証コード）アルゴリズムを使用しています。各アルゴリズムは、特定の長さのハッシュ出力を生成します。HMACアルゴリズムは、ハッシュ化された出力を生成するために、秘密鍵とハッシュ関数の組み合わせを使用します。HMACのプロセスは以下のとおりです。

1. 秘密鍵とメッセージデータを混合します。
2. その結果をハッシュ関数でハッシュ化します。
3. ハッシュ値を再び秘密鍵と混合します。
4. ハッシュ関数をもう一度適用します。

ハッシュ関数は一方通行です。つまり、元に戻すことはできません。このため、これらの関数をデータの暗号化に使うことはできません。このセクションのハッシュ関数と同じように、暗号化でも鍵が使われます。ただし、暗号化の場合、アルゴリズムにハッシュアルゴリズムは含まれておらず、元に戻すことができます。Studioは、暗号化関数を提供しません。

鍵を入手して受信側のエンティティやシステムと共有するのは、各組織の責任となります。

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS256 = restProxy.EncodeHS256(hashThis, key) 

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS256NoB64= restProxy.EncodeHS256NoBase64Encoding(hashThis, key) 

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS384= restProxy.EncodeHS384(hashThis, key) 

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS512 = restProxy.EncodeHS512(hashThis, key) 

トークンとOAuthによる認証のための関数

OAuthおよびJSONWebTokens（JWT、またはトークン）によるトークンベースの認証は、アプリケーションに認証フローを組み込むための2つの標準です。これらを併用すると、クライアントアプリケーションがユーザー情報を効率的に検証できるようになります。認証サーバーがOAuth経由でユーザーの認証情報の確認に成功した場合、クライアントアプリケーションにもユーザー情報を送信する必要があります。

これらの関数を使用するには、認証サーバーを用意しなければなりません。トークンを使用する場合、OAuthサーバーは認証フローが完了した後にトークンをクライアントアプリケーションに送信します。トークンにはエンドユーザーの情報が含まれています。

スクリプトで使用可能な関数は、ユーザー認証とクライアント認証のためのOAuth標準と、HMACSHA256ハッシュアルゴリズムを組み合わせたものです。OAuth標準はRFC7523で定義されていて、Studioの関数名に含まれています。

Studioスクリプトで以下の関数を使用すると、OAuthとトークンを使用した認証フローを組み込むことができます。

• RFC7523GrantWithHS256(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

• RFC7523GrantWithHS256Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

• RFC7523GrantWithHS384(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

• RFC7523GrantWithHS384Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

• RFC7523GrantWithHS512(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData)

• RFC7523GrantWithHS512Extended(apiUrl, key, iss, sub, aud, jwtHeaderData, jwtPayloadData, queryParams, requestHeaders)

トークンには、ヘダー、ペイロード、署名の3つの部分があります。これらの関数には多くのパラメーターがあり、各部分を作成するために使用されるデータを提供します。以下の表にパラメーターの定義を示します。

サンプルスクリプトのスニペットアクションには次のコードが含まれています。

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN key = "key"
ASSIGN url = "https://example.com"
ASSIGN iss = "some issuer"
ASSIGN sub = "some subscriber"
ASSIGN aud = "some audience"

DYNAMIC headerData
DYNAMIC payloadData
DYNAMIC queryParams //only in the Extended functions
DYNAMIC requestHeaders //only in the Extended functions
payloadData.ist=155533969
payloadData.exp=155533969

ASSIGN hash=restProxy.RFC7523GrantWithHS256(url, key, iss, sub, aud, headerData, payloadData)
ASSIGN hash=restProxy.RFC7523GrantWithHS256Extended(url, key, iss, sub, aud, headerData, payloadData, queryParams, requestHeaders)	

サンプルスクリプトには、使用可能な各関数のためのコードがあります。この例では、利用可能な6つの関数のうち2つだけを扱います。