Kodierung und Hashing von Strings

Studio unterstützt mehrere Funktionen, die Sie für die Kodierung und das Hashing von Daten in Ihren Skripten verwenden können. Bei der Kodierung und beim Hashing werden Daten in ein anderes Format umgewandelt. Die Methoden unterscheiden sich darin, wie sich die Daten ändern und wofür sie verwendet werden können:

  • Kodierung: Die Daten werden in ein Format konvertiert, das in anderen Systemen verwendet oder von Ihren Skripten an andere Systeme übergeben werden kann. Bei der Kodierung wird ein Schema oder eine Methode verwendet, die häufig öffentlich verfügbar ist. Deshalb ist die Umwandlung nicht sicher. Die Kodierung hat aber auch nicht den Zweck, die Daten zu sichern. Sie soll dafür sorgen, dass die Daten im empfangenden System ordnungsgemäß verwendet werden können. Die Kodierung kann rückgängig gemacht werden, um die Daten wieder in das Originalformat zu konvertieren.
  • Hashing: Dies ist ein unidirektionales Verfahren, mit dem Daten in einen alphanumerischen String mit einer festen Länge konvertiert werden. Ein per Hashing konvertierter String wird auch als "Hash" bezeichnet. Hashes werden häufig verwendet, um die Integrität von Daten zu überprüfen. Wenn das Hashing für zwei identische Strings mit demselben Algorithmus durchgeführt wird, sind ihre Hashes gleich. Wenn zwei Hashes, die mit demselben Algorithmus erstellt wurden, nicht übereinstimmen, waren auch die ursprünglichen Strings ungleich. Mit diesem Verfahren können Sicherheitsdaten wie digitale Signaturen oder Kennwörter überprüft werden, ohne dass vertrauliche Daten im reinen Textformat übergeben werden müssen.

Zusätzlich unterstützt Studio die Autorisierung mit OAuth. Diese Methode sorgt für Sicherheit bei Interaktionen zwischen CXone und anderen Systemen.

Auf dieser Seite finden Sie Informationen zu den Funktionen, die Sie in Studio-Skripten zum Kodieren oder Hashen von Strings oder zum Einrichten von Autorisierungsabläufen mit OAuth verwenden können. Die Implementierung dieser Lösungen wird nicht beschrieben. Weitere Informationen zu den von diesen Funktionen verwendeten Algorithmen finden Sie auf der Website der Internet Engineering Task Force (IETF).

Das Hashing kann nicht rückgängig gemacht werden. Gehen Sie vorsichtig vor, wenn Sie Funktionen verwenden, die Strings per Hashing umwandeln. Nutzen Sie die Funktion nur dann mit Live-Daten, wenn Sie wissen, wie Sie sie richtig implementieren.

RestProxy

Zum Kodieren und Hashing von Strings in Studio muss der RestProxy-Dienst verwendet werden, der Ihnen den Zugriff auf RESTful-APIs in Ihren Skripten ermöglicht. Er bietet auch Zugriff auf die Funktionen, die für die Kodierung und das Hashing verwendet werden. Die Snippet-Beispiele für Funktionen, die Sie beim Kodieren oder Hashing von Strings verwenden können, enthalten alle die folgende Anweisung für den Zugriff auf RestProxy:

ASSIGN restProxy = new UCN.Data.RESTProxy()

Sie müssen UCN.Data.RESTProxy() genau wie gezeigt in Ihre Variablenzuweisung aufnehmen. RESTProxy() ist die Funktion, mit der Sie auf die Funktionen für die Kodierung und das Hashing von Daten zugreifen können.

Beispiele

Beispiele des Snippet-Codes für jede Funktion stehen zur Verwendung in Ihren Skripten zur Verfügung. Der Code kann auch auf dieser Hilfeseite in der Tabelle mit den Funktionsbeschreibungen kopiert werden.

  1. Laden Sie die ZIP-Datei mit dem Beispielskript herunter.
  2. Extrahieren Sie den Inhalt der ZIP-Datei. Sie enthält zwei Skriptdateien: 

    • EncodeAndHashScriptExample.xml enthält ein Beispielskript, mit dem Sie eine Funktion testen können.

    • ExampleSnippetActions.xml enthält eine Snippet-Aktion für jeden Algorithmus auf dieser Seite. Jedes Snippet enthält den Beispielcode für die jeweilige Funktion.

  3. Importieren Sie beide XML-Dateien in Studio.
  4. Kopieren Sie den Snippet-Code aus der Snippet-Aktion in die Datei ExampleSnippetActions.xml für die Funktion, die Sie verwenden möchten.
  5. Fügen Sie den kopierten Code in die Snippet-Aktion in der Datei EncodeAndHashScriptExample.xml ein.
  6. Richten Sie eine simulierte Interaktion ein und klicken Sie auf Start with Trace. Sie können auch den Debugger im Snippet-Editor-Fenster verwenden. Bei beiden Optionen können Sie sehen, wie sich die Inhalte der Variablen im Snippet ändern.

