Criando um hash de autenticação

Observação

Esse recurso requer as chaves de criptografia do serviço de usuário corporativo. Você pode obter essa informação na seção “Usuários corporativos” dentro da plataforma AnnA

Variáveis POST

• HASH: Hash da empresa
• ANNAEXEC: O IV que foi gerado, esse deve ser utilizado para encriptação dos valores de outras variáveis
• ACTION: Ação a ser executada
  • GENERATE_USER_HASH: Gera um hash de autenticação para o usuário especificado (USER_ID)
  • GENERATE_USER_HASH_FORCE_USER: Cria ou atualiza um usuário com os valores de USER_ID e USER_NAME, e gera um hash de autenticação
  • INACTIVATE_USER: Inativa o usuário informado (USER_ID)
  • MESSENGER_STRUCTURE: Retorna um json informando uma lista de departamento (alias e nome) e a lista de canais de cada departamento (alias e nome) da empresa solicitante.
  • MESSENGER_ALERT_COUNTER:
    • Retorna um json informando a quantidade de requisições com status “Aberta” que estão com a situação pendente de resposta para o usuário informado na variável USER_ID ou pelo conjunto dos valores informados nas variáveis MESSENGER_UNIQUE_DOC_TYPE e MESSENGER_UNIQUE_DOC_VALUE
    • Pode-se ainda informar um filtro para a consulta na variável MESSENGER_FILTER informando os campos de departamento, canal, data inicial e data final
  • MESSENGER_REQUESTS:
    • Retorna um json com uma coleção das requisições do usuário informado na variável USER_ID ou pelo conjunto dos valores informados nas variáveis MESSENGER_UNIQUE_DOC_TYPE e MESSENGER_UNIQUE_DOC_VALUE contendo as seguintes informações: Departamento, canal, descrição da requisição, data da abertura, protocolo, status (aberta/encerrada), um flag indicando se está pendente de resposta por parte do usuário e um link para visualização da requisição em questão
    • Pode-se ainda informar um filtro para a consulta na variável MESSENGER_FILTER informando os campos de departamento, canal, data inicial e data final, Status (A-abertas, E-encerradas) e Pendentes (S/N - pendente de resposta pelo usuário ou não)
  • MESSENGER_LINK:
    • Retorna um json informando o link para a visualização completa da mensageria do usuário informado na variável USER_ID ou pelo conjunto dos valores informados nas variáveis MESSENGER_UNIQUE_DOC_TYPE e MESSENGER_UNIQUE_DOC_VALUE
• USER_ID: ID do usuário corporativo
• USER_NAME: Nome do usuário corporativo
• MESSENGER_UNIQUE_DOC_TYPE: Contém o tipo de documento para identificação única do usuário na mensageria. Ex.: CPF, RG, RA, etc… Deve ser encriptado usando a chave de encriptação e o IV gerado.
• MESSENGER_UNIQUE_DOC_VALUE: Contém o valor do documento para identificação única do usuário na mensageria. Ex.: 715.037.620-76. Deve ser encriptado usando a chave de encriptação e o IV gerado.
• MESSENGER_FILTER: (OPCIONAL) Contém filtros a serem aplicados para as actions MESSENGER_ALERT_COUNTER e MESSENGER_REQUESTS. Deve ser encriptado usando a chave de encriptação e o IV gerado.
  • Deve ser informado o json no formato abaixo:

    {
    "DepartmentAlias":"CENTRALATEND",
    "ChannelAlias": "ATENDINICIAL",
    "DataIni": "01/01/2024",
    "DataFim": "01/05/2024",
    "Status": "A",
    "Pendentes": "S"
    }

• START_SERVICE: (Opcional) Define o serviço que irá iniciar ao abrir o AnnA Chat

Exemplos

Observação

Toda comunicação entre AnnA e cliente trafega com criptografia 3DES-CBC (Cipher Block Chaining) com block size de 64 e key size 192 bytes

Veja mais sobre a criptografia utilizada pela AnnA

C#/.NET Framework

Dica

