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

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

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

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

このページでは、文字列をエンコードまたはハッシュしたり、Studioで認可フローを設定したりするために、OAuthスクリプトで使用できる関数について説明します。 これらのソリューションの実装方法に関する情報は提供していません。 これらの関数が使用するアルゴリズムの詳細については、インターネット技術タスクフォース（IETF）のウェブサイトを参照してください。

ハッシュを元に戻すことはできません。 文字列をハッシュ化する関数は慎重に使用し、本番のデータで使用する前に実装方法を理解しておくことが必要です。

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つのSnippetアクションが含まれます。 各Snippetには、その関数のサンプルコードが含まれています。

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

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

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

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

関数名 説明
EncodeBase64(string)

一部のプロトコルではバイナリデータを転送できません。 この関数を使用すると、stringパラメーターで渡されたバイナリデータを転送可能な形式に変換することができます。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

Base64関数は、ウェブアプリケーションのURLをエンコードするために使用できます。 ただし、エンコードに使用される3つの特殊文字があり、URLではこれらを異なる方法で解析する必要があります。 特殊文字とは、プラス記号（+）、フォワードスラッシュ（ /）、等号（ = ）です。 EncodeBase64Url関数を使用すると、URLパラメーターの引数として渡されたURLを適切にエンコードできます。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

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

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

関数名 説明
DecodeBase64 (string)

この関数は、エンコードされたデータ（string）を元の形式に戻します。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

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

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

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

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

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

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

秘密鍵のセキュリティは十分保護してください。 鍵を紛失した場合、その鍵でハッシュ化されたデータはすべて使用できなくなります。 同一の文字列であっても、2つの異なる鍵でハッシュ化された文字列を比較することはできません。

関数名 説明
EncodeHS256(stringText, secretKey)

この関数はHMACSHA256を使用します。これはSHA-256ハッシュアルゴリズムから構築された鍵付きハッシュアルゴリズムで、ハッシュベースのメッセージ認証コード（HMAC）として使用されます。 Base64エンコーディングが含まれます。 これは、ソースデータstringText とsecretKeyからなる256ビット長のハッシュ化された出力を生成します。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

この関数は、Base64エンコーディングを含まないことを除けば、EncodeHS256と同じです。 ハッシュ化された出力は、ソースデータstringText とsecretKeyから構成されます。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

この関数は、SHA-384ハッシュアルゴリズムから構築され、ハッシュベースのメッセージ認証コード（HMAC）として使用される鍵付きハッシュアルゴリズム、HMACSHA384を使用します。 これは、ソースデータstringText とsecretKeyからなる384ビット長のハッシュ化された出力を生成します。

スクリプト例のSnippetアクションには、このコードが含まれています：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS384= restProxy.EncodeHS384(hashThis, key)
EncodeHS512(string Text, secretKey) この関数は、SHA-512ハッシュアルゴリズムから構築され、ハッシュベースのメッセージ認証コード（HMAC）として使用される鍵付きハッシュアルゴリズム、HMACSHA512を使用します。 これは、ソースデータstringText とsecretKeyからなる512ビット長のハッシュ化された出力を生成します。

スクリプト例のSnippetアクションには、このコードが含まれています：

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

公開鍵と秘密鍵のペアで文字列をハッシュ化する関数

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

これらの関数は、RSAとSHAアルゴリズムを使用します。 RSAは、公開鍵と秘密鍵のペアを使用する暗号アルゴリズムのセットです。 SHAは、ハッシュアルゴリズムのセットです。 これらを組み合わせて固定長のハッシュを生成します。 サポートされている関数は3つあり、それぞれが異なる長さのハッシュを生成します。 秘密鍵はハッシュの生成に使われます。 公開鍵はそれを検証するために使われます。

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

