Codificar e embaralhar (hash) strings

As informações desta página de ajuda se aplicam tanto a Studio quanto a Desktop Studio.

Studio suporta várias funções que você pode usar para codificar ou embaralhar dados nos seus scripts. Tanto a codificação quanto o hashing transformam dados em um formato diferente. A forma como os dados são alterados e o que você pode fazer com eles é diferente:

  • Codificação: Este processo transforma dados em um formato que pode ser usado em seus Scripts ou transmitido por eles a outros sistemas. Codificação utiliza um esquema, ou método, que geralmente está disponível publicamente. Por causa disso, a transformação não é segura. No entanto, o objetivo de codificar não é proteger os dados, e sim garantir que estejam sendo usados adequadamente pelo sistema de destino. A codificação pode ser revertida para retornar os dados ao seu formato original.
  • Hash: Este é um processo unidirecional que converte dados em uma cadeia alfanumérica de tamanho fixo. Uma string embaralhada é às vezes chamada de hash. Hashes são frequentemente usadas para verificar a integridade de dados. Quando duas strings idênticas são embaralhadas (hashed) com o mesmo algoritmo, suas hashes são as mesmas. Se duas hashes criadas com o mesmo algoritmo não corresponderem, você sabe que as strings originais também eram diferentes. Esse processo pode ser usado para verificar dados de segurança, como assinaturas digitais ou senhas, sem a necessidade de passar dados confidenciais em texto simples.

Além disso, Studio oferece suporte à autorização usando OAuth. Este é um método de fornecer segurança a interações entre o NiCE CXone e outros sistemas.

Esta página fornece informações sobre as funções que você pode usar em scripts do Studio para codificar ou hash de strings, ou para configurar fluxos de autorização com OAuth. Ela não fornece informações sobre como implementar estas soluções. Para obter mais informações sobre os algoritmos que essas funções usam, consulte o site do Internet Engineering Task Force (IETF).

O processo de embaralhamento (hashing) é irreversível. Use qualquer função que embaralhe (hash) strings com cautela e certifique-se de que entende como implementá-las antes de usá-las com dados reais.

RestProxy

A codificação e o hash de strings em Studio requer o uso do RestProxy, um serviço que permite que você acesse API RESTful com seus scripts. Ele também fornece acesso às funções usadas para codificar e embaralhar (hashing). Os exemplos de snippet das funções que você pode usar ao codificar ou fazer hash de strings incluem todos a seguinte instrução, que acessa o RestProxy:

ASSIGN restProxy = new UCN.Data.RESTProxy()

É importante que você inclua UCN.Data.RESTProxy() na atribuição de variável exatamente como mostrado. RESTProxy() é a função que permite acessar as funções usadas para codificar e fazer hash dos dados.

Exemplos

Exemplos do código Snippet para cada função são fornecidos para que você os utilize em seus Scripts. O código também está disponível para cópia a partir desta página de ajuda, na tabela que descreve cada função.

  1. Baixar o arquivo ZIP com o script de exemplo.
  2. Unzip the contents of the ZIP file. It contains two script files related to encoding and hashing: 
    • EncodeAndHashScriptExample.json, que contém um exemplo de script em que você pode testar uma função.
    • ExampleSnippetActions.json, que contém uma ação Snippet para cada algoritmo nesta página. Cada snippet contém o código de amostra para a função.

  3. Importar ambos os arquivos para Studio.
  4. Copie o código do snippet da ação Snippet no arquivo ExampleSnippetActions.json referente à função que você deseja usar.
  5. Cole o código copiado na ação Snippet no arquivo EncodeAndHashScriptExample.json.
  6. Configurar uma interação simulada e clique em Iniciar com Rastreamento. Você também pode usar o depurador na janela do editor Snippet. Ambas as opções permitem que você veja o conteúdo em alteração das variáveis no snippet.

Funções para codificar strings

Codificar transforma dados para um formato diferente. Você pode codificar para transmitir grandes quantidades de dados ou para transmitir dados que não podem ser transportados pelo protocolo sendo usado. Os dados codificados podem ser convertidos novamente para seu formato original.

Há duas funções que você pode usar para codificar strings. Ambas usam o esquema Base64 para codificar os dados.

Nome da função Descrição
EncodeBase64(sequência)

Dados binários não podem ser transportados por alguns protocolos. Você pode usar esta função para converter dados binários passados com o parâmetro string em um formato que possa ser transportado.

A ação Snippet no snippet de exemplo contém este código:

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

As funções Base64 podem ser usadas para codificar URLs em aplicativos da web. No entanto, há três caracteres especiais usados na codificação que devem ser analisados de forma diferente nas URLs. Os caracteres são o sinal de mais ( + ), a barra ( / ) e o sinal de igual ( = ). Você pode usar a função EncodeBase64Url para codificar corretamente a URL passada como argumento do parâmetro URL.

A ação Snippet no snippet de exemplo contém este código:

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

Função para decodificar um comando

Use esta função para decodificar uma string que foi codificada com a função EncodeBase64.

Nome da função Descrição
DecodeBase64 (string)

Esta função reverte os dados codificados (string) para seu formato original.

A ação Snippet no snippet de exemplo contém este código:

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

Funções para embaralhar (hash) uma string com uma senha secreta

As funções de hash usam cálculos matemáticos para produzir uma string de saída de tamanho fixo. A saída da string, chamada de hash, é útil para verificar a autenticidade dos dados que sofreram hash. Você pode usá-las para verificar senhas, assinaturas digitais e assim por diante. Por exemplo, você pode armazenar uma versão com hash de uma senha. Quando o usuário insere a senha, você pode aplicar hash a ela e compará-la à versão com hash da senha que armazenou. Se elas são as mesmas, a senha está correta.