Para aplicações .NET Framework e .NET, um pacote AnnA.Services está disponível em: https://www.nuget.org/packages/AnnA.Services

  public string Post()
  {
      string companyHash = "YOUR_COMPANY_HASH";
      string encryptionKey = "YOUR_CORPORATE_USER_ENCRYPTION_KEY";
      string decryptionKey = "YOUR_CORPORATE_USER_DECRYPTION_KEY";
      string iv = GenerateIV();

      string action = "GENERATE_USER_HASH"; // GENERATE_USER_HASH || GENERATE_USER_HASH_FORCE_USER || INACTIVATE_USER
      string userId = "USER_ID";
      string username = "USERNAME";
      string startService = "START_SERVICE";

      // Only for MESSENGER actions and GENERATE_USER_HASH_FORCE_USER
      string uniqueDocType = "UNIQUE_DOC_TYPE";
      string uniqueDocValue = "UNIQUE_DOC_VALUE";

      // Only for MESSENGER_ALERT_COUNTER and MESSENGER_REQUESTS actions
      string messengerFilters = new
      {
          DepartmentAlias = "DEPARTMENT_ALIAS",
          ChannelAlias = "CHANNEL_ALIAS",
          DataIni = "START_DATE", // dd/MM/yyyy
          DataFim = "END_DATE", // dd/MM/yyyy
          Status = "STATUS", // A | E
          Pendentes = "PENDENTES" // S | N
      }

      string url = "YOUR_ANNA_URL/aannacorporateuser.aspx";

      string encryptedAction = Encrypt(action, encryptionKey, iv);
      string encryptedUserId = Encrypt(userId, encryptionKey, iv);
      string encryptedUserName = Encrypt(username, encryptionKey, iv);
      string encryptedStartService = Encrypt(startService, encryptionKey, iv);
      string encryptedUniqueDocType = Encrypt(uniqueDocType, encryptionKey, iv);
      string encryptedUniqueDocValue = Encrypt(uniqueDocValue, encryptionKey, iv);
      string encryptedMessengerFilters = Encrypt(JsonSerializer.Serialize(messengerFilters), encryptionKey, iv);

      string dadosPost = "HASH=" + Uri.EscapeDataString(companyHash);
      dadosPost += "&ANNAEXEC=" + Uri.EscapeDataString(iv);
      dadosPost += "&ACTION=" + Uri.EscapeDataString(encryptedAction);
      dadosPost += "&USER_ID=" + Uri.EscapeUriString(encryptedUserId);
      dadosPost += "&USER_NAME=" + Uri.EscapeUriString(encryptedUserName);
      dadosPost += "&MESSENGER_UNIQUE_DOC_TYPE=" + Uri.EscapeUriString(encryptedUniqueDocType);
      dadosPost += "&MESSENGER_UNIQUE_DOC_VALUE=" + Uri.EscapeUriString(encryptedUniqueDocValue);
      dadosPost += "&MESSENGER_FILTER=" + Uri.EscapeDataString(encryptedMessengerFilters);
      dadosPost += "&START_SERVICE=" + Uri.EscapeUriString(encryptedStartService);

      byte[] dados = Encoding.UTF8.GetBytes(dadosPost);

      var webRequest = WebRequest.Create(url);
      webRequest.Method = "POST";
      webRequest.ContentType = "application/x-www-form-urlencoded";
      webRequest.ContentLength = dados.Length;

      Stream dataStream = webRequest.GetRequestStream();
      dataStream.Write(dados, 0, dados.Length);
      dataStream.Close();

      WebResponse response = webRequest.GetResponse();

      using (dataStream = response.GetResponseStream())
      {
          StreamReader reader = new StreamReader(dataStream);

          string responseFromServer = reader.ReadToEnd();

          if (responseFromServer.Contains(iv))
          {
              string novoIVEncriptado = responseFromServer.Substring(responseFromServer.IndexOf(iv));
              novoIVEncriptado = novoIVEncriptado.Replace(iv, "");
              string retornoEncriptado = responseFromServer.Substring(0, responseFromServer.IndexOf(iv));

              string novoIV = Decrypt(novoIVEncriptado, encryptionKey, iv);

              string retorno = Decrypt(retornoEncriptado, decryptionKey, novoIV);

              response.Close();
              return retorno;
          }
          else
          {
              response.Close();
              return responseFromServer;
          }
      }
  }

C#/.NET

Dica

