Codificar o usar hash con los datos

La información de esta página de ayuda aplica tanto a CXone Studio como a Desktop Studio.

Studio admite varias funciones que puede usar para codificar datos en sus scripts. Tanto la codificación como el hash transforman los datos en un formato diferente. Es diferente la forma en que cambian los datos y lo que puede hacer con ellos:

  • Codificación: Este proceso transforma los datos en un formato que se puede usar o pasar mediante sus scripts a otros sistemas. La codificación utiliza un esquema o método, que a menudo está disponible públicamente. Por eso, no es segura la transformación. Sin embargo, el objetivo de la codificación no es proteger los datos, sino asegurarse de que se puedan utilizar correctamente en el sistema receptor. La codificación se puede invertir para devolver los datos a su formato original.
  • Elaboración de hash: Este es un proceso unidireccional que convierte los datos en una cadena alfanumérica de longitud fija. Una cadena con hash a veces se denomina hash. Los hashes se utilizan a menudo para verificar la integridad de los datos. Cuando se aplica hash a dos cadenas idénticas con el mismo algoritmo, sus hash son los mismos. Si no coinciden dos hashes que se crean con el mismo algoritmo, sabrá que también eran diferentes las cadenas originales. Este proceso se puede utilizar para verificar datos de seguridad, como firmas digitales o contraseñas, sin tener que pasar datos confidenciales en texto sin formato.

Además, Studio admite la autorización mediante OAuth. Este es un método para brindar seguridad a las interacciones entre CXone y otros sistemas.

Esta página ofrece información sobre las funciones que puede usar en los Studio scripts para codificar o hacer un hash de las cadenas, o para configurar flujos de autorización con OAuth. No ofrece información sobre cómo implementar estas soluciones. Para mayor información sobre los algoritmos que usan estas funciones, consulte el sitio web del Internet Engineering Task Force (IETF)

El hashing es irreversible. Utilice con precaución cualquier función que genere hashes de cadenas y asegúrese de comprender cómo implementarla antes de usarla con datos en vivo.

RestProxy

La codificación y el hash de cadenas en Studio requiere el uso de RestProxy, un servicio que le permite ingresar a las RESTful API con sus scripts. También le brinda acceso a las funciones que se utilizan para la codificación y el hash. Los ejemplos de los snippets de las funciones que puede usar al codificar o elaborar hashes de cadenas incluyen la siguiente declaración, que ingresa a RestProxy:

ASSIGN restProxy = new UCN.Data.RESTProxy()

Es importante que incluya UCN.Data.RESTProxy() en su asignación de variables exactamente como se muestra. RESTProxy() es la función que le permite ingresar a las funciones que se utilizan para codificar y hacer hashes con los datos.

Ejemplos

Los ejemplos del código Snippet por cada función se presenta para que lo use en sus scripts. El código también está disponible para ser copiado desde esta página de ayuda en la tabla que describe cada función.

  1. Descargue el archivo ZIP del script de ejemplo.
  2. Descomprima el contenido del archivo ZIP. Contiene dos archivos de script: 

    • EncodeAndHashScriptExample.xml, que contiene un script de ejemplo donde puede probar una función.

    • ExampleSnippetActions.xml, que contiene una acción de un Snippet por cada algoritmo de esta página. Cada Snippet contiene el código de muestra de esa función.

  3. Importe ambos archivos XML en Studio.
  4. Copie el código del snippet de la acción de Snippet en el archivo ExampleSnippetActions.xml para la función que desea utilizar.
  5. Pegue el código copiado en la acción del Snippet en el archivo EncodeAndHashScriptExample.xml.
  6. Configure una interacción simulada y haga clic Start with Trace. También puede usar el depurador de código en la ventana del editor del Snippet. Ambas opciones le permiten ver los contenidos cambiantes de las variables en el snippet.

Funciones para Codificar las  cadenas

La codificación transforma los datos en un formato diferente. Puede usarlo para transmitir grandes cantidades de datos o para transmitir datos que no puede transportar el protocolo que se está utilizando. Los datos codificados se pueden volver a convertir a su formato original.

Hay dos funciones que puede usar para codificar cadenas. Ambos usan el esquema Base64 para codificar los datos.

Nombre de la función Descripción
EncodeBase64(string)

Algunos protocolos no pueden transportar datos binarios. Puede usar esta función para convertir datos binarios que se transfieren con el parámetro string en un formato en que pueda ser transportado.

La acción Snippet en el ejemplo contiene este código:

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

