編碼和雜湊字串

Studio 支援可用於在指令碼中對資料進行編碼或雜湊的幾個函數。編碼和雜湊都會將資料轉換為不同的格式。資料變更的方式和您可以用它做什麼是相互不同：

  • 編碼：此過程將資料轉換為可在指令碼中使用或由指令碼傳遞給其他系統的格式。編碼使用一種模式或方法，其通常是公開可用。正因如此，這種轉換並不安全。然而，編碼的目的不是保護資料，而是確保可以在接收系統上正確使用資料。可以反轉編碼以將資料返回到其原始格式。
  • 雜湊：此單向過程可以將資料轉換為固定長度的英數字串。雜湊字串有時稱為雜湊。雜湊通常用於驗證資料的完整性。當使用相同的演算法雜湊兩個相同的字串時，它們的雜湊相同。如果使用相同演算法建立的兩個雜湊不相符，您就知道原始字串也不同。此過程可用於驗證資料的完整性，例如數位簽名或密碼，而不必以純文字形式傳遞敏感性資料。

此外，Studio 支援使用 OAuth 進行授權。這是一種為 CXone 和其他系統之間的互動提供安全性的方法。

本頁提供了關於您可以在Studio指令碼中使用的函數的資訊，以編碼或雜湊字串，或用 OAuth 設定授權。它不提供關於如何實作這些解決方案的資訊。關於這些函數使用的演算法的更多資訊，請參考 Internet 工程任務編組 (IETF) 網站。

雜湊是不可逆。謹慎使用任何雜湊字串的函數，並確保在對即時資料使用函數之前了解如何實現函數。

RestProxy

Studio 中編碼和雜湊需要使用 RestProxy，此服務允許您透過指令碼存取 RESTful API。它還為您提供了存取用於編碼和雜湊的函數的權限。編碼或雜湊字串時可以使用的函數的 snippet 範例都包含以下陳述，其可存取 RestProxy：

ASSIGN restProxy = new UCN.Data.RESTProxy()

重要的是必須完全按照所示在變數指派中包括 UCN.Data.RESTProxy()。RESTProxy() 是允許存取用於編碼和雜湊資料的函數。

範例

提供了每個函數的 Snippet 代碼範例，供您在指令碼中使用。還可以從描述每個函數的表中的此説明頁中複製代碼。

  1. 下載指令碼範例的 ZIP 檔案。
  2. 解壓縮 ZIP 檔案的內容。它包含兩個指令碼檔案：

    • EncodeAndHashScriptExample.xml，其中包含一個範例指令碼，您可以在其中測試函數。

    • ExampleSnippetActions.xml，其中包含本頁上每個演算法的一個 Snippet 動作。每個 Snippet 含該函數的範例代碼。

  3. 將兩個 XML 檔案匯入 Studio。
  4. 從要使用的函數的 ExampleSnippetActions.xml 檔案中的 Snippet 動作複製 snippet 代碼片段。
  5. 將複製的代碼粘貼入 EncodeAndHashScriptExample.xml檔案中的 Snippet 動作。
  6. 設定模擬的互動並點擊 Start with Trace。您還可以在 Snippet 編輯器視窗中使用偵錯程式。這兩個選項都允許您查看 snippet 中變數的變更內容。

對字串進行編碼的函數

編碼會將資料轉換為不同的格式。您可以使用它來傳輸大量資料，或者傳輸當前所用的通訊協定無法傳輸的資料。可以將編碼後的資料轉換回其原始格式。

有兩個函數可以用來對字串進行編碼。兩者都使用 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 函數可用於對 Web 應用程式中的 URL 進行編碼。但是，在編碼中使用的三個特殊字元必須在 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不提供任何加密功能。

您的組織有責任獲取金鑰並將其與接收實體或系統共用。

保護秘密金鑰的安全。如果金鑰遺失，所有與之雜湊的資料都將不再可用。您不能比較透過兩個不同金鑰雜湊的字串，即使字串是相同的。

函數名稱 描述
EncodeHS256(stringText, secretKey)

該函數使用 HMACSHA256，這是一種由 SHA-256 雜湊演算法構建的含有金鑰的雜湊函數演算法，用作雜湊訊息鑒別碼 (HMAC) 使用。它產生長度為 256 位的雜湊輸出，其由來源資料 stringText 和 secretKey 組成

範例指令碼中的 Snippet 動作包含此代碼：

ASSIGN restProxy = new UCN.Data.RESTProxy()
ASSIGN hashThis = "This is the source data."
ASSIGN key = "mykey"
ASSIGN hashHS256 = restProxy.EncodeHS256(hashThis, key)
EncodeHS256NoBaseEncoding(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)

該函數使用 HMACSHA384，這是一種由 SHA-384 雜湊演算法構建的含有金鑰的雜湊函數演算法，用作雜湊訊息鑒別碼 (HMAC) 使用。它產生長度為 384 位的雜湊輸出，其由來源資料 stringText 和 secretKey 組成

範例指令碼中的 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) 該函數使用 HMACSHA512，這是一種由 SHA-512 雜湊演算法構建的含有金鑰的雜湊函數演算法，用作雜湊訊息鑒別碼 (HMAC) 使用。它產生長度為 512 位的雜湊輸出，其由來源資料 stringText 和 secretKey 組成

範例指令碼中的 Snippet 動作包含此代碼：

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

使用權杖和 OAuth 進行授權的函數

OAuth 和透過 JSON 網路權杖（JWT，或權杖）進行的基於權杖的驗證是將驗證流構建到應用程式中的兩個標準。您可以將它們一起使用，以確保用戶端應用程式能夠有效地驗證使用者詳細資料。當驗證伺服器透過 OAuth 成功地驗證了使用者的憑證時，它還必須將使用者的詳細資料傳送給用戶端應用程式。

要使用這些函數，您必須有一個可用的驗證伺服器。當使用權杖時，OAuth 伺服器會在授權流程完成後將權杖傳送給用戶端應用程式。該權杖包含最終使用者的資訊。

可在指令碼中使用的函數結合了用於使用者和用戶端驗證的 OAuth 標準和 HMACSHA256 雜湊演算法。RFC7523 中定義了 OAuth 標準，其在 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)

權杖有三個部分：標頭、工作負載和簽名。這些函數有許多參數，這些參數提供用於建立這些部分的資料。參數定義如下表所示：

參數 類型 描述
apiURL 字串 所連接的 API 端點的 URL。
key 字串 您希望指令碼在使用該函數進行雜湊時使用的金鑰。
iss 字串 權杖的發行者。
sub 字串 權杖的主題。
aud 字串 權杖的預期消費者。通常情況下，這就是客戶想要存取的授權伺服器。
jwtHeaderData 動態資料 您想要包含在權杖標頭中的資料。
jwtPayloadData 動態資料 保存權杖中需要包含的任何工作負載的鍵值對。這可以包括權杖的過期時間。這在下面的樣本 snippet 中顯示為 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)

樣本指令碼擁有每個可用函數的代碼。此範例僅涵蓋了六個可用函數中的兩個。