Strings coderen en hashen

Studio Ondersteunt meerdere functies die u kunt gebruiken voor het coderen of hashen van gegevens in uw scripts. Zowel het coderen als hashen transformeren gegevens in een andere indeling. De manier waarop gegevens veranderen en wat u ermee kunt doen verschillen.

  • Codering: dit proces transformeert gegevens in een indeling die kan worden gebruikt in of doorgegeven door uw scripts aan andere systemen. Codering gebruikt een schema of methode die vaak openbaar beschikbaar is. De transformatie is daarom niet veilig. Het doel van de codering is echter niet de beveiliging van de gegevens, maar het is ervoor zorgen dat dit correct kan worden gebruikt op het ontvangstsysteem. Codering kan worden omgekeerd om gegevens terug te brengen naar de originele indeling.
  • Hashen: dit is het eenrichtingsproces dat gegevens converteert naar een alfanumerieke string met een vaste lengte. Een gehashte string wordt soms een hash genoemd. Hashes worden vaak gebruikt voor het verifiëren van de integriteit van gegevens. Wanneer twee identieke strings worden gehasht met hetzelfde algoritme, zijn hun hashes dezelfde. Als twee hashes die met hetzelfde algoritme zijn gemaakt, niet overeenkomen, weet u dat de originele strings ook verschillen. Dit proces kan worden gebruikt voor het controleren van beveiligingsgegevens, zoals digitale handtekeningen of wachtwoorden, zonder dat u gevoelige gegevens in onbewerkte tekst moet doorlopen.

Daarnaast ondersteunt Studio autorisatie met OAuth. Dit is een methode voor het leveren van beveiliging aan interacties tussen CXone en andere systemen.

Deze pagina biedt informatie over de functies die u kunt gebruiken in Studio-scripts om strings te coderen of te hashen of om authorisatieflows in te stellen met OAuth. Dit biedt geen informatie over het implementeren van deze oplossingen. Raadpleeg de website Internet Engineering Task Force (IETF) voor meer informatie over de algoritmen die deze functies gebruiken.

Hashing is onomkeerbaar. Wees voorzichtig bij het gebruik van functies die strings hasht en zorg dat u begrijpt hoe u het moet implementeren voordat het wordt gebruikt met live gegevens.

RestProxy

Coderen en hashen van strings in Studio vereist het gebruik van RestProxy, een service die toegang verleent tot RESTful-API's met uw scripts. Dit biedt u ook toegang tot de functies die worden gebruikt voor het coderen en hashen. Het fragmentvoorbeelden voor de functies die u kunt gebruiken bij het coderen of hashen van strings, bevatten allemaal de volgende verklaring die RestProxy opent:

ASSIGN restProxy = new UCN.Data.RESTProxy()

Het is belangrijk dat u UCN.Data.RESTProxy() exact in uw variabelentoewijzing opneemt zoals weergegeven. RESTProxy() is de functie waarmee u toegang krijgt tot de functies die worden gebruikt voor het coderen en hashen van gegevens.

Voorbeelden

Er zijn voorbeelden van de Snippet-code voor elke functie die u krijgt voor het gebruik in uw scripts. De code is ook beschikbaar om te kopiëren vanaf deze helppagina in de tabel die elke functie beschrijft.

  1. Download het ZIP-bestand van het voorbeeldscript.
  2. Pak de inhoud van het ZIP-bestand uit. Het bevat twee scriptbestanden: 

    • EncodeAndHashScriptExample.xml die een voorbeeldscript bevat waar u een functie kunt testen.

    • ExampleSnippetActions.xml die één fragment-actie bevat voor elk algoritme op deze pagina. Elke fragment bevat de voorbeeldcode voor die functie.

  3. Importeer beide XML-bestanden in Studio.
  4. Kopieer de fragmentcode van de Fragment-actie in het bestand ExampleSnippetActions.xml voor de functie die u wilt gebruiken.
  5. Plak de gekopieerde code in de Fragment-actie in het bestand EncodeAndHashScriptExample.xml.
  6. Stel een gesimuleerde interactie in en klik op Start with Trace. U kunt de debugger ook gebruiken in het venster Fragment-editor. Via beide opties kunt u de veranderende inhoud van de variabelen in het fragment zien.