As funções de embaralhamento (hash) descritas nesta seção são todas algoritmos hash chaveados. Eles usam um algoritmo HMAC (Hash-based Mensagem Authentication Code). Cada algoritmo produz uma saída com hash de um comprimento específico. Os algoritmos HMAC usam uma combinação de chaves secretas e funções de hash para produzir a saída com hash. O processo HMAC:

  1. Combina uma chave secreta com os dados da mensagem.
  2. Embaralha o resultado com a função embaralhar (hash).
  3. Combina o valor embaralhado com a chave secreta de novo.
  4. Aplica a função embaralhar (hash) uma segunda vez.

Funções hash são unidirecionais.Isso significa que elas não podem ser desfeitas. Por este motivo, estas funções não podem ser usadas para criptografar dados. Criptografias sempre usam senhas, assim como as funções hash nessa seção. No entanto, os algoritmos de criptografia não incluem os algoritmos de hash e são reversíveis. Studio não fornece nenhuma função de criptografia.

É responsabilidade da sua organização obter a chave e compartilhá-la com a entidade ou sistema de destino.

Proteja a segurança da sua chave secreta. Se a chave for perdida, todos os dados associados a ela por hash deixam de ser utilizáveis. Não é possível comparar strings embaralhadas (hashed) com duas chaves diferentes, mesmo se as strings forem idênticas.

Nome da função Descrição
EncodeHS256(stringText, secretKey)

Esta função usa HMACSHA256, um algoritmo de embaralhamento (hash) chaveado criado a partir do algoritmo de hash SHA-256 e usado como um Código de autenticação de Mensagem baseado em hash (HMAC). Ela inclui codificação Base64. Ela produz uma saída em hash de 256 bits de comprimento, composta pelos dados de origem stringText e pela secretKey.

A ação Snippet no snippet de exemplo contém 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 função é a mesma que EncodeHS256, exceto que não inclui a codificação Base64. A saída em hash é composta pelos dados de origem stringText e pela secretKey.

A ação Snippet no snippet de exemplo contém 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 função usa HMACSHA384, um algoritmo de embaralhamento (hash) chaveado criado a partir do algoritmo de hash SHA-384 e usado como um Código de autenticação de Mensagem baseado em hash (HMAC). Ela produz uma saída com hash de 384 bits de comprimento, composta pelos dados de fonte stringText e pela secretKey.

A ação Snippet no snippet de exemplo contém 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 função usa HMACSHA512, um algoritmo de embaralhamento (hash) chaveado criado a partir do algoritmo de hash SHA-512 e usado como um Código de autenticação de Mensagem baseado em hash (HMAC). Ela produz uma saída com hash de 512 bits de comprimento, composta pelos dados de origem stringText e pela secretKey.

A ação Snippet no snippet de exemplo contém 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) 

Funçoes para Autorização com Tokens e OAuth

OAuth e a autenticação baseada em token com JSON Web Tokens (JWTs, ou tokens) são dois padrões para a criação de fluxos de autenticação em aplicativos. Você pode usá-los juntos para garantir que o aplicativo cliente possa verificar com eficiência os detalhes do usuário. Quando o servidor de autenticação verifica com sucesso as credenciais do usuário por meio de OAuth, ele também deve transmitir os detalhes do usuário para o aplicativo cliente.

Para usar estas funções, você precisa ter um servidor de autenticação disponível. Quando os tokens são usados, o servidor OAuth envia o token para o aplicativo cliente após a conclusão do fluxo de autorização. O token contém as informações do usuário final.

As funções disponíveis para uso em scripts combinam o padrão OAuth para autenticação de usuário e cliente com o algoritmo de hash HMACSHA256. O padrão OAuth é definido na RFC7523, que está no nome das funções em Studio.

Você pode usar as seguintes funções em seus scripts Studio para incorporar um fluxo de autorização com OAuth e 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)

Tokens têm três partes: um cabeçalho, uma carga útil e uma assinatura. Estas funções têm vários parâmetros, os quais fornecem dados para serem usados para criar essas partes. Os parâmetros são definidos na tabela a seguir:

Parâmetro Tipo Descrição
apiURL Sequência O URL DO terminal da API ao qual você está se conectando.
Chave Sequência A chave secreta que você quer que o script use ao ser embaralhado (hashed) com esta função.
iss Sequência O emitente do token.
sub Sequência Assunto do token.
aud Sequência O consumidor visado pelo token. Normalmente, este é o servidor de autorização que o cliente quer acessar.
jwtHeaderData Dados dinâmicos Os dados que você quer incluir no cabeçalho do token.
jwtPayloadData Dados dinâmicos Os pares de chave-valor que armazenam qualquer carga útil que você precise incluir no token. Isso pode incluir o tempo de expiração do token. Isso é mostrado no exemplo de Snippet abaixo como payload.exp.
queryParams Dados dinâmicos Os pares de chave-valor que contêm os parâmetros de consulta que você deseja incluir com o token. Isso é incluído apenas nas funções Estendidas.
requestHeaders Dados dinâmicos Os pares de chave-valor que contêm as informações do cabeçalho da solicitação. Isso é incluído apenas nas funções Estendidas.

A ação Snippet no snippet de exemplo contém 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)

O script de amostra tem um código para cada função disponível. Este exemplo descreve apenas duas das seis funções disponíveis.