Objetivo

Esta documentação explica alguns conceitos importantes sobre o tema, instrui como solicitar as credenciais e demonstra o fluxo da geração do Certificado Dinâmico para demais produtos, exceto para os produtos PIX Indireto, PISP, Corban Digital, Extrato (Account Statement) e FX as a Service - Câmbio.

O Certificate Sign Request é um certificado não assinado e usado apenas no ambiente de produção, gerado pelo responsável técnico que contém os dados da empresa requisitante e sua chave pública.

Esse procedimento é realizado para que ao solicitar um certificado ao Itaú o solicitante identifique sua aplicação e receba um certificado de uso único e exclusivo.

O CSR (Certificate Sign Request) é o arquivo que contém a chave pública do certificado e as demais informações de identificação. Utilizado para requisitar ao STS Itaú a assinatura do certificado.

Seu formato segue o seguinte padrão:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

A segurança do processo é baseada no conceito de chave assimétrica ou chave pública

Chave pública

A chave pública é um valor gerado a partir de operações matemáticas com a chave privada. Como seu nome já sugere, seu conhecimento pode ser público e não é necessário ser armazenada de forma confidencial. Seu valor fica embutido dentro do próprio certificado.

Chave privada

Seu formato segue o seguinte padrão:

SSL

O SSL (Secure Socket Layer) na requisição, oferece total segurança entre aplicativos cliente/servidor, preservando a integridade e a veracidade do conteúdo trafegado na rede, por meio da autenticação das partes envolvidas com a troca destas informações. A versão recomendada pelo banco é a 1.1.1.c ou superior.

Credenciais

As credenciais é o conjunto client_id + client_secret.

Token temporário

O token é um valor obtido através do STS Itaú que representa a autenticação da credencial. Ele é obrigatório para consumo das APIs disponibilizadas pelo Itaú, assim como o certificado.

Como faço para obter um token temporário?

Para obter um token temporário do Itaú o procedimento varia conforme a etapa da jornada em que você está: onboarding ou consumo.

• Etapa de onboarding- Esta etapa é quando você está iniciando seu contato com o Itaú , você receberá um token temporário por e-mail com validade de 7 dias corridos com o único objetivo de emitir suas credenciais e o certificado, após este período esse token será invalidado. É fundamental seguir o procedimento de recebimento das credenciais de acesso e emissão do certificado dentro desse prazo a contar da data de emissão do token.

• Etapa de Consumo- Esta etapa é quando você já tem em mãos suas credenciais e o certificado devidamente emitidos pelo STS Itaú. O processo de emissão do token é bem simples e pode ser realizado por meio de requisição ao STS Itaú.

Figura 01. A imagem acima demonstra todo o fluxo da Solicitação de credenciais para Cobranças e uso externo, exceto para os produtos PIX Indireto, PISP, Corban Digital, Extrato (Account Statement) e FX as a Service - Câmbio.

Novos usuários: gerar pela primeira vez as credenciais e o certificado dinâmico

Se você é um novo usuário, e vai gerar seu certificado dinâmico pela primeira vez, primeiramente, você deve observar os pré-requisitos, depois o passo a passo para gerar as credenciais e, por último, prosseguir com o passo a passo para gerar o certificado dinâmico.

Mas se você já é um usuário e quer renovar seu certificado, acesso o tópico renovar o certificado dinâmico.

Para gerar o certificado dinâmico, os pré-requisitos abaixo devem ser observados:

Credenciais – Tenha o (client_id, token temporário e a chave de seção), você receberá essas informações via e-mail por meio do seu ponto focal do Itaú.

OpenSSL - Tenha o OpenSSL na versão 1.1.1 recomendada pelo banco instalado em sua máquina, pois será a ferramenta utilizada neste tutorial para gerar o arquivo CSR e validar se tudo ocorreu como o esperado.

Par de chaves – Tenha as chaves pública e privada, geradas por meio da ferramenta OpenSSL.

IDE – Tenha o JAVA ou uma IDE de sua preferência pois será necessário para executar o arquivo .java, o qual será utilizado no processo de descriptografia das credenciais.

Passo a passo para gerar as credenciais

Passo 1 – Instalar em sua máquina a ferramenta OpenSSL na versão 1.1.1 recomendada pelo banco;

Passo 2 – Gerar o par de chaves (pública e privada);

2.1 - Criar uma pasta específica no diretório na própria máquina para salvar o par de chaves;

