Codificar o usar hash con los datos

La información de esta página de ayuda se aplica tanto a 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 usar para verificar datos de seguridad, como firmas digitales o contraseñas, sin tener que transmitir 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 NiCE CXone y otros sistemas.

Esta página proporciona información sobre las funciones que puede usar en los scripts de Studio para codificar o aplicar hash a cadenas, o para configurar flujos de autorización con OAuth. No ofrece información sobre cómo implementar estas soluciones. Para obtener más información sobre los algoritmos que utilizan 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 acceder a las API RESTful 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 la asignación de su variable exactamente como se muestra. RESTProxy() es la función que le permite acceder a las funciones utilizadas para codificar y aplicar hash a los datos.

Ejemplos

Se proporcionan ejemplos del código Snippet para cada función para que los use en sus Scripts. El código también está disponible para copiarlo desde esta página de ayuda en la tabla que describe cada función.

  1. Descargue el archivo ZIP del script de ejemplo.
  2. Unzip the contents of the ZIP file. It contains two script files related to encoding and hashing: 
    • EncodeAndHashScriptExample.json, que contiene un script de ejemplo en el que puede probar una función.

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

  3. Import ambos archivos en Studio.
  4. Copie el código del snippet de la acción Snippet en el archivo ExampleSnippetActions.json para la función que desea utilizar.
  5. Pegue el código copiado en la acción Snippet del archivo EncodeAndHashScriptExample.json.
  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.

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 función Descripción
EncodeBase64(Cadena de caracteres)

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

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 Base64 se pueden utilizar para codificar URL en aplicaciones web. Sin embargo, hay tres caracteres especiales utilizados en la codificación que deben analizarse de manera diferente en las URL. Los caracteres SOn el signo más ( + ), la barra diagonal ( / ) y el signo igual ( = ). Puede utilizar la función EncodeBase64Url para codificar correctamente la URL pasada como el 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 de caracteres

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 utilizan cálculos matemáticos para producir una cadena de salida de longitud fija. La cadena de salida, denominada hash, es útil para verificar la autenticidad de los datos con 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 produce una salida con hash de una longitud específica. Los algoritmos HMAC usan una combinación de claves secretas y funciones hash para producir la salida con 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 de hash y SOn reversibles. Studio no proporciona ninguna función de cifrado.

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

Proteja la seguridad de su clave secreta. Si se pierde la clave, todos los datos codificados con ella dejan de ser utilizables. 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). Incluye codificación Base64. Produce una salida con hash de 256 bits de longitud, compuesta por los datos fuente stringText y la secretKey.

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


add code examples here
		
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)

Esta función es igual que EncodeHS256, excepto que no incluye la codificación Base64. La salida con hash está compuesta por los datos fuente stringText y la 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). Produce una salida con hash de 384 bits de longitud, compuesta por los datos fuente stringText y la 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). Produce una salida con hash de 512 bits de longitud, compuesta por los datos fuente stringText y la 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 de autorización con tokens y OAuth

OAuth y la autenticación basada en tokens con JSON Web Tokens (JWT, o tokens) SOn DOs estándares para crear flujos de autenticación en las aplicaciones. Puede utilizarlos juntos para garantizar que la aplicación cliente pueda verificar eficientemente los detalles del usuario. Cuando el servidor de autenticación verifica con éxito las credenciales del usuario mediante 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 después de que se completa el flujo de autorización. El token contiene la información del usuario final.

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

Puede usar las siguientes funciones en sus scripts de Studio para incorporar un flujo de authorization 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:

El parámetro Tipo Descripción
apiURL Cadena de caracteres La URL de la terminal de la API con la que se está conectando.
Clave Cadena de caracteres La clave secreta que desea que use la secuencia de comandos al realizar operaciones hash con esta función.
iss Cadena de caracteres El emisor del token.
sub Cadena de caracteres El asunto del token.
aud Cadena de caracteres 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 ejemplo a continuación como payload.exp.
queryParams Datos dinámicos Los pares clave-valor que contienen los parámetros de consulta que desea incluir con 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.