Codage et hachage de chaînes

Studio prend en charge plusieurs fonctions que vous pouvez utiliser pour coder ou hacher des données dans vos scripts. Le codage 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 :

  • Codage : ce processus transforme les données dans un format qui peut être utilisé ou transmis par vos scripts à d'autres systèmes. Le codage utilise un schéma, ou une méthode, qui est souvent publiquement accessible. La transformation n'est donc pas sécurisée. Cependant, l'objectif du codage 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. Le codage 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 « 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 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. Elle 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 toute fonction de hachage de chaînes avec prudence et assurez-vous de bien comprendre comment la mettre en œuvre avant de l'utiliser avec des données réelles.

RestProxy

Le codage 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 le codage 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 affectation de variable exactement comme indiqué. RESTProxy() est la fonction qui vous permet d'accéder aux fonctions utilisées pour coder 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 peut également être copié à partir de cette page d'aide dans le tableau qui décrit chaque fonction.

  1. Téléchargez le fichier ZIP du script d'exemple.
  2. Décompressez le contenu du fichier ZIP. Il contient deux fichiers de script :

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

    • ExampleSnippetActions.xml, 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 XML dans Studio.
  4. Copiez le code de l'action Snippet dans le fichier ExampleSnippetActions.xml pour la fonction que vous voulez utiliser.
  5. Collez le code copié dans l'action Snippet du fichier EncodeAndHashScriptExample.xml .
  6. Définissez une interaction simulée et cliquez sur Start with Trace. Vous pouvez également utiliser le débogueur dans la fenêtre de l'éditeur de snippets. Les deux options vous permettent de voir les changements de contenu des variables dans le snippet.

Fonctions de codage de chaînes

Le codage 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 codées peuvent être reconverties dans leur format d'origine.

Il existe deux fonctions permettant de coder les chaînes de caractères. Elles utilisent toutes deux le schéma Base64 pour coder 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 Snippet dans le script d'exemple 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 coder les URL dans les applications web. Cependant, trois caractères spéciaux utilisés dans le codage 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 coder correctement l'URL transmise en tant qu'argument du paramètre URL.

L'action Snippet dans le script d'exemple 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é codée avec la fonction EncodeBase64.

Nom de la fonction Description
DecodeBase64 (string)

Cette fonction rétablit les données codées (string) à leur format d'origine.

L'action Snippet dans le script d'exemple 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 utiliser ces fonctions 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 à sens unique. Cela signifie qu'elles ne peuvent pas être annulées. C'est la raison pour laquelle 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 à la sécurité de votre clé secrète. Si la clé est perdue, toutes les données hachées avec elle ne sont plus utilisables. 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 Snippet dans le script d'exemple 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 le codage Base64. La sortie hachée est composée des données sources stringText et de secretKey.

L'action Snippet dans le script d'exemple 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 Snippet dans le script d'exemple 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 Snippet dans le script d'exemple 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 d'autorisation avec Jetons et OAuth

OAuth et l'authentification basée sur des jetons avec JSON Web Tokens (JWTs, ou tokens) 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 valide 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 en vue d’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 la RFC7523, qui se trouve dans le nom des fonctions de 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 parties. Les paramètres sont définis dans le tableau suivant :

Paramètre Type Description
apiURL chaîne de caractères L'URL du point de terminaison de l'API auquel vous vous connectez.
key chaîne de caractères La clé secrète que vous voulez que le script utilise lors du hachage avec cette fonction.
iss chaîne de caractères L'émetteur du jeton.
sub chaîne de caractères L'objet du jeton.
aud chaîne de caractères Le consommateur prévu du jeton. Il s'agit généralement du serveur d'autorisation auquel le client veut accéder.
jwtHeaderData Données dynamiques Les données que vous voulez 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 de snippet 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. 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 Snippet dans le script d'exemple 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.