2.2 - Abrir essa mesma pasta via terminal e executar primeiro este comando para conferir se está na versão 1.1.1, recomendada pelo banco:

Figura 02: A imagem acima demostra a execução do comando openSSL version no Git Bash para conferir a versão do openSSL instalada.

Passo 3 - Após conferir a versão, agora execute estes comandos no terminal para gerar o par de chaves (private.pem e public.pem) na pasta do diretório;

Figura 03: A imagem acima demostra a execução dos comandos openssl genpkey -out private.pem -algorithm RSA -pkeyopt rsa_keygen_bits:2048 e openssl rsa -in private.pem -pubout -out public.pem no Git Bash para gerar o par de chaves na pasta do diretório.

Passo 4 - Confira se o par de chaves foi gerado corretamente na pasta criada no diretório.

Passo 5– Envie a chave pública ao Officercash , ou seja, seu ponto focal do Itaú que solicitará ao time de Backoffice suas credenciais criptografadas.

O time de Backoffice lhe enviará por e-mail as credenciais criptogradas, contendo o Client ID, Token temporário e a Chave de Sessão.

Observe as informações a seguir, o e-mail deve chegar da seguinte forma:

Assunto do e-mail: Credenciais Itaú

O remetente padrão de nossos e-mails é: itau@itau.com.br, para sua própria segurança não aceite e-mails que não sejam deste remetente. Exceto em casos em que haja um alinhamento prévio com o seu representante Itaú sobre o envio dos dados.

Exemplo de e-mail:

Passo 6 – Descriptografar as credenciais

Existe duas opções para descriptografar as credenciais recebidas por e-mail mencionado no passo anterior, escolha uma delas para realizar este passo.

import java.io.BufferedReader;
import java.io.FileInputStream;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.interfaces.RSAPrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import java.util.Scanner;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.SecretKey;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

public class Criptografia {

    private static String extrairChaveRsaPem(String tipoChave, String arquivoChavesRsa) {

        try {
            InputStream is = new FileInputStream(arquivoChavesRsa);
            @SuppressWarnings("resource")
            BufferedReader br = new BufferedReader(new InputStreamReader(is));
            StringBuilder sb = new StringBuilder();
            boolean inKey = false;
            for (String line = br.readLine(); line != null; line = br.readLine()) {
                if (!inKey) {
                    if (line.startsWith("-----BEGIN ") && line.endsWith(" " + tipoChave + " KEY-----")) {
                        inKey = true;
                    }
                } else {
                    if (line.startsWith("-----END ") && line.endsWith(" " + tipoChave + " KEY-----")) {
                        inKey = false;
                        break;
                    }
                    sb.append(line);
                }
            }
            return sb.toString();
        } catch (Exception e) {
            e.printStackTrace();
        }

        return null;
    }

    public static String decriptografiaAes(SecretKey key, String cipherText) {

        try {
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            IvParameterSpec iv = new IvParameterSpec(new byte[16]);
            cipher.init(Cipher.DECRYPT_MODE, key, iv);
            byte[] plainText = cipher.doFinal(Base64.getDecoder().decode(cipherText));

            return new String(plainText);
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (BadPaddingException e) {
            e.printStackTrace();
        } catch (IllegalBlockSizeException e) {
            e.printStackTrace();
        } catch (InvalidKeyException e) {
            e.printStackTrace();
        } catch (InvalidAlgorithmParameterException e) {
            e.printStackTrace();
        } catch (NoSuchPaddingException e) {
            e.printStackTrace();
        }

        return null;
    }

    private static byte[] decriptografiaRsa(String caminhoChavePrivada, String dadosCifrados) {

        try {
            String chavePrivada = extrairChaveRsaPem("PRIVATE", caminhoChavePrivada);

            PKCS8EncodedKeySpec spec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(chavePrivada.toString()));
            KeyFactory kf = KeyFactory.getInstance("RSA");
            RSAPrivateKey privateKey = (RSAPrivateKey) kf.generatePrivate(spec);

            Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
            cipher.init(Cipher.DECRYPT_MODE, privateKey);

            return cipher.doFinal(Base64.getDecoder().decode(dadosCifrados));

        } catch (Exception e) {
            e.printStackTrace();
        }

        return null;
    }