Funktionen zum Kodieren von Strings

Bei der Kodierung werden Daten in ein anderes Format umgewandelt. Mit dieser Methode können Sie große Datenmengen oder Daten, die vom verwendeten Protokoll nicht unterstützt werden, übertragen. Die kodierten Daten können wieder in das ursprüngliche Format konvertiert werden.

Zum Kodieren von Strings stehen zwei Funktionen zur Verfügung. Beide verwenden das Base64-Schema zum Kodieren der Daten.

Funktionsname Beschreibung
EncodeBase64(string)

Binärdaten können von einigen Protokollen nicht übertragen werden. Mit dieser Funktion können Sie Binärdaten, die mit dem string-Parameter übergeben wurden, in ein Format konvertieren, das sich für die Übertragung eignet.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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

Base64-Funktionen eignen sich zum Kodieren von URLs in Webanwendungen. Die Kodierung enthält jedoch drei Sonderzeichen, die in URLs auf unterschiedliche Weise analysiert werden müssen. Bei diesen Zeichen handelt es sich um das Pluszeichen ( + ), den Schrägstrich ( / ) und das Gleichheitszeichen ( = ). Sie können die Funktion EncodeBase64Url verwenden, um die URL, die als Argument des URL-Parameters übergeben wurde, korrekt zu kodieren.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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

Funktion zum Dekodieren eines Strings

Verwenden Sie diese Funktion zum Dekodieren eines Strings, der mit der Funktion EncodeBase64 kodiert wurde.

Funktionsname Beschreibung
DecodeBase64 (string)

Mit dieser Funktion werden kodierte Daten (string) wieder in das ursprüngliche Format konvertiert.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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

Funktionen für das Hashing eines Strings mit einem Geheimschlüssel

Hash-Funktionen verwenden mathematische Berechnungen, um einen Ausgabe-String mit einer festen Länge zu generieren. Mithilfe des Ausgabe-Strings, genannt "Hash", kann die Authentizität der Hash-Daten überprüft werden. Anhand dieser Daten können Sie Kennwörter, digitale Signaturen und so weiter verifizieren. Beispielsweise können Sie eine Hash-Version eines Kennworts speichern. Wenn ein Benutzer das Kennwort eingibt, können Sie es mit der Hash-Funktion verarbeiten und mit der Hash-Version des gespeicherten Kennworts vergleichen. Wenn sie übereinstimmen, ist das Kennwort korrekt.

Die in diesem Abschnitt beschriebenen Hash-Funktionen sind alle verschlüsselte Hash-Algorithmen. Sie verwenden einen HMAC-Algorithmus (Hash-based Message Authentication Code, Hash-basierter Nachrichtenauthentifizierungscode). Jeder Algorithmus erstellt eine Hash-Ausgabe mit einer bestimmten Länge. HMAC-Algorithmen verwenden eine Kombination aus Geheimschlüsseln und Hash-Funktionen, um die Hash-Ausgabe zu generieren. Dies sind die Schritte beim HMAC-Prozess:

  1. Ein Geheimschlüssel wird mit den Nachrichtendaten kombiniert.
  2. Das Ergebnis wird mit der Hash-Funktion in das Hash-Format konvertiert.
  3. Der Hash-Wert wird wieder mit dem Geheimschlüssel kombiniert.
  4. Die Hash-Funktion wird ein zweites Mal angewendet.

Hash-Funktionen sind nur für eine Richtung vorgesehen. Das heißt, dass sie nicht rückgängig gemacht werden können. Deshalb eignen sich diese Funktionen nicht zum Verschlüsseln von Daten. Bei der Verschlüsselung werden wie bei den Hash-Funktionen in diesem Abschnitt ebenfalls Schlüssel verwendet. Doch Verschlüsselungsalgorithmen enthalten keine Hash-Algorithmen und können rückgängig gemacht werden. Studio bietet keine Verschlüsselungsfunktionen.

Ihre Organisation ist dafür zuständig, den Schlüssel abzurufen und mit dem empfangenden System zu teilen.

Der Geheimschlüssel muss gut geschützt werden. Wenn der Schlüssel verloren geht, können die mit dem Schlüssel erstellten Hash-Daten nicht mehr verwendet werden. Hash-Strings, die mit zwei unterschiedlichen Schlüsseln generiert wurden, können nicht verglichen werden, selbst wenn die Strings identisch sind.

Funktionsname Beschreibung
EncodeHS256(stringText, secretKey)