Las funciones de Base64 se pueden utilizar para codificar direcciones URL en aplicaciones web. Sin embargo, en la codificación se utilizan tres caracteres especiales que deben analizarse de manera diferente en las URL. Los caracteres son el signo más ( + ), la barra inclinada ( / ) y el signo igual ( = ). Puede usar la función EncodeBase64Url para codificar correctamente la URL que se pasa como argumento del parámetro URL.

La acción Snippet en el ejemplo contiene este código:

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

Función para decodificar una cadena

Use esta función para decodificar una cadena que haya sido codificada con la función EncodeBase64.

Nombre de función Descripción
DecodeBase64 (string)

Esta función revierte los datos codificados (string) a su formato original.

La acción Snippet en el ejemplo contiene este código:

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

Funciones para codificar una cadena con una Clave Secreta

Las funciones hash usan cálculos matemáticos para generar una cadena de salida de una longitud fija. La cadena de salida, llamada hash, es útil para verificar la autenticidad de los datos en un hash. Puede usarlos para verificar contraseñas, firmas digitales, etc. Por ejemplo, puede almacenar una versión en hash de una contraseña. Cuando un usuario ingresa la contraseña, puede volverla un hash y compararla con la versión en hash de la contraseña que usted almacenó. Si son iguales, es correcta la contraseña.

Las funciones hash descritas en esta sección son todos algoritmos hash con clave. Utilizan un algoritmo de Código de Autenticación de Mensajes basado en Hash (HMAC). Cada algoritmo genera una salida hash de una longitud específica. Los algoritmos HMAC utilizan una combinación de claves secretas y funciones hash para producir la salida hash. El proceso HMAC:

  1. Mezcla una clave secreta con los datos del mensaje.
  2. Genera un hash del resultado con la función hash.
  3. Mezcla de nuevo el valor hash con la clave secreta.
  4. Aplica la función hash por segunda vez.

Las funciones hash son unidireccionales. Esto significa que no se pueden deshacer. Por este motivo, no se pueden utilizar estas funciones para cifrar datos. El cifrado también utiliza claves, al igual que las funciones hash de esta sección. Sin embargo, los algoritmos de cifrado no incluyen los algoritmos hash y son reversibles. Studio no ofrece ninguna función de encriptación.

Es responsabilidad de su organización obtener la clave y compartirla con la entidad o el sistema receptor.

Proteja la seguridad de su clave secreta. Si se pierde la clave, ya no se pueden utilizar todos los datos con hash. No puede comparar cadenas con hash con dos claves diferentes, incluso si son idénticas las cadenas.

Nombre de función Descripción
EncodeHS256(stringText, secretKey)

Esta función utiliza HMACSHA256, un algoritmo hash con clave construido a partir del algoritmo hash SHA-256 y se utiliza como un Código de Autenticación de Mensajes basado en Hash (HMAC). Genera una salida hash de 256 bits de longitud, compuesta por los datos de origen stringText y el secretKey.

La acción Snippet en el ejemplo contiene este código:

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)

Esta función es la misma que EncodeHS256, salvo que no incluye la codificación Base64. La salida hash se compone de los datos de origen stringText y el secretKey.

La acción Snippet en el ejemplo contiene este código:

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)

Esta función utilizaHMACSHA384, un algoritmo hash con clave construido a partir del algoritmo hash SHA-384 y se utiliza como un Código de Autenticación de Mensajes basado en Hash (HMAC). Genera una salida hash de 384 bits de longitud, compuesta por los datos de origen stringText y el secretKey.

La acción Snippet en el ejemplo contiene este código:

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) Esta función utiliza HMACSHA512, un algoritmo hash con clave construido a partir del algoritmo hash SHA-512 y se utiliza como un Código de Autenticación de Mensajes basado en Hash (HMAC). Genera una salida hash de 512 bits de longitud, compuesta por los datos de origen stringText y el secretKey.

La acción Snippet en el ejemplo contiene este código:

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

Funciones para crear un Hash con una Cadena con un Par de Clave Pública/Privada

Las funciones hash usan cálculos matemáticos para generar una cadena de salida de una longitud fija. La cadena de salida, llamada hash, es útil para verificar la autenticidad de los datos en un hash. Puede usarlos para verificar contraseñas, firmas digitales, etc. Por ejemplo, puede almacenar una versión en hash de una contraseña. Cuando un usuario ingresa la contraseña, puede volverla un hash y compararla con la versión en hash de la contraseña que usted almacenó. Si son iguales, es correcta la contraseña.

