Encoder et hacher des chaînes

Les informations contenues dans cette page d’aide s’appliquent à la fois à Studio et à Desktop Studio.

Studio prend en charge plusieurs fonctions que vous pouvez utiliser pour encoder ou hacher des données dans vos scripts. L’encodage et le hachage transforment tous deux les données dans un format différent. La façon dont les données changent et ce que vous pouvez en faire sont différents :

  • Encodage : Ce processus transforme les données dans un format qui peut être utilisé dans vos scripts ou transmis par ceux-ci à d’autres systèmes. L’encodage utilise un schéma, ou une méthode, qui est souvent accessible publiquement. Pour cette raison, la transformation n’est pas sécurisée. Cependant, l’objectif de l’encodage n’est pas de sécuriser les données, mais de s’assurer qu’elles peuvent être utilisées correctement sur le système récepteur. L’encodage peut être inversé pour ramener les données à leur format d’origine.
  • Hachage : Il s’agit d’un processus à sens unique qui convertit les données en une chaîne alphanumérique de longueur fixe. Une chaîne hachée est parfois appelée un hachage. Les hachages sont souvent utilisés pour vérifier l’intégrité des données. Lorsque deux chaînes identiques sont hachées avec le même algorithme, leurs hachages sont identiques. Si deux hachages créés avec le même algorithme ne correspondent pas, vous savez que les chaînes d’origine étaient également différentes. Ce processus peut être utilisé pour vérifier des données de sécurité, telles que des signatures numériques ou des mots de passe, sans avoir à transmettre des données sensibles en texte brut.

De plus, Studio prend en charge l’autorisation à l’aide de OAuth. Il s’agit d’une méthode permettant d’assurer la sécurité des interactions entre NiCE CXone et d’autres systèmes.

Cette page fournit des informations sur les fonctions que vous pouvez utiliser dans les scripts Studio pour encoder ou hacher des chaînes, ou pour configurer des flux d'autorisation avec OAuth. Elle ne fournit pas d'informations sur la façon d'implémenter ces solutions. Pour de plus amples informations sur les algorithmes que ces fonctions utilisent, consultez le site Web de l'Internet Engineering Task Force (IETF).

Le hachage est irréversible. Utilisez avec prudence toute fonction qui hache des chaînes et assurez-vous de bien comprendre comment la mettre en œuvre avant de l’utiliser avec des données en direct.

RestProxy

L’encodage et le hachage de chaînes dans Studio nécessitent l’utilisation de RestProxy, un service qui vous permet d’accéder à des API RESTful avec vos scripts. Il vous donne également accès aux fonctions utilisées pour l’encodage et le hachage. Les exemples d’extraits pour les fonctions que vous pouvez utiliser lors de l’encodage ou du hachage de chaînes incluent tous l’énoncé suivant, qui accède à RestProxy :

ASSIGN restProxy = new UCN.Data.RESTProxy()

Il est important que vous incluiez UCN.Data.RESTProxy() dans votre affectation de variable exactement comme indiqué. RESTProxy() est la fonction qui vous permet d’accéder aux fonctions utilisées pour encoder et hacher les données.

Exemples

Des exemples du code Snippet pour chaque fonction vous sont fournis afin que vous puissiez les utiliser dans vos scripts. Le code est également disponible pour être copié à partir de cette page d’aide dans le tableau qui décrit chaque fonction.

  1. Télécharger le fichier ZIP de l’exemple de script.
  2. Unzip the contents of the ZIP file. It contains two script files related to encoding and hashing: 
    • EncodeAndHashScriptExample.json, qui contient un exemple de script où vous pouvez tester une fonction.

    • ExampleSnippetActions.json, qui contient une action Snippet pour chaque algorithme de cette page. Chaque Snippet contient l’exemple de code pour cette fonction.

  3. Importez les deux fichiers dans Studio.
  4. Copiez le code de l’extrait à partir de l’action Snippet dans le fichier ExampleSnippetActions.json correspondant à la fonction que vous voulez utiliser.
  5. Collez le code copié dans l’action Snippet dans le fichier EncodeAndHashScriptExample.json.
  6. Configurez une interaction simulée et cliquez sur Démarrer avec trace. Vous pouvez également utiliser le débogueur dans la fenêtre de l’éditeur Snippet. Les deux options vous permettent de voir le contenu changeant des variables dans l’Extrait.