Diese Funktion verwendet HMACSHA256, einen verschlüsselten Hash-Algorithmus, der mit dem SHA-256-Hash-Algorithmus generiert und als HMAC (Hash-based Message Authentication Code) verwendet wird. Sie generiert eine Hash-Ausgabe mit einer Länge von 256 Bit. Die Ausgabe besteht aus den stringText -Quelldaten und dem secretKey-Geheimschlüssel.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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)

Diese Funktion entspricht EncodeHS256, sie enthält jedoch keine Base64-Kodierung. Die Hash-Ausgabe besteht aus den stringText -Quelldaten und dem secretKey-Geheimschlüssel.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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)

Diese Funktion verwendet HMACSHA384, einen verschlüsselten Hash-Algorithmus, der mit dem SHA-384-Hash-Algorithmus generiert und als HMAC (Hash-based Message Authentication Code) verwendet wird. Sie generiert eine Hash-Ausgabe mit einer Länge von 384 Bit. Die Ausgabe besteht aus den stringText -Quelldaten und dem secretKey-Geheimschlüssel.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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) Diese Funktion verwendet HMACSHA512, einen verschlüsselten Hash-Algorithmus, der mit dem SHA-512-Hash-Algorithmus generiert und als HMAC (Hash-based Message Authentication Code) verwendet wird. Sie generiert eine Hash-Ausgabe mit einer Länge von 512 Bit. Die Ausgabe besteht aus den stringText -Quelldaten und dem secretKey-Geheimschlüssel.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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

Funktionen für die Autorisierung mit Tokens und OAuth

OAuth und die tokenbasierte Authentifizierung mit JSON-Webtokens (JWTs oder Tokens) sind zwei Standardmethoden, mit denen Authentifizierungsabläufe in Anwendungen integriert werden können. Sie können diese Methoden zusammen verwenden, um sicherzustellen, dass die Client-Anwendung die Benutzerdetails auf effiziente Weise überprüfen kann. Wenn der Authentifizierungsserver die Anmeldedaten des Benutzers erfolgreich über OAuth überprüft hat, müssen die Benutzerdetails zusätzlich an die Client-Anwendung übertragen werden.

Sie können diese Funktionen nur verwenden, wenn ein Authentifizierungsserver zur Verfügung steht. Wenn Tokens verwendet werden, sendet der OAuth-Server das Token an die Client-Anwendung, nachdem der Autorisierungsablauf abgeschlossen wurde. Das Token enthält die Informationen des Endbenutzers.

Die Funktionen, die in Skripten verwendet werden können, kombinieren den OAuth-Standard für die Benutzer- und Client-Authentifizierung mit dem HMACSHA256-Hash-Algorithmus. Der OAuth-Standard ist in RFC7523 definiert, der im Namen der Funktionen in Studio enthalten ist.

Sie können die folgenden Funktionen in Ihren Studio-Skripten verwenden, um einen Autorisierungsablauf mit OAuth und Tokens zu integrieren:

  • 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)

Tokens bestehen aus drei Teilen: Kopfzeile, Payload und Signatur. Diese Funktionen haben zahlreiche Parameter, mit denen die Daten bereitgestellt werden, die zum Erstellen dieser Teile verwendet werden. Die Parameter werden in der folgenden Tabelle beschrieben:

Parameter Art Beschreibung
apiURL String Die URL des API-Endpunkts, mit dem Sie eine Verbindung herstellen.
key String Der Geheimschlüssel, den das Skript für das Hashing mit dieser Funktion verwenden soll.
iss String Der Aussteller des Tokens.
sub String Der Betreff des Tokens.
aud String Der vorgesehene Nutzer des Tokens. Normalerweise ist dies der Autorisierungsserver, auf den der Client zugreifen möchte.
jwtHeaderData Dynamische Daten Die Daten, die in die Token-Kopfzeile aufgenommen werden sollen.
jwtPayloadData Dynamische Daten Die Schlüssel-Wert-Paare, die die Payload enthalten, die in das Token aufgenommen werden muss. Dies kann beispielsweise das Ablaufdatum des Tokens sein. Diese Angabe wird unten im Beispiel-Snippet als payload.exp gezeigt.
queryParams Dynamische Daten Die Schlüssel-Wert-Paare, die die Abfrageparameter enthalten, die Sie in das Token aufnehmen möchten. Sie werden nur in den erweiterten Funktionen verwendet.
requestHeaders Dynamische Daten Die Schlüssel-Wert-Paare, die die Informationen für die Kopfzeile der Anfrage enthalten. Sie werden nur in den erweiterten Funktionen verwendet.

Die Snippet-Aktion im Beispielskript enthält diesen Code:

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)

Das Beispielskript enthält Code für jede verfügbare Funktion. In diesem Beispiel werden nur zwei der sechs verfügbaren Funktionen behandelt.