Estas funciones utilizan algoritmos RSA y SHA. RSA es un conjunto de algoritmos criptográficos que utilizan pares de claves pública/privada. SHA es un conjunto de algoritmos hash. Juntos, generan hashes de longitud fija. Hay tres funciones permitidas, cada una de las cuales produce un hash de diferente longitud. La clave privada se utiliza para crear el hash. La clave pública se utiliza para verificarlo.

Las funciones hash son unidireccionales. Esto significa que no se pueden deshacer. Por este motivo, no se pueden utilizar estas funciones para cifrar datos. El cifrado también utiliza claves, al igual que las funciones hash de esta sección. Sin embargo, los algoritmos de cifrado no incluyen los algoritmos hash y son reversibles. Studio no ofrece ninguna función de encriptación.

Todas las funciones hash que se describen en esta sección requieren que usted genere e instale un certificado SSL en su CXone tenant. El certificado contiene las claves pública y privada que utilizan estas funciones. Póngase en contacto con su Representante de cuenta CXone para obtener ayuda con esta proceso.

Esta opción demanda de la asistencia de NICE CXone para configurar el certificado para su sistema. Póngase en contacto con su Representante de cuenta CXone para más información.

Nombre de función Descripción
EncodeRS256(stringText)

Esta función utiliza el algoritmo RS256, también conocido como Firma RSA con SHA-256. La longitud de la salida hash depende de la longitud de la clave privada que utilice. El hash se compone de los datos de origen stringText y la clave privada que es parte del certificado SSL que instala con CXone.

La acción Snippet en el ejemplo contiene este código:

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

Esta función utiliza el algoritmo RS384, también conocido como Firma RSA con SHA-384. La longitud de la salida hash depende de la longitud de la clave privada que utilice. El hash se compone de los datos de origen stringText y la clave privada que es parte del certificado SSL que instala con CXone.

La acción Snippet en el ejemplo contiene este código:

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

Esta función utiliza el algoritmo RS512, también conocido como Firma RSA con SHA-512. La longitud de la salida hash depende de la longitud de la clave privada que utilice. El hash se compone de los datos de origen stringText y la clave privada que es parte del certificado SSL que instala con CXone.

La acción Snippet en el ejemplo contiene este código:

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

Funciones para Autorización con Tokens y OAuth

OAuth y la autenticación basada en tokens con Tokens Web JSON (JWT o tokens) son dos estándares para crear flujos de autenticación en las aplicaciones. Puede usarlos en conjunto para asegurarse de que la aplicación cliente pueda verificar de manera eficiente los detalles del usuario. Cuando el servidor de autenticación verifica con éxito las credenciales del usuario a través de OAuth, también debe transmitir los detalles del usuario a la aplicación cliente.

Para usar estas funciones, debe contar con un servidor de autenticación. Cuando se utilizan tokens, el servidor OAuth envía el token a la aplicación cliente una vez que se completa el flujo de autorización. El token contiene la información del usuario final.

Las funciones disponibles para su uso en scripts combinan el estándar OAuth para la autenticación de usuarios y la autenticación de clientes con el algoritmo de hash HMACSHA256. El estándar OAuth se define en RFC7523, que está en el nombre de las funciones en Studio.

Puede utilizar las siguientes funciones en sus scripts Studio para incorporar un flujo de autorización con OAuth y 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)

Los tokens tienen tres partes: un encabezado, una carga útil y una firma. Estas funciones tienen muchos parámetros, que proporcionan datos que se utilizan para crear estas partes. Se definen los parámetros en la siguiente tabla:

Parámetro Tipo Descripción
apiURL Cadena La URL de la terminal de la API con la que se está conectando.
key Cadena La clave secreta que desea que use la secuencia de comandos al realizar operaciones hash con esta función.
iss Cadena El emisor del token.
sub Cadena El asunto del token.
aud Cadena El consumidor previsto del token. Por lo general, este es el servidor de autorización al que el cliente desea ingresar.
jwtHeaderData Datos dinámicos Los datos que desea incluir en el encabezado del token.
jwtPayloadData Datos dinámicos Los pares clave-valor que contienen cualquier carga útil que necesite incluir en el token. Esto puede incluir el tiempo de vencimiento del token. Esto se muestra en el snippet de muestra a continuación como payload.exp.
queryParams Datos dinámicos Los pares clave-valor que contienen los parámetros de la consulta que necesite incluir en el token. Esto se incluye únicamente en las funciones Ampliadas.
requestHeaders Datos dinámicos Los pares clave-valor que contienen la información del encabezado de la solicitud. Esto se incluye únicamente en las funciones Ampliadas.

La acción Snippet en el ejemplo contiene este código:

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)

El script de muestra tiene un código para cada función disponible. Este ejemplo cubre solo dos de las seis funciones disponibles.