Fonctions d’encodage des chaînes

L’encodage transforme les données dans un format différent. Vous pouvez l’utiliser pour transmettre de grandes quantités de données, ou pour transmettre des données qui ne peuvent pas être transportées par le protocole utilisé. Les données encodées peuvent être reconverties dans leur format d’origine.

Il existe deux fonctions que vous pouvez utiliser pour encoder des chaînes. Tous deux utilisent le schéma Base64 pour encoder les données.

Nom de la fonction Description
EncodeBase64(string)

Les données binaires ne peuvent pas être transportées par certains protocoles. Vous pouvez utiliser cette fonction pour convertir les données binaires transmises avec le paramètre string dans un format qui peut être transporté.

L’action Extrait de code de l’exemple de script contient ce code :

ASSIGN restProxy = new UCN.Data.RESTProxy()

ASSIGN encodeThis = "This is the source data."

ASSIGN hashB64 = restProxy.EncodeBase64(encodeThis)
EncodeBase64Url(URL)

Les fonctions Base64 peuvent être utilisées pour encoder les URL dans les applications Web. Cependant, il existe trois caractères spéciaux utilisés dans l’encodage qui doivent être traités différemment dans les URL. Ces caractères sont le signe plus ( + ), la barre oblique ( / ), et le signe égal ( = ). Vous pouvez utiliser la fonction EncodeBase64Url pour encoder correctement l’URL transmise comme argument du paramètre URL.

L’action Extrait de code de l’exemple de script contient ce code :

ASSIGN restProxy = new UCN.Data.RESTProxy()

ASSIGN encodeThis = "https://example.com"

ASSIGN hashB64url = restProxy.EncodeBase64Url(encodeThis)

Fonction de décodage d’une chaîne

Utilisez cette fonction pour décoder une chaîne qui a été encodée avec la fonction EncodeBase64.

Nom de la fonction Description
DecodeBase64 (string)

Cette fonction reconvertit les données encodées (string) dans leur format d’origine.

L’action Extrait de code de l’exemple de script contient ce code :

ASSIGN restProxy = new UCN.Data.RESTProxy()

ASSIGN encodedString = "234sdf"

ASSIGN decodedString = restProxy.DecodeBase64(encodedString)

Fonctions pour hacher une chaîne avec une Clé secrète

Les fonctions de hachage utilisent des calculs mathématiques pour produire une chaîne de sortie de longueur fixe. La chaîne de sortie, appelée hachage, est utile pour vérifier l'authenticité des données hachées. Vous pouvez les utiliser pour vérifier des mots de passe, des signatures numériques, et ainsi de suite. Par exemple, vous pouvez stocker une version hachée d'un mot de passe. Lorsqu'un utilisateur saisit le mot de passe, vous pouvez le hacher et le comparer à la version hachée du mot de passe que vous avez stockée. S'ils sont identiques, le mot de passe est correct.

Les fonctions de hachage décrites dans cette section sont toutes des algorithmes de hachage à clé. Elles utilisent un algorithme de code d’authentification des messages basé sur le hachage (HMAC). Chaque algorithme produit une sortie hachée d’une longueur précise. Les algorithmes HMAC utilisent une combinaison de clés secrètes et de fonctions de hachage pour produire la sortie hachée. Le processus HMAC :

  1. Mélange une clé secrète avec les données du message.
  2. Hache le résultat avec la fonction de hachage.
  3. Mélange à nouveau la valeur de hachage avec la clé secrète.
  4. Applique la fonction de hachage une deuxième fois.

Les fonctions de hachage sont à sens unique. Cela signifie qu'elles ne peuvent pas être annulées. Pour cette raison, ces fonctions ne peuvent pas être utilisées pour chiffrer des données. Le Chiffrement utilise également des clés, tout comme les fonctions de hachage présentées dans cette Section. Cependant, les algorithmes de chiffrement n'incluent pas les algorithmes de hachage et sont réversibles. Studio ne fournit aucune fonction de chiffrement.

Il incombe à votre organisation d’obtenir la clé et de la partager avec l’entité ou le système destinataire.

Protégez la sécurité de votre clé secrète. Si la clé est perdue, toutes les données hachées avec cette clé seront inutilisables. Vous ne pouvez pas comparer des chaînes hachées avec deux clés différentes, même si les chaînes sont identiques.

