Encode and Hash Strings

Studio supports several functions that you can use to encode or hash data in your scripts. Both encoding and hashing transform data into a different format. The way the data changes and what you can do with it are different: 

  • Encoding: This process transforms data into a format that can be used in or passed by your scripts to other systems. Encoding uses a scheme, or method, which is often publicly available. Because of that, the transformation is not secure. However, the goal of encoding is not to secure the data, but to make sure it can be used properly on the receiving system. Encoding can be reversed to return data to its original format.
  • Hashing: This is a one-way process that converts data into a fixed-length alphanumeric string. A hashed string is sometimes called a hash. Hashes are often used to verify the integrity of data. When two identical strings are hashed with the same algorithm, their hashes are the same. If two hashes created with the same algorithm don't match, you know that the original strings were also different. This process can be used to verify security data, such as digital signatures or passwords, without having to pass sensitive data in plain text.

Additionally, Studio supports authorization using OAuth. This is a method of providing security to interactions between CXone and other systems.

This page provides information about the functions you can use in Studio scripts to encode or hash strings, or to set up authorization flows with OAuth. It does not provide information about how to implement these solutions. For more information about the algorithms that these functions use, refer to the Internet Engineering Task Force (IETF) website.

Hashing is irreversible. Use any function that hashes strings with caution and be sure that you understand how to implement it before using it with live data.

RestProxy

Encoding and hashing strings in Studio requires the use of RestProxy, a service that allows you to access RESTful APIs with your scripts. It also provides you access to the functions used for encoding and hashing. The snippet examples for the functions you can use when encoding or hashing strings all include the following statement, which accesses RestProxy:

ASSIGN restProxy = new UCN.Data.RESTProxy()

It's important that you include UCN.Data.RESTProxy() in your variable assignment exactly as shown. RESTProxy() is the function that allows you to access the functions used to encode and hash data.

Examples

Examples of the Snippet code for each function are provided for you to use in your scripts. The code is also available to copy from this help page in the table that describes each function.

  1. Download the example script ZIP file.
  2. Unzip the contents of the ZIP file. It contains two script files: 

    • EncodeAndHashScriptExample.xml, which contains an example script where you can test a function.

    • ExampleSnippetActions.xml, which contains one Snippet action for each algorithm on this page. Each Snippet contains the sample code for that function.

  3. Import both XML files into Studio.
  4. Copy the snippet code from the Snippet action in the ExampleSnippetActions.xml file for the function you want to use.
  5. Paste the copied code into the Snippet action in the EncodeAndHashScriptExample.xml file.
  6. Set up a simulated interaction and click Start with Trace. You can also use the debugger in the Snippet editor window. Both options allow you to see the changing contents of the variables in the snippet.

Functions to Encode Strings

Encoding transforms data into a different format. You can use it to transmit large amounts of data, or to transmit data that cannot be transported by the protocol being used. Encoded data can be converted back to its original format.

There are two functions you can use to encode strings. Both use the Base64 scheme to encode the data.

Function Name Description
EncodeBase64(string)

Binary data cannot be transported by some protocols. You can use this function to convert binary data passed with the string parameter into a format that can be transported.

The Snippet action in the example script contains this code: 

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

Base64 functions can be used to encode URLs in web applications. However, there are three special characters used in the encoding that must be parsed differently in URLs. The characters are the plus sign ( + ), forward slash ( / ), and equal sign ( = ). You can use the EncodeBase64Url function to properly encode the URL passed as the argument of the URL parameter.

The Snippet action in the example script contains this code: 

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

Function to Decode a String

Use this function to decode a string that was encoded with the EncodeBase64 function.

Function Name Description
DecodeBase64 (string)

This function reverts encoded data (string) to its original format.

The Snippet action in the example script contains this code: 

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

Functions to Hash a String with a Secret Key

Hash functions use mathematical calculations to produce an output string of a fixed length. The output string, called a hash, is useful for verifying the authenticity of the hashed data. You can use them to verify passwords, digital signatures, and so on. For example, you can store a hashed version of a password. When a user enters the password, you can hash it and compare it to the hashed version of the password that you stored. If they're the same, the password is correct.

The hash functions described in this section are all keyed hash algorithms. They use a Hash-based Message Authentication Code (HMAC) algorithm. Each algorithm produces a hashed output of a specific length. HMAC algorithms use a combination of secret keys and hash functions to produce the hashed output. The HMAC process:

  1. Mixes a secret key with the message data.
  2. Hashes the result with the hash function.
  3. Mixes the hash value with the secret key again.
  4. Applies the hash function a second time.

Hash functions are one-way. This means they cannot be undone. For this reason, these functions cannot be used to encrypt data. Encryption also uses keys, just like the hash functions in this section. However, encryption algorithms do not include the hashing algorithms and are reversible. Studio does not provide any encryption functions.

It's your organization's responsibility to obtain the key and share it with the receiving entity or system.

Guard the security of your secret key. If the key is lost, all data hashed with it is no longer useable. You cannot compare strings hashed with two different keys, even if the strings are identical.