    public static void main(String[] args) {
        SecretKey chaveSessao = null;
        Scanner scanner = new Scanner(System.in);

        try {
            System.out.println("\n=========================================");
            System.out.println("Coloque as informacoes recebidas no e-mail");
            System.out.println("=========================================");

            System.out.println("\nClientId: ");
            System.out.flush();
            String clientIdCifrado = scanner.nextLine().trim().replace("\n", "").replace("\r", "").replace(" ", "");

            System.out.println("\nToken Temporario: ");
            System.out.flush();
            String tokenCifrado = scanner.nextLine().trim().replace("\n", "").replace("\r", "").replace(" ", "");

            System.out.println("\nChave Sessao: ");
            System.out.flush();
            String chaveSessaoCifrada = scanner.nextLine().trim().replace("\n", "").replace("\r", "").replace(" ", "");

            System.out.println("\nCaminho chave privada (Nao use espacos/Caracteres especiais): ");
            System.out.flush();
            String caminhoChavePrivada = scanner.nextLine().trim().replace("\n", "").replace("\r", "").replace(" ", "");

            System.out.flush();
            scanner.close();

            System.out.println("\n=====================================");
            System.out.println("    Processo de Decriptografia         ");
            System.out.println("=====================================");

            // Decifra a chave de sessao AES com a chave RSA privada
            byte[] chaveSessaoDecifrada = decriptografiaRsa(caminhoChavePrivada, chaveSessaoCifrada);
            chaveSessao = new SecretKeySpec(chaveSessaoDecifrada, 0, chaveSessaoDecifrada.length, "AES");
            // Decriptografa a credencial atraves da chave de sessao AES
            String clientIdDecifrada = decriptografiaAes(chaveSessao, clientIdCifrado);
            System.out.println(
                    "\nClient id decifrado com a chave de sessao AES:\n[ " + new String(clientIdDecifrada) + " ]");
            String tokenDecifrado = decriptografiaAes(chaveSessao, tokenCifrado);
            System.out.println("\nToken decifrado com a chave de sessao AES:\n[ " + new String(tokenDecifrado) + " ]");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Ao executar a aplicação com os valores informados, as credenciais serão exibidas no terminal.

Observe abaixo o modelo de e-mail que você receberá após decifrar suas credenciais:

Credenciais decifradas

Processo de Decriptografia
Client id decifrada com a chave de sessao AES:

e26f2f89-xxxxx-4ca6-8bc3-xxxxxxxxxxxxcc7

Token decifrado com a chave de sessao AES:

eyJraWQiOiJhZTYxYWIxZi0yNTRhLTQ5ZWQtODMzNC05ZDJlN2E0MzZiNGQuaG9tLmdlbi4xNTk3NjAwMzM2OTkyLmp3dCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJlxxxxxxxxxxFkLTRjYTYtOGJjMy1kZDQ0YjRhYjNjYxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxE2MTg5NDIyMTIsImlhdCI6MTYxODUxMDIxMiwiZmxvdyI6IkNDIn0.ZEIGYAUu-8-aCirhuClcp4F4qpL9L0KFh0pQJggXieUSCEasX-3I5QLvp5BkKcE2RhwvRfW2dUuiXJGaDqK_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-fpTkve_8SBnnJb4L_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-F-1ygx5yTSl_DMCGn4uCYmH5IfkZa9jC9A2-t4jlIlvFZHeGVl_c2-xaWFBd_9ryQ

3. Copie o client_id decifrada com a chave de sessao AES e o token decifrado com a chave de sessão AES que foram gerados e salve em local seguro pois você irá utilizá-los para gerar seu certificado dinâmico.

• Segunda opção: Tenha o JRE ou tenha o java 8 ou superior em sua máquina:

1. Crie um arquivo .java e o nomeie obrigatoriamente "Criptografia.java";

2. No mesmo diretório onde foi criado o arquivo .java, compile o código através do comando:

3. E, então o execute com:

4. Preencha os dados que serão solicitados conforme o que foi recebido via e-mail:

• ClientId: < ClientId presente no e-mail>
• Token temporário: <Token temporário presente no e-mail>
• Chave sessão: <Chave sessão presente no e-mail>
• Caminho chave privada: Copie o caminho do diretório que foi criado onde contém a chave privada. Exemplo: C:/Users/Cliente/Certificado/private.pem

Ao executar a aplicação com os valores informados, as credenciais serão exibidas no terminal.

Observe abaixo o modelo de e-mail que você receberá após decifrar suas credenciais:

5. Copie o client_id decifrada com a chave de sessao AES e o token decifrado com a chave de sessão AES que foram gerados e salve em local seguro pois você irá utilizá-los para gerar seu certificado dinâmico.

Ao final dos passos mencionados até aqui, você já deve estar com as suas credenciais decifradas para iniciar o processo de geração do Certificado Dinâmico.

Para gerar o Certificado Dinâmico o client_id e o token temporário que deverão ser preenchidos neste passo, são as credenciais que foram decifradas no passo anterior.

1 - Escolha o seu sistema operacional (Windows ou Linux e macOS) e execute no OpenSSL os comandos correspondentes conforme o sistema escolhido;

2 - Após escolher seu sistema operacional, insira o client_id e o token temporário decifrados nos campos correspondentes;

3 - Troque o valor dos parâmetros de acordo com as instruções da tabela explicativa, não esqueça de remover as chaves {{ }} e não utilizar caracteres especiais.

Confira abaixo os comandos referente ao sistema operacional:

Windows

• Copie o comando abaixo, insira suas credenciais decifradas e o execute em seu terminal.

Exemplo de como deve ficar o comando a ser executado:

O comando foi executado com sucesso, caso a saída abaixo seja exibida:

Linux e macOS

• Copie o comando abaixo, insira suas credenciais decifradas e o execute em seu terminal.

O comando foi executado com sucesso, caso a saída abaixo seja exibida:

Observe a tabela explicando cada campo a ser preenchido mencionado no item anterior:

Tabela explicativa

Validar o certificado dinâmico (opcional)

Para validar, você pode utilizar uma ferramenta conforme sua preferência.

Ou, executar o comando abaixo no OpenSSL;

openssl req -in ARQUIVO_REQUEST_CERTIFICADO.csr -noout -text

Se tudo ocorreu como o esperado, em nosso exemplo a saída seria similar a esta:

Passo 8 - enviar o certificado dinâmico

Header - O access_token_tmp é o token temporário decifrado, após o processo de descriptografia.

Request Body - O conteudo_arquivo_csr é o conteúdo do ARQUIVO_REQUEST_CERTIFICADO.csr.

Response Body- Você receberá do STS o client_secret e o certificado emitido pelo Itaú no formato .crt, isso significa que o retorno da chamada foi realizado com sucesso.

Observe um exemplo da chamada realizada com sucesso:

Figura 5 – A imagem acima demonstra o statusCode=200 que significa sucesso da chamada e no body do Response trará na primeira linha o client-secret e nas demais linhas será o certificado emitido pelo Itaú no formato .crt.

Observe um exemplo da chamada realizada com erro:

Figura 6 – A imagem acima demonstra que o envio do certificado CSR apresenta o erro C800, a mensagem informa que o CSR é inválido e como ação é solicitado que o envio seja verificado.

Confira na prática como enviar o certificado dinâmico (CSR) e como receber o secret assinado juntamente com o certificado assinado pelo Itaú:

Vídeo 01 - O vídeo acima demonstra os passos na prática de como enviar o certificado dinâmico (CSR) e como receber o secret assinado juntamente com o certificado assinado pelo Itaú.

Exemplos de envio do certificado dinâmico

Confira aqui exemplos de como enviar o certificado dinâmico via Postman e também em outras linguagens de programação:

Geração e ativação do certificado dinâmico via Postman

O Postman é uma aplicação que permite realizar requisições HTTP a partir de uma interface simples, didática e intuitiva, com o objetivo de facilitar o teste e a depuração de serviços RESTful (Web APIs), por meio do envio destas requisições bem como a análise do seu retorno.

Com isso, é possível consumir facilmente serviços locais e na rede, enviar dados e efetuar testes sobre as respostas das requisições. Além disso, o Postman permite aos desenvolvedores analisar o funcionamento de serviços externos, a fim de saber como consumi-los.

E, pensando sempre em sua melhor experiência conosco, o portal Itaú for developers_ disponibiliza uma collection para lhe auxiliar na configuração do ambiente de testes via Postman.

Portanto, o primeiro passo para gerar e ativar o certificado dinâmico via Postman, é realizar o download da nossa Collection.

Após a habilitação do Postman, o mesmo valida se está sendo enviado algum tipo de certificado SSL (Secure Socket Layer).

Figura 7 - A imagem acima demonstra os parâmetros gerais do Postman, o qual valida se está sendo enviado algum tipo de certificado SSL na requisição.

Como enviar o certificado dinâmico via Postman

Para importar via Postman o ARQUIVO_CERTIFICADO.crs e o ARQUIVO_CHAVE_PRIVADA.key após a geração, siga os passos abaixo:

1. Abra o Postman e clique no ícone da engrenagem, localizada no canto superior direito da página;
2. Acionar a opção Settings;
3. Em seguida, clique na aba Certificates;
4. Clicar na opção Add Certificate;
5. Preencher os campos conforme as informações abaixo:

• Host: api.itau.com.br;
• CRT file: selecione o arquivo_certificado.crt;
• KEY file: selecione o arquivo_chave_privada.key;

6. Clicar em Add para adicionar o arquivo.

Figura 8 - A imagem acima demonstra os 6 passos a serem seguidos para enviar o certificado via Postman.

Confira na prática como enviar o certificado dinâmico (CSR) via Postman:

Vídeo 02 - O vídeo acima demonstra os passos na prática de como enviar o certificado dinâmico (CSR) via Postman.

Outras linguagens de programação

Agora, confira o envio do certificado dinâmico em outras linguagens de programação:

Confira na prática como enviar o certificado dinâmico (CSR) via cURL:

Vídeo 03 - O vídeo acima demonstra os passos na prática de como enviar o certificado dinâmico (CSR) via cURL.

Parabéns! Você já tem em mãos o client_secret e seu Certificado Dinâmico emitido pelo Itaú, agora você já pode começar a consumir nossas APIs.

Renovar o certificado dinâmico

Existem duas formas para renovar o certificado dinâmico:

Nos tópicos a seguir, exploraremos ambas as opções e os processos envolvidos em cada uma delas.

1 - Renovar um certificado ainda válido dentro do prazo de validade

Se você já é um usuário, porém, quer renovar seu certificado dinâmico mesmo tendo um certificado ainda válido, ou seja, sem ter expirado o prazo de 365 dias do seu arquivo .CRT, basta seguir as instruções a seguir:

1. Não é necessário gerar novas credenciais (client_ID e client_secret), recomendamos que utilize suas credenciais descriptografadas já existentes geradas anteriormente, caso não as tenha em mãos, solicite ao seu ponto focal do Itaú;

2. Solicite um novo access_token por meio de requisição ao STS Itaú, cuja validade é de 5 minutos, caso expire solicite novamente;

3. Gerar o novo certificado dinâmico (.CRT): com as credenciais descriptografadas e o access_token em mãos, siga o Passo 7 – passo a passo para gerar o certificado dinâmico.

4. Com o arquivo (.CSR) e o token STS gerado (conforme mencionado no tópico 2), você poderá concluir o processo de geração do certificado dinâmico utililizando a rota de renovação /seguranca/v2/certificado/renovacao. O response trará o certificado emitido pelo Itaú no formato .crt. Esta API de renovação pode ser utilizada se o seu certificado for válido por 30 dias ou menos, caso contrário, um erro será retornado, indicando que ainda não está no prazo de renovação. Se o certificado já estiver expirado, siga o procedimento descrito na seção 2 - Renovar um certificado expirado após o prazo de validade.

Curl exemplo:

2 - Renovar um certificado expirado após o prazo de validade

Se você já é um usuário, porém, detém um certificado dinâmico expirado, ou seja, decorreu o prazo de validade de 365 dias do seu arquivo .CRT, é necessário gerar um novo certificado dinâmico, basta seguir as instruções abaixo:

1. Não é necessário gerar novas credenciais (client_ID e client_secret), recomendamos que utilize suas credenciais descriptografadas já existentes geradas anteriormente, caso não as tenha em mãos, solicite ao seu ponto focal do Itaú;

2. Solicite um novo token temporário ao seu ponto focal do Itaú que lhe enviará por e-mail um token criptografado, cuja validade é de 7 dias corridos. Caso expire, solicite novamente;

3. Copie o token temporário que você recebeu por e-mail do seu ponto focal e realize o processo do Passo 6 – Descriptografar as credenciais (role a documentação para baixo) para descriptografa-lo;

4. Agora, basta gerar um novo certificado dinâmico (.CRT): com as credenciais descriptografadas e o token temporário em mãos, siga a partir do Passo 7 – passo a passo para gerar o certificado dinâmico.

Códigos de retorno da chamada do envio do certificado