Nom de la fonction Description
EncodeHS256(stringText, secretKey)

Cette fonction utilise HMACSHA256, un algorithme de hachage à clé construit à partir de l’algorithme de hachage SHA-256 et utilisé comme code d’authentification des messages basé sur le hachage (HMAC). Elle comprend l’encodage Base64. Elle produit une sortie hachée d’une longueur de 256 bits, composée des données source stringText et de la secretKey.

L’action Extrait de code de l’exemple de script contient ce code :



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)

Cette fonction est identique à EncodeHS256, sauf qu’elle ne comprend pas l’encodage Base64. La Sortie hachée est composée des données source stringText et de la secretKey.

L’action Extrait de code de l’exemple de script contient ce 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)

Cette fonction utilise HMACSHA384, un algorithme de hachage à clé construit à partir de l’algorithme de hachage SHA-384 et utilisé comme code d’authentification des messages basé sur le hachage (HMAC). Elle produit une sortie hachée d’une longueur de 384 bits, composée des données source stringText et de la secretKey.

L’action Extrait de code de l’exemple de script contient ce 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.

L’action Extrait de code de l’exemple de script contient ce code :

ASSIGN restProxy = new UCN.Data.RESTProxy()

ASSIGN hashThis = "This is the source data."

ASSIGN key = "mykey"

ASSIGN hashHS512 = restProxy.EncodeHS512(hashThis, key)

Fonctions pour l’autorisation avec jetons et OAuth

OAuth et l’authentification basée sur les jetons avec les jetons Web JSON (JWT, ou jetons) sont deux normes permettant d’intégrer des flux d’authentification dans les applications. Vous pouvez les utiliser ensemble pour vous assurer que l’application cliente peut vérifier efficacement les détails de l’utilisateur. Lorsque le serveur d’authentification vérifie avec succès les informations d’identification de l’utilisateur via OAuth, il doit également transmettre les détails de l’utilisateur à l’application cliente.

Pour utiliser ces fonctions, vous devez disposer d’un serveur d’authentification. Lorsque des jetons sont utilisés, le serveur OAuth envoie le jeton à l’application cliente une fois le flux d’autorisation terminé. Le jeton contient les informations de l’utilisateur final.

Les fonctions disponibles pour utilisation dans les scripts combinent la norme OAuth pour l’authentification des utilisateurs et des clients avec l’algorithme de hachage HMACSHA256. La norme OAuth est définie dans la RFC7523, qui figure dans le nom des fonctions dans Studio.

Vous pouvez utiliser les fonctions suivantes dans vos scripts Studio pour intégrer un flux d’autorisation avec OAuth et des jetons :

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

Les jetons comportent trois parties : un en-tête, une charge utile et une signature. Ces fonctions comportent de nombreux paramètres, qui fournissent des données utilisées pour créer ces parties. Les paramètres sont définis dans le tableau suivant :

Paramètre Catégorie Description
apiURL string L’URL du terminal de l’API auquel vous vous connectez.
clé string La clé secrète que vous voulez que le script utilise lors du hachage avec cette fonction.
iss string L’émetteur du jeton.
sub string L’objet du jeton.
aud string Le consommateur prévu du jeton. Habituellement, il s’agit du serveur d’autorisation auquel le client souhaite accéder.
jwtHeaderData Données dynamiques Les données que vous souhaitez inclure dans l’en-tête du jeton.
jwtPayloadData Données dynamiques Les paires clé-valeur qui contiennent toute charge utile que vous devez inclure dans le jeton. Il peut s’agir du délai d’expiration du jeton. Ceci est illustré dans l’extrait d’exemple ci-dessous sous la forme payload.exp.
queryParams Données dynamiques Les paires clé-valeur qui contiennent les paramètres de requête que vous voulez inclure avec le jeton. Ceci est inclus uniquement dans les fonctions étendues.
requestHeaders Données dynamiques Les paires clé-valeur qui contiennent les informations d’en-tête de la demande. Ceci est inclus uniquement dans les fonctions étendues.

L’action Extrait de code de l’exemple de script contient ce 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)

Le script d’exemple contient du code pour chacune des fonctions disponibles. Cet exemple ne couvre que deux des six fonctions disponibles.