Para aplicações .NET Framework e .NET, um pacote AnnA.Services está disponível em: https://www.nuget.org/packages/AnnA.Services

  public async Task<ActionResult<string>> Get()
  {
      var decryptionKey = "YOUR_DECRYPTION_KEY";
      var encryptionKey = "YOUR_ENCRYPTION_KEY";
      var CompanyHash = "YOUR_COMPANY_HASH";

      string iv = GenerateIV();

      string action = "GENERATE_USER_HASH"; // GENERATE_USER_HASH || GENERATE_USER_HASH_FORCE_USER || INACTIVATE_USER
      string userId = "USER_ID";
      string username = "USERNAME";
      string startService = "START_SERVICE";

      // Only for MESSENGER actions and GENERATE_USER_HASH_FORCE_USER
      string uniqueDocType = "UNIQUE_DOC_TYPE";
      string uniqueDocValue = "UNIQUE_DOC_VALUE";

      // Only for MESSENGER_ALERT_COUNTER and MESSENGER_REQUESTS actions
      string messengerFilters = new
      {
          DepartmentAlias = "DEPARTMENT_ALIAS",
          ChannelAlias = "CHANNEL_ALIAS",
          DataIni = "START_DATE", // dd/MM/yyyy
          DataFim = "END_DATE", // dd/MM/yyyy
          Status = "STATUS", // A | E
          Pendentes = "PENDENTES" // S | N
      }

      string encryptedAction = Encrypt(action, encryptionKey, iv);
      string encryptedUserId = Encrypt(userId, encryptionKey, iv);
      string encryptedUserName = Encrypt(username, encryptionKey, iv);
      string encryptedStartService = Encrypt(startService, encryptionKey, iv);
      string encryptedUniqueDocType = Encrypt(uniqueDocType, encryptionKey, iv);
      string encryptedUniqueDocValue = Encrypt(uniqueDocValue, encryptionKey, iv);
      string encryptedMessengerFilters = Encrypt(JsonSerializer.Serialize(messengerFilters), encryptionKey, iv);

      var dadosPost = new Dictionary<string, string>
      {
          { "HASH", CompanyHash },
          { "ANNAEXEC", iv },
          { "ACTION", encryptedAction },
          { "USER_ID", encryptedUserId },
          { "USER_NAME", encryptedUserName },
          { "START_SERVICE", encryptedStartService },
          { "MESSENGER_UNIQUE_DOC_TYPE", encryptedUniqueDocType },
          { "MESSENGER_UNIQUE_DOC_VALUE", encryptedUniqueDocValue },
          { "MESSENGER_FILTER", encryptedMessengerFilters }
      };

      var httpClient = new HttpClient();

      string url = "YOUR_ANNA_URL/aannacorporateuser.aspx";

      var result = await httpClient.PostAsync(url, new FormUrlEncodedContent(dadosPost));
      var content = await result.Content.ReadAsStringAsync();

      if (content.Contains(iv))
      {
          string novoIVEncriptado = content.Substring(content.IndexOf(iv));
          novoIVEncriptado = novoIVEncriptado.Replace(iv, "");
          string retornoEncriptado = content.Substring(0, content.IndexOf(iv));

          string novoIV = Decrypt(novoIVEncriptado, encryptionKey, iv);

          string retorno = Decrypt(retornoEncriptado, decryptionKey, novoIV);

          return Ok(retorno);
      }

      return Ok(content);
  }

Java

