Codificar e embaralhar (hash) strings

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

  • Codificar: Este processo transforma dados em um formato que pode ser usado ou passado pelo seu script para outros sistemas. Codificar usa um esquema, ou método, que frequentemente está disponível ao público. 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. Codificações podem ser revertidas para retornar dados ao formato original.
  • Embaralhar: Este é um processo unidirecional que converte dados em uma string 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. Este processo pode ser usado para verificar dados de segurança, como assinaturas ou senhas digitais, sem a necessidade de passar dados sigilosos usando texto simples.

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

Esta página fornece informações sobre as funções que você pode usar nos scripts Studio para codificar ou criptografar strings e comandos ou para configurar fluxos de autorização com OAuth. Ela não fornece informações sobre como implementar estas soluções. Para mais informações sobre os algoritmos que essas funções usam, consulte a página da Força Tarefa de Engenharia de Internet (IETF, na sigla em inglês).

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

Codificar e embaralhar strings no Studio exige o uso do RestProxy, um serviço que permite que você acesse APIs RESTful com seus scripts. Ele também fornece acesso às funções usadas para codificar e embaralhar (hashing). Os snippets de exemplo para as funções que você pode usar ao codificar ou embaralhar strings incluem a seguinte instrução que acessa o RestProxy:

ASSIGN restProxy = new UCN.Data.RESTProxy()

É importante que você inclua UCN.Data.RESTProxy() na sua atribuição de variável exatamente como ilustrado. RESTProxy() é a função que permite seu acesso às funções usadas para codificar e embaralhar (hash) dados.

Exemplos

Exemplos de código Snippet para cada função são fornecidos para você usar nos seus scripts. O código também está disponível para cópia nesta página de ajuda, na tabela que descreve cada função.

  1. Baixar o arquivo ZIP com o script de exemplo.
  2. Extraia o conteúdo do arquivo ZIP. Ele contém dois arquivos de script:

    • EncodeAndHashScriptExample.xml, que contém um script de exemplo onde você pode testar uma função.

    • ExampleSnippetActions.xml, que contém uma ação de 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 XML para o Studio.
  4. Copie o código do snippet a partir da ação Snippet no arquivo ExampleSnippetActions.xml para a função que você quer usar.
  5. Cole o código copiado na ação Snippet no arquivo EncodeAndHashScriptExample.xml.
  6. Configure uma interação simulada e clique em Start with Trace. Você também pode usar o depurador na janela do Editor snippet. Ambas as opções permitem que você veja os conteúdos 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. Dados codificados podem ser convertidos de volta ao 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(string)

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 para um formato que pode 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)

Funções Base64 podem ser usadas para codificar URLs em aplicativos web. No entanto, há três caracteres especiais usados em codificações que devem ser analisados diferentemente em URLs. Esses caracteres são o sinal de adição ( + ), barra para a frente ( / ) e sinal de igual ( = ). Você pode usar a função EncodeBase64Url para codificar adequadamente o URL passado como o 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 uma string

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 dados codificados (string) de volta ao 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

Funções hash usam cálculos matemáticos para produzir uma string de saída de tamanho fixo. A string de saída, chamada de hash, é útil para verificar a autenticidade de um dado com 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. Elas usam um algoritmo com Código de autenticação de mensagem baseado em hash (HMAC). Cada algoritmo produz uma saída embaralhada (hashed) com um tamanho específico. Algoritmos HMAC usam uma combinação de chaves sigilosas e funções hash para produzir a saída embaralhada (hashed). 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, 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.

Mantenha a sua chave secreta em segurança. Se perder a chave, todos os dados com ela embaralhados não poderão ser mais usados. 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 produz uma saída embaralhada (hashed) de 256 bits, composta pelos dados da fonte stringText e 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 hashHS256 = restProxy.EncodeHS256(hashThis, key)
EncodeHS256NoBaseEncoding(stringText, secretKey)

Esta função é a mesma que EncodeHS256, porém não inclui codificação Base64. A saída embaralhada (hashed) é composta pelos dados da fonte stringText e 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 embaralhada (hashed) de 384 bits, composta pelos dados da fonte stringText e 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 embaralhada (hashed) de 512 bits, composta pelos dados da fonte stringText e 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ções para autorização com Tokens e OAuth

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

Para usar estas funções, você precisa ter um servidor de autenticação disponível. Quando tokens são usados, o servidor OAuth envia o token ao aplicativo do cliente depois que o fluxo de autorização é concluído. 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ários e clientes com o algoritmo de embaralhamento (hashing) HMACSHA256. O padrão Oauth é definido em RFC7523, que está no nome das funções no Studio.

Você pode usar as seguintes funções nos 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 string O URL do terminal do API ao qual você está se conectando.
key string A chave secreta que você quer que o script use ao ser embaralhado (hashed) com esta função.
iss string O emissor do token.
sub string O assunto do token.
aud string 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 valores de chave que contém qualquer carga útil que você precisa incluir no token. Isso pode incluir o tempo de expiração do token. Isso é mostrado no script de exemplo abaixo como payload.exp.
queryParams Dados dinâmicos Os pares de valores de chave que contém os parâmetros de consulta que você deseja incluir no token. Isso é incluído apenas nas funções Estendidas.
requestHeaders Dados dinâmicos Os pares de valores de chave que contém a informação do cabeçalho de pedido. 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.