このセクションで説明するハッシュ関数はすべて、CXoneビジネスユニット閉じた CXone環境におけるテクニカルサポート、請求、およびグローバル設定を管理するために使用される上位レベルの組織グループでSSL証明書を生成してインストールする必要があります。 証明書には、これらの関数が使用する公開鍵と秘密鍵が含まれています。 このプロセスについてのサポートは、アカウント担当者までお問い合わせください。

このオプションは、お使いのシステムに証明書を設定するために、CXoneからの支援が必要です。 詳細はアカウント担当者にお問い合わせください。

このセクションのハッシュ関数は、Studioのスニペットデバッガーでは使用できません。 スニペットデバッガーは、CXoneシステムにある証明書にアクセスできず、エラーを返します。 これらの関数をテストするには、必要な証明書にアクセスできるスクリプトでトレースを実行する必要があります。

関数名 説明
EncodeRS256(stringText)

この関数は、RSA Signature with SHA-256とも呼ばれるRS256アルゴリズムを使用します。 出力されるハッシュの長さは、使用する秘密鍵の長さに依存します。 ハッシュは、ソースデータstringText と、CXoneでインストールしたSSL証明書の一部である秘密鍵で構成されます。

スクリプト例のSnippetアクションには、このコードが含まれています：

ASSIGN restProxy = new UCN.Data.RESTProxy()
restProxy.SetCertificateSerialNumber("[serialNumber]")
ASSIGN hashThis = "This is the source data."
ASSIGN hashRS256= restProxy.EncodeRS256(hashThis)
EncodeRS384(stringText)

この関数は、RSA Signature with SHA-384としても知られるRS384アルゴリズムを使用します。 出力されるハッシュの長さは、使用する秘密鍵の長さに依存します。 ハッシュは、ソースデータstringText と、CXoneでインストールしたSSL証明書の一部である秘密鍵で構成されます。

スクリプト例のSnippetアクションには、このコードが含まれています：

ASSIGN restProxy = new UCN.Data.RESTProxy()
restProxy.SetCertificateSerialNumber("[serialNumber]")
ASSIGN hashThis = "This is the source data."
ASSIGN hashRS384= restProxy.EncodeRS384(hashThis)
EncodeRS512(stringText)

この関数は、RSA Signature with SHA-512としても知られるRS512アルゴリズムを使用します。 出力されるハッシュの長さは、使用する秘密鍵の長さに依存します。 ハッシュは、ソースデータstringText と、CXoneでインストールしたSSL証明書の一部である秘密鍵で構成されます。

スクリプト例のSnippetアクションには、このコードが含まれています：

ASSIGN restProxy = new UCN.Data.RESTProxy()
restProxy.SetCertificateSerialNumber("[serialNumber]")
ASSIGN hashThis = "This is the source data."
ASSIGN hashRS512= restProxy.EncodeRS512(hashThis)

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

OAuthとJSON Webトークンを使用したトークンベースの認証（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つの部分があります。 これらの関数には多くのパラメーターがあり、各部分を作成するために使用されるデータを提供します。 以下の表にパラメーターの定義を示します。

パラメーター タイプ 説明
apiURL 文字列 接続先のAPIエンドポイントのURL。
key 文字列 この関数でハッシュする際にスクリプトで使用する秘密鍵。
iss 文字列 トークンの発行者。
sub 文字列 トークンのサブジェクト。
aud 文字列 トークンの使用者。 通常はクライアントがアクセスを希望する認証サーバーです。
jwtHeaderData ダイナミックデータ トークンのヘダーに含めたいデータ。
jwtPayloadData ダイナミックデータ トークンに含める必要のあるペイロードを保持するキーと値のペア。 トークンの有効期限を含めることができます。 以下のサンプルスニペットでは、payload.expとなっています。
queryParams ダイナミックデータ トークンに含めるクエリパラメーターを保持するキーと値のペア。 これは拡張関数にのみ含まれます。
requestHeaders ダイナミックデータ リクエストヘダー情報を保持するキーと値のペア。 これは拡張関数にのみ含まれます。

スクリプト例のSnippetアクションには、このコードが含まれています：

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つだけを扱います。