public static String encrypt3DES(String data, String key, String iv) {
    byte[] decodedIv = Base64.getDecoder().decode(iv);
    byte[] decodedKey = Base64.getDecoder().decode(key);

    IvParameterSpec ivSpec = new IvParameterSpec(decodedIv);
    SecretKey secretKey = new SecretKeySpec(decodedKey, "DESede");

    try {
        Cipher cipher = Cipher.getInstance("DESede/CBC/PKCS5Padding");
        cipher.init(Cipher.ENCRYPT_MODE, secretKey, ivSpec);

        byte[] plainTextBytes = data.getBytes(StandardCharsets.UTF_8);
        byte[] encryptedBytes = cipher.doFinal(plainTextBytes);

        byte[] base64Bytes = Base64.getEncoder().encode(encryptedBytes);

        return new String(base64Bytes);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

public static String decrypt3DES(String data, String key, String iv) {
    byte[] decodedIv = Base64.getDecoder().decode(iv);
    byte[] decodedKey = Base64.getDecoder().decode(key);

    IvParameterSpec ivSpec = new IvParameterSpec(decodedIv);
    SecretKey secretKey = new SecretKeySpec(decodedKey, "DESede");

    byte[] encryptedBytes = Base64.getDecoder().decode(data);

    try {
        Cipher decipher = Cipher.getInstance("DESede/CBC/PKCS5Padding");
        decipher.init(Cipher.DECRYPT_MODE, secretKey, ivSpec);

        byte[] plainText = decipher.doFinal(encryptedBytes);

        return new String(plainText, StandardCharsets.UTF_8);
    } catch (IllegalBlockSizeException | NoSuchPaddingException | NoSuchAlgorithmException |
             InvalidAlgorithmParameterException | InvalidKeyException | BadPaddingException e) {
        throw new RuntimeException(e);
    }
}

public static String generateInitializationVector() {
    byte[] randomBytes = new byte[8];
    new Random().nextBytes(randomBytes);

    return new String(Base64.getEncoder().encode(randomBytes));
}

public static String sample() {
    String decryptionKey = "DECRYPTION_KEY";
    String encryptionKey = "ENCRYPTION_KEY";
    String companyHash = "COMPANY_HASH";

    String iv = generateInitializationVector();

    String action = "GENERATE_USER_HASH"; // GENERATE_USER_HASH || GENERATE_USER_HASH_FORCE_USER || INACTIVATE_USER
    String userId = "USER_ID";
    String username = "USERNAME";
    String startService = "START_SERVICE";

    // Only for MESSENGER actions and GENERATE_USER_HASH_FORCE_USER
    String uniqueDocType = "UNIQUE_DOC_TYPE";
    String uniqueDocValue = "UNIQUE_DOC_VALUE";

    // Only for MESSENGER_ALERT_COUNTER and MESSENGER_REQUESTS actions
    String messengerFilters = "{";
    messengerFilters+="\"DepartmentAlias\": \"DEPARTMENT_ALIAS\",";
    messengerFilters+="\"ChannelAlias\": \"CHANNEL_ALIAS\",";
    messengerFilters+="\"DataIni\": \"START_DATE\","; // dd/MM/yyyy
    messengerFilters+="\"DataFim\": \"END_DATE\","; // dd/MM/yyyy
    messengerFilters+="\"Status\": \"STATUS\","; // A | E
    messengerFilters+="\"Pendentes\": \"PENDENTES\"";  // S | N
    messengerFilters+="}";

    String encryptedAction = encrypt3DES(action, encryptionKey, iv);
    String encryptedUserId = encrypt3DES(userId, encryptionKey, iv);
    String encryptedUserName = encrypt3DES(username, encryptionKey, iv);
    String encryptedStartService = encrypt3DES(startService, encryptionKey, iv);
    String encryptedUniqueDocType = encrypt3DES(uniqueDocType, encryptionKey, iv);
    String encryptedUniqueDocValue = encrypt3DES(uniqueDocValue, encryptionKey, iv);
    String encryptedMessengerFilters = encrypt3DES(messengerFilters, encryptionKey, iv);

    String postBody = "HASH=" + URLEncoder.encode(companyHash, StandardCharsets.UTF_8);
    postBody += "&ANNAEXEC=" + URLEncoder.encode(iv, StandardCharsets.UTF_8);
    postBody += "&ACTION=" + URLEncoder.encode(encryptedAction, StandardCharsets.UTF_8);
    postBody += "&USER_ID=" + URLEncoder.encode(encryptedUserId, StandardCharsets.UTF_8);
    postBody += "&USER_NAME=" + URLEncoder.encode(encryptedUserName, StandardCharsets.UTF_8);
    postBody += "&START_SERVICE=" + URLEncoder.encode(encryptedStartService, StandardCharsets.UTF_8);
    postBody += "&MESSENGER_UNIQUE_DOC_TYPE=" + URLEncoder.encode(encryptedUniqueDocType, StandardCharsets.UTF_8);
    postBody += "&MESSENGER_UNIQUE_DOC_VALUE=" + URLEncoder.encode(encryptedUniqueDocValue, StandardCharsets.UTF_8);
    postBody += "&MESSENGER_FILTER=" + URLEncoder.encode(encryptedMessengerFilters, StandardCharsets.UTF_8);

    try {
        String environmentUrl = "http://YOUR_ANNA_URL";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(environmentUrl + "/aannacorporateuser.aspx"))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(postBody))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseFromServer = response.body();

        if (responseFromServer.contains(iv)) {
            String newEncryptedIv = responseFromServer.substring(responseFromServer.indexOf(iv));
            newEncryptedIv = newEncryptedIv.replace(iv, "");

            String encryptedResponse = responseFromServer.substring(0, responseFromServer.indexOf(iv));

            String newIv = decrypt3DES(newEncryptedIv, encryptionKey, iv);

            return decrypt3DES(encryptedResponse, decryptionKey, newIv);
        }

        return responseFromServer;

    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

PHP

  $DecKey = "DECKEY";
  $EncKey = "ENCKEY";
  $Hash = "HASH";

  // Generate new IV
  $ivlen = openssl_cipher_iv_length('des-ede3-cbc');
  $IV = base64_encode(openssl_random_pseudo_bytes(8));

  $actionName = "GENERATE_USER_HASH_FORCE_USER";
  $actionNameEncriptado = encrypt3DES($actionName, $EncKey, $IV);

  $userId = "USER_ID";
  $userIdEncriptado = encrypt3DES($userId, $EncKey, $IV);

  $userName = "USER_NAME";
  $userNameEncriptado = encrypt3DES($userName, $EncKey, $IV);

  $dadosPost = array(
                      'HASH' => $Hash,
                      'ANNAEXEC' => $IV,
                      'ACTION' => $actionNameEncriptado,
                      'USER_ID' => $userIdEncriptado,
                      'USER_NAME' => $userNameEncriptado);

  $url = "URL_AMBIENTE/aannacorporateuser.aspx";
  $options = array(
      'http' => array(
          'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
          'method'  => 'POST',
          'content' => http_build_query($dadosPost)
      )
  );
  $context  = stream_context_create($options);
  $result = file_get_contents($url, false, $context);

  if (str_contains($result, $IV)) {
      $novoIVEncriptado = substr($result, strpos($result, $IV));
      $novoIVEncriptado = str_replace($IV, "", $novoIVEncriptado);
      $retornoEncriptado = substr($result, 0, strrpos($result, $IV));

      $novoIV = decrypt3DES($novoIVEncriptado, $EncKey, $IV);

      $retorno = decrypt3DES($retornoEncriptado, $DecKey, $novoIV);

      echo utf8_encode($retorno);
  } else {
      echo utf8_encode($retorno);
  }

GeneXus

Cuidado

Em construção

Python

  import requests
  import json
  from Crypto.Cipher import AES, DES3, DES
  from Crypto.Util.Padding import pad, unpad
  from Crypto.Random import get_random_bytes
  from base64 import b64encode, b64decode

  # Encryption method
  def encrypt(data, enckey, iv):

      enckey = b64decode(enckey)
      iv = b64decode(iv)

      cipher = DES3.new(enckey, DES3.MODE_CBC, iv)
      ct_bytes = cipher.encrypt(
          pad(bytes(data, encoding='utf-8'), DES3.block_size))
      ciphertext = b64encode(ct_bytes).decode('utf-8')

      return ciphertext


  # Decryption method
  def decrypt(data, deckey, iv):
      try:
          deckey = b64decode(deckey)
          iv = b64decode(iv)
          data = b64decode(data)

          cipher = DES3.new(deckey, DES3.MODE_CBC, iv)
          pt = unpad(cipher.decrypt(data), DES3.block_size)

          return pt.decode('utf-8')

      except (ValueError, KeyError):
          return 'Incorrect decryption'


  # Integration variables
  url = 'https://YOUR_ANNA_URL/aannacorporateuser.aspx'
  enckey = 'ENCRYPTION_KEY'
  deckey = 'DECRYPTION_KEY'
  hash = 'COMPANY_HASH'
  action = 'ACTION'
  userId = 'USER_ID'
  userName = 'USER_NAME'
  fluxo = '@FLUXO'

  # Creating an IV
  key = get_random_bytes(8)
  cipher = DES.new(key, DES3.MODE_CBC)
  iv = b64encode(cipher.iv).decode('utf-8')

  # Encrypting data
  actionEncypted = encrypt(action, enckey, iv)
  userIdEncrypted = encrypt(userId, enckey, iv)
  userNameEncrypted = encrypt(userName, enckey, iv)
  fluxoEncrypted = encrypt(fluxo, enckey, iv)

  # Creating the submission structure
  request = {
      'HASH': hash,
      'ANNAEXEC': iv,
      'ACTION': actionEncypted,
      'USER_ID': userIdEncrypted,
      'USER_NAME': userNameEncrypted,
      'START_SERVICE': fluxoEncrypted
  }

  # Making a post for AnnA
  response = requests.post(url, request)

  # Retrieving AnnA's response
  response = response.text

  # Separating the received IV from the AnnA response string
  responseEncrypted = response.split(iv)

  # Decrypting the new IV
  newIV = decrypt(responseEncrypted[1], enckey, iv)

  # Decrypting the content of the reply
  responseDecrypt = decrypt(responseEncrypted[0], deckey, newIV)

  # Log
  print('\n')
  print('  -> Server response:\n', response)
  print('  -> Separating the new IV from the json:\n', responseEncrypted)
  print('  -> New IV: ', newIV)
  print('  -> Decrypted return: ', responseDecrypt)
  print('\n')