Functies voor het coderen van strings

Het coderen transformeert gegevens naar een andere indeling. U kunt deze gebruiken voor het overdragen van grote hoeveelheden gegevens, of voor het overdragen van gegevens die niet kunnen worden getransporteerd door het protocol dat wordt gebruikt. Gecodeerde gegevens kunnen terug naar de originele indeling worden geconverteerd.

Er zijn twee functies die u kunt gebruiken voor het coderen van gegevens. Beide gebruiken het Base64-schema voor het coderen van de gegevens.

Functienaam Description
EncodeBase64(string)

Binaire gegevens kunnen niet worden getransporteerd door sommige protocollen. U kunt deze functie gebruiken voor het converteren van binaire gegevens die zijn doorgegeven met de string parameter in een indeling die kan worden getransporteerd.

De Fragment-actie in het voorbeeldscript bevat deze code:

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

Base64-functies kunnen worden gebruikt voor het coderen van URL's in webtoepassingen. Er zijn echter drie speciale tekens die worden gebruikt in de codering die anders moet worden geparseerd in URL's De tekens zijn het plusteken ( + ), voorwaartse schuine streep ( / ) en gelijkheidsteken ( = ). U kunt de functie EncodeBase64Url gebruiken voor een correcte codering van de URL die is doorgegeven als het argument van de URL parameter.

De Fragment-actie in het voorbeeldscript bevat deze code:

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

Functie voor het decoderen van een string

Gebruik deze functie voor het decoderen van een string die werd gecodeerd met de functie EncodeBase64.

Functienaam Description
DecodeBase64 (string)

Deze functie brengt gecodeerde gegevens (string) terug naar de originele indeling.

De Fragment-actie in het voorbeeldscript bevat deze code:

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

Functies voor hashing van strings met een geheime sleutel

Hash-functies gebruiken wiskundige berekeningen om een uitvoerstring van een vaste lengte te produceren. De uitvoerstring, hash genoemd, is handig voor het verifiëren van de authenticiteit van de gehashte gegevens. U kunt ze gebruiken voor het controleren van wachtwoorden, digitale handtekeningen enz. U kunt bijvoorbeeld een gehashte versie van een wachtwoord opslaan. Wanneer een gebruiker het wachtwoord invoert, kunt u het hashen en vergelijken met de gehashte versie van het wachtwoord dat u hebt opgeslagen. Als ze dezelfde zijn, is het wachtwoord correct.

De hashfuncties die zijn beschreven in deze secties, zijn allemaal hash-algoritmen met een sleutel. Ze gebruiken een algoritme van een op hash gebaseerde berichtauthenticatiecode (HMAC). Elk algoritme produceert een gehashte uitvoer van een specifieke lengte. HMAC-algoritmen gebruiken een combinatie van geheime sleutels en hash-functies voor het produceren van de gehashte uitvoer. Het HMAC-proces:

  1. Mengt een geheime sleutel met de berichtgegevens.
  2. Hasht het resultaat met de hashfunctie.
  3. Mengt de hashwaarde opnieuw met de geheime sleutel.
  4. Past de hashfunctie een tweede keer toe.

Hash-functies gaan in één richting. Dit betekent dat ze niet ongedaan kunnen worden gemaakt. Voor deze reden kunnen functies niet worden gebruikt voor het coderen van gegevens. Codering gebruikt ook sleutels, net als de hashfuncties in deze sectie. Coderingsalgoritmen bevatten echter geen hashingalgoritmen en zijn omkeerbaar. Studio biedt geen coderingsfuncties.

Het is de verantwoordelijkheid van uw organisatie voor het verkrijgen van de sleutel en deze te delen met de ontvangende entiteit of het ontvangende systeem.

Bewaak de beveiliging van uw geheime sleutel. Als de sleutel verloren is, zijn alle gegevens die ermee zijn gehasht, niet langer bruikbaar. U kunt geen strings vergelijken die gehasht zijn met twee verschillende sleutels, zelfs als de strings identiek zijn.

Functienaam Description
EncodeHS256(stringText, secretKey)

