Encoder et hacher des chaînes

Les informations contenues dans cette page d’aide s’appliquent à la fois à CXone 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 varient :

  • Encodage : Ce processus transforme les données dans un format qui peut être utilisé ou transmis par vos scripts à d’autres systèmes. L’encodage utilise un schéma, ou une méthode, qui est souvent accessible au public. 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 unidirectionnel qui convertit les données en une chaîne alphanumérique de longueur fixe. Une chaîne hachée est parfois appelée « hash ». 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 de caractères originales étaient également différentes. Ce processus peut être utilisé pour vérifier les données de sécurité, telles que les signatures numériques ou les mots de passe, sans avoir à transmettre des données sensibles en texte clair.

En outre, Studio prend en charge l’autorisation à l’aide d’OAuth. Il s’agit d’une méthode permettant de sécuriser les interactions entre 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. Il ne fournit pas d’informations sur la manière de mettre en œuvre ces solutions. Pour plus d’informations sur les algorithmes utilisés par ces fonctions, consultez le site Web de l’IETF (Internet Engineering Task Force).

Le hachage est irréversible. Utilisez les fonctions de hachage de chaînes avec prudence et assurez-vous de bien comprendre comment les mettre en œuvre avant de les utiliser avec des données réelles.

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 aux API RESTful avec vos scripts. Il vous donne également accès aux fonctions utilisées pour l’encodage et le hachage. Les exemples de fonctions que vous pouvez utiliser pour encoder ou hacher des chaînes comprennent tous l’instruction suivante, qui accède à RestProxy :

ASSIGN restProxy = new UCN.Data.RESTProxy()

Il est important que vous incluiez UCN.Data.RESTProxy() dans votre assignation 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 de code Snippet pour chaque fonction sont fournis pour 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échargez le fichier ZIP de l’exemple de script.
  2. Décompressez le contenu du fichier ZIP. Il contient deux fichiers de script :

    • EncodeAndHashScriptExample.xml, qui contient un exemple de script dans lequel vous pouvez tester une fonction.

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

  3. Importez les deux fichiers XML dans Studio.
  4. Copiez le code de l’action Extrait de code dans le fichier ExampleSnippetActions.xml pour la fonction que vous souhaitez utiliser.
  5. Collez le code copié dans l’action Extrait de code du fichier EncodeAndHashScriptExample.xml.
  6. Configurez une interaction simulée et cliquez sur Start with Trace. Vous pouvez également utiliser le débogueur dans la fenêtre de l’éditeur d’extraits de code. Les deux options vous permettent de voir les changements de contenu des variables dans l’extrait de code.

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 permettant d’encoder les 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, trois caractères spéciaux utilisés dans l’encodage doivent être analysés différemment dans les URL. Les 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 en tant qu’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 ramène les données encodées (string) à 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 d’une 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 les mots de passe, les signatures numériques, etc. 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 un résultat haché d’une longueur spécifique. Les algorithmes HMAC utilisent une combinaison de clés secrètes et de fonctions de hachage pour produire le résultat haché. 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 unidirectionnelles. Cela signifie qu’elles ne peuvent pas être annulées. C’est pourquoi 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 de cette section. Toutefois, les algorithmes de chiffrement ne comprennent 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.

Veillez à protéger 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 produit un résultat haché d’une longueur de 256 bits, composé des données sources stringText et de 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 hashHS256 = restProxy.EncodeHS256(hashThis, key)
EncodeHS256NoBaseEncoding(stringText, secretKey)

Cette fonction est identique à EncodeHS256, sauf qu’elle n’inclut pas l’encodage Base64. La sortie hachée est composée des données sources stringText et de 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 un résultat haché d’une longueur de 384 bits, composé des données sources stringText et de 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) Cette fonction utilise HMACSHA512, un algorithme de hachage à clé construit à partir de l’algorithme de hachage SHA-512 et utilisé comme code d’authentification des messages basé sur le hachage (HMAC). Elle produit un résultat haché d’une longueur de 512 bits, composé des données sources stringText et de 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 de hachage d’une chaîne avec une paire de clés publiques/privées