Function Name Description
EncodeHS256(stringText, secretKey)

This function uses HMACSHA256, a keyed hash algorithm constructed from the SHA-256 hash algorithm and used as a Hash-based Message Authentication Code (HMAC). It uses Base64 encoding. It produces a hashed output of 256 bits in length, made up of the source data stringText and the secretKey.

The Snippet action in the example script contains this code: 

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)

This function is the same as EncodeHS256, except it does not include Base64 encoding. The hashed output is made up of the source data stringText and the secretKey.

The Snippet action in the example script contains this 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)

This function uses HMACSHA384, a keyed hash algorithm that's constructed from the SHA-384 hash algorithm and used as a Hash-based Message Authentication Code (HMAC). It produces a hashed output of 384 bits in length, made up of the source data stringText and the secretKey.

The Snippet action in the example script contains this 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) This function uses HMACSHA512 , a keyed hash algorithm constructed from the SHA-512 hash algorithm and used as a Hash-based Message Authentication Code (HMAC). It produces a hashed output of 512 bits in length, made up of the source data stringText and the secretKey.

The Snippet action in the example script contains this code: 

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

Functions to Hash a String with a Public/Private Key Pair

Hash functions use mathematical calculations to produce an output string of a fixed length. The output string, called a hash, is useful for verifying the authenticity of the hashed data. You can use them to verify passwords, digital signatures, and so on. For example, you can store a hashed version of a password. When a user enters the password, you can hash it and compare it to the hashed version of the password that you stored. If they're the same, the password is correct.

These functions use RSA and SHA algorithms. RSA is a set of cryptographic algorithms that use public/private key pairs. SHA is a set a hashing algorithms. Together, they generate fixed-length hashes. There are three supported functions, each one producing a hash of a different length. The private key is used to create the hash. The public key is used to verify it.

Hash functions are one-way. This means they cannot be undone. For this reason, these functions cannot be used to encrypt data. Encryption also uses keys, just like the hash functions in this section. However, encryption algorithms do not include the hashing algorithms and are reversible. Studio does not provide any encryption functions.

The hash functions described in this section all require that you generate and install an SSL certificate in your CXone business unitClosed High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment. The certificate contains the public and private keys these functions use. Contact your CXone Account Representative for assistance with this process.

This option requires assistance from NICE CXone to set the certificate up for your system. Contact your CXone Account Representative for more information.

Function Name Description
EncodeRS256(stringText)

This function uses the RS256 algorithm, also known as RSA Signature with SHA-256. The length of the hash output depends on the length of the private key you use. The hash is made up of the source data stringText and the private key that's part of the SSL certificate you install with CXone.

The Snippet action in the example script contains this code: 

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

This function uses the RS384 algorithm, also known as RSA Signature with SHA-384. The length of the hash output depends on the length of the private key you use. The hash is made up of the source data stringText and the private key that's part of the SSL certificate you install with CXone.

The Snippet action in the example script contains this code: 

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

This function uses the RS512 algorithm, also known as RSA Signature with SHA-512. The length of the hash output depends on the length of the private key you use. The hash is made up of the source data stringText and the private key that's part of the SSL certificate you install with CXone.

The Snippet action in the example script contains this code: 

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

Functions for Authorization with Tokens and OAuth

OAuth and token-based authentication with JSON Web Tokens (JWTs, or tokens) are two standards for building authentication flows into applications. You can use them together to ensure that the client application can efficiently verify the user details. When the authentication server successfully verifies the user's credentials via OAuth, it must also transmit the user details to the client application.

To use these functions, you must have an authentication server available. When tokens are used, the OAuth server sends the token to the client application after the authorization flow is complete. The token contains the end user's information.

The functions available for use in scripts combine the OAuth standard for user and client authentication with the HMACSHA256 hashing algorithm. The OAuth standard is defined in RFC7523, which is in the name of the functions in Studio.

You can use the following functions in your Studio scripts to incorporate an authorization flow with OAuth and 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 have three parts: a header, a payload, and a signature. These functions have many parameters, which provide data that is used to create these parts. The parameters are defined in the following table: 

Parameter Type Description
apiURL string The URL of the API endpoint you're connecting with.
key string The secret key you want the script to use when hashing with this function.
iss string The issuer of the token.
sub string The subject of the token.
aud string The intended consumer of the token. Typically, this is the authorization server the client wants to access.
jwtHeaderData Dynamic Data The data you want to include in the header of the token.
jwtPayloadData Dynamic Data The key-value pairs that hold any payload you need to include in the token. This can include the token's expiration time. This is shown in the sample snippet below as payload.exp.
queryParams Dynamic Data The key-value pairs that hold the query parameters you want to include with the token. This is included only in the Extended functions.
requestHeaders Dynamic Data The key-value pairs that hold the request header information. This is included only in the Extended functions.

The Snippet action in the example script contains this 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)

The sample script has code for each available function. This example covers only two of the available six functions.