Deze functie gebruikt HMACSHA256, een hash-algoritme met sleutel dat is gebouwd op basis van het SHA-256-hashalgoritme en is gebruikt als een op hash gebaseerde berichtauthenticatiecode (HMAC). Dit produceert een gehashte uitvoer van 256 bits lang, bestaande uit de brongegevens stringText en de secretKey.

De Fragment-actie in het voorbeeldscript bevat deze 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)

Deze functie is dezelfde als EncodeHS256, behalve dat deze geen Base64-codering bevat. De gehashte uitvoer is opgemaakt uit de brongegevens stringText en de secretKey.

De Fragment-actie in het voorbeeldscript bevat deze 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)

Deze functie gebruikt HMACSHA384, een hash-algoritme met sleutel dat is gebouwd op basis van het SHA-384-hashalgoritme en is gebruikt als een op hash gebaseerde berichtauthenticatiecode (HMAC). Dit produceert een gehashte uitvoer van 384 bits lang, bestaande uit de brongegevens stringText en de secretKey.

De Fragment-actie in het voorbeeldscript bevat deze 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) Deze functie gebruikt HMACSHA512, een hash-algoritme met sleutel dat is gebouwd op basis van het SHA-512-hashalgoritme en is gebruikt als een op hash gebaseerde berichtauthenticatiecode (HMAC). Dit produceert een gehashte uitvoer van 512 bits lang, bestaande uit de brongegevens stringText en de secretKey.

De Fragment-actie in het voorbeeldscript bevat deze code:

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

Functies voor autorisatie met tokens en OAuth

OAuth en op token gebaseerde authenticatie met JSON-webtokens (JWT's of tokens) zijn twee standaarden voor het bouwen van authenticatieflows in applicaties. U kunt ze samen gebruiken om te garanderen dat de clientapplicatie de gebruikersdetails efficiënt kan verifiëren. Wanneer de authenticatieserver de gebruikersgegevens met succes verifieert via OAuth, moet deze ook de gebruikersgegevens overdragen naar de clienttoepassing.

Om deze functies te gebruiken, moet er een autorisatieserver beschikbaar zijn. Wanneer tokens worden gebruikt, verzendt de OAuth-server de token naar de clientapplicatie nadat de autorisatieflow is voltooid. De token bevat de informatie van de eindgebruiker.

De functies die beschikbaar zijn voor gebruik in scripts, combineren de OAuth-standaard voor gebruikers- en clientauthenticatie met het HMACSHA256-hashingalgoritme. De OAuth-standaard is gedefinieerd in RFC7523, wat in de naam zit van de functies in Studio.

U kunt de volgende functies in uw Studio-scripts gebruiken voor het integreren van een autorisatieflow met OAuth en tokens:

  • 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 hebben drie delen: een koptekst, een payload en een handtekening. Deze functies hebben veel parameters die gegevens leveren die worden gebruikt om deze onderdelen te maken. De parameters zijn gedefinieerd in de volgende tabel:

Parameter Type Description
apiURL string De URL van het API-eindpunt waarmee u verbinding maakt.
key string De geheime sleutel dat het script moet gebruiken bij het hashen met deze functie.
iss string De uitgever van de token.
sub string Het onderwerp van de token.
aud string De bedoelde verbruiker van de token. Dit is standaard de verficatieserver waarvoor de klant toegang wil.
jwtHeaderData Dynamische data De data die u wilt opnemen in de koptekst van de token.
jwtPayloadData Dynamische data De sleutelwaardeparen die elke payload bevatten die u moet opnemen in de token. Dit kan de vervaltijd van de token opnemen. Dit wordt getoond in het onderstaande voorbeeldfragment als payload.exp.
queryParams Dynamische data De sleutelwaardeparen die de query-parameters die u wilt opnemen met de token. Dit is alleen opgenomen in de uitgebreide functies.
requestHeaders Dynamische data De sleutelwaardeparen die de koptekstinformatie van de aanvraag bevatten. Dit is alleen opgenomen in de uitgebreide functies.

De Fragment-actie in het voorbeeldscript bevat deze 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)

Het voorbeeldscript heeft een code voor elke beschikbare functie. Dit voorbeeld dekt slechts twee van de zes beschikbare functies.