Les fonctions de hachage utilisent des calculs mathématiques pour produire une chaîne de sortie d’une 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 les mots de passe, les signatures numériques, etc. 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.

Ces fonctions utilisent les algorithmes RSA et SHA. RSA est un ensemble d’algorithmes cryptographiques qui utilisent des paires de clés publiques/privées. SHA est un ensemble d’algorithmes de hachage. Ensemble, ils génèrent des hachages de longueur fixe. Trois fonctions sont prises en charge, chacune produisant un hachage d’une longueur différente. La clé privée est utilisée pour créer le hachage. La clé publique est utilisée pour la vérifier.

Les fonctions de hachage sont unidirectionnelles. Cela signifie qu’elles ne peuvent pas être annulées. C’est pourquoi 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 de cette section. Toutefois, les algorithmes de chiffrement ne comprennent pas les algorithmes de hachage et sont réversibles. Studio ne fournit aucune fonction de chiffrement.

Les fonctions de hachage décrites dans cette section nécessitent toutes que vous génériez et installiez un certificat SSL sur votre CXone locataireFermé Regroupement organisationnel de haut niveau utilisé pour gérer le support technique, la facturation et les paramètres globaux pour votre environnement CXone. Le certificat contient les clés publiques et privées que ces fonctions utilisent. Contactez votre Représentant de compte CXone pour obtenir de l’aide dans cette procédure.

Cette option nécessite l’assistance de NICE CXone pour configurer le certificat pour votre système. Contactez votre Représentant de compte CXone pour plus d’informations.

Nom de la fonction Description
EncodeRS256(stringText)

Cette fonction utilise l’algorithme RS256, également connu sous le nom de RSA Signature avec SHA-256. La longueur du résultat du hachage dépend de la longueur de la clé privée utilisée. Le hachage est constitué des données source stringText et de la clé privée qui fait partie du certificat SSL que vous installez avec CXone.

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

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

Cette fonction utilise l’algorithme RS384, également connu sous le nom de RSA Signature avec SHA-384. La longueur du résultat du hachage dépend de la longueur de la clé privée utilisée. Le hachage est constitué des données source stringText et de la clé privée qui fait partie du certificat SSL que vous installez avec CXone.

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

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

Cette fonction utilise l’algorithme RS512, également connu sous le nom de RSA Signature avec SHA-512. La longueur du résultat du hachage dépend de la longueur de la clé privée utilisée. Le hachage est constitué des données source stringText et de la clé privée qui fait partie du certificat SSL que vous installez avec CXone.

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

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

Fonctions d’autorisation avec jetons et OAuth

OAuth et l’authentification basée sur des jetons avec JSON Web Tokens (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 données 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 relatives à l’utilisateur final.

Les fonctions disponibles pour une 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 RFC7523, qui se trouve dans le nom des fonctions dans Studio.

Vous pouvez utiliser les fonctions suivantes dans vos scripts Studio pour incorporer 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 ont de nombreux paramètres, qui fournissent des données utilisées pour créer ces pièces. Les paramètres sont définis dans le tableau suivant :

Paramètre Type Description
apiURL string L’URL du terminal de l’API auquel vous vous connectez.
key 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. Il s’agit généralement 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’exemple d’extrait de code ci-dessous sous la forme suivante : payload.exp.
queryParams Données dynamiques Les paires clé-valeur qui contiennent les paramètres de requête que vous souhaitez inclure avec le jeton. Cette fonction n’est incluse que dans les fonctions étendues.
requestHeaders Données dynamiques Les paires clé-valeur qui contiennent les informations de l’en-tête de la demande. Cette fonction n’est incluse que 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)

L’exemple de script contient du code pour chaque fonction disponible. Cet exemple ne couvre que deux des six fonctions disponibles.