# Como implementar tokenização de CPF para reduzir risco de vazamento > Aprenda a implementar tokenização de CPF para substituir dados sensíveis por tokens seguros, reduzindo drasticamente o risco de vazamento. **Publicado:** 26/07/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/implementar-tokenizacao-cpf-reduzir-vazamento --- A tokenização substitui o CPF por um identificador aleatório — o token — armazenado em um cofre isolado sem relação matemática com o dado original. Se o banco de dados principal for comprometido, os tokens capturados são inúteis sem acesso ao cofre. Essa abordagem reduz o escopo de auditoria da LGPD e simplifica o cumprimento do direito de exclusão: revogar um token efetivamente apaga o CPF de todo o sistema. ## Introdução A tokenização é uma técnica de segurança que substitui dados sensíveis — como o CPF — por um identificador aleatório chamado token, que não possui relação matemática com o dado original. Diferente da criptografia, onde o dado original pode ser recuperado com uma chave, a tokenização armazena o mapeamento em um cofre seguro isolado, reduzindo drasticamente a superfície de ataque. --- ## Tokenização vs. criptografia vs. mascaramento Antes de implementar, é importante entender as diferenças entre as três técnicas: ### Criptografia - Transforma o dado original usando um algoritmo matemático e uma chave. - O dado pode ser recuperado por qualquer pessoa que possua a chave. - Se a chave for comprometida, todos os dados ficam expostos. ### Mascaramento - Oculta partes do dado original (ex: ***.456.***-01). - É irreversível — o dado original não pode ser recuperado a partir da versão mascarada. - Útil para exibição, mas insuficiente para armazenamento seguro quando o dado precisa ser recuperado. ### Tokenização - Substitui o dado original por um token aleatório sem relação matemática. - O mapeamento token-dado é armazenado em um cofre seguro isolado. - Mesmo que o banco de dados principal seja comprometido, os tokens são inúteis sem acesso ao cofre. --- ## Arquitetura do sistema de tokenização O sistema é composto por três componentes: 1. **Aplicação principal**: utiliza tokens no lugar de CPFs reais em todas as operações. 2. **Serviço de tokenização**: responsável por gerar tokens e fazer o mapeamento. 3. **Cofre de tokens**: banco de dados isolado e altamente seguro que armazena o mapeamento token-CPF. --- ## Implementação do serviço de tokenização ```python import uuid import hashlib import json import sqlite3 from datetime import datetime, timezone from typing import Optional class CofreTokensCPF: """Cofre seguro para armazenamento de mapeamento token-CPF.""" def __init__(self, db_path: str = "cofre_tokens.db"): self.conn = sqlite3.connect(db_path) self._criar_tabela() def _criar_tabela(self): self.conn.execute(""" CREATE TABLE IF NOT EXISTS tokens ( token TEXT PRIMARY KEY, cpf_cifrado TEXT NOT NULL, criado_em TEXT NOT NULL, expira_em TEXT, criado_por TEXT NOT NULL, finalidade TEXT NOT NULL, ativo INTEGER DEFAULT 1 ) """) self.conn.execute(""" CREATE INDEX IF NOT EXISTS idx_cpf_cifrado ON tokens(cpf_cifrado) """) self.conn.commit() def tokenizar(self, cpf: str, usuario: str, finalidade: str) -> str: """Gera um token para o CPF informado.""" # Verificar se já existe token ativo para este CPF cpf_hash = hashlib.sha256(cpf.encode()).hexdigest() cursor = self.conn.execute( "SELECT token FROM tokens WHERE cpf_cifrado = ? AND ativo = 1", (cpf_hash,) ) existente = cursor.fetchone() if existente: return existente[0] # Gerar novo token token = f"tok_{uuid.uuid4().hex}" self.conn.execute( "INSERT INTO tokens (token, cpf_cifrado, criado_em, criado_por, finalidade) VALUES (?, ?, ?, ?, ?)", (token, cpf_hash, datetime.now(timezone.utc).isoformat(), usuario, finalidade) ) self.conn.commit() # Registrar auditoria self._registrar_auditoria("tokenizar", token, usuario) return token def destokenizar(self, token: str, usuario: str) -> Optional[str]: """Recupera o CPF original a partir do token (requer autorização).""" cursor = self.conn.execute( "SELECT cpf_cifrado FROM tokens WHERE token = ? AND ativo = 1", (token,) ) resultado = cursor.fetchone() if resultado: self._registrar_auditoria("destokenizar", token, usuario) # Em produção, aqui seria feita a descriptografia real return resultado[0] return None def revogar(self, token: str, usuario: str): """Revoga um token, tornando-o inválido.""" self.conn.execute( "UPDATE tokens SET ativo = 0 WHERE token = ?", (token,) ) self.conn.commit() self._registrar_auditoria("revogar", token, usuario) def _registrar_auditoria(self, acao: str, token: str, usuario: str): """Registra operações no cofre para auditoria.""" log = { "timestamp": datetime.now(timezone.utc).isoformat(), "acao": acao, "token": token[:10] + "...", "usuario": usuario } with open("cofre_audit.log", "a") as f: f.write(json.dumps(log) + "\n") # Exemplo de uso cofre = CofreTokensCPF() # Tokenizar um CPF token = cofre.tokenizar( cpf="12345678901", usuario="sistema_onboarding", finalidade="verificacao_cadastral" ) print(f"Token gerado: {token}") # Destokenizar quando necessário cpf_hash = cofre.destokenizar(token, usuario="sistema_pagamento") print(f"CPF hash recuperado: {cpf_hash}") ``` --- ## Integração com a API do CPFHub.io Ao consultar a API, tokenize o CPF imediatamente após receber a resposta: ```python import requests def consultar_e_tokenizar(cpf: str, api_key: str, cofre: CofreTokensCPF) -> dict: """Consulta CPF na API e retorna dados com CPF tokenizado.""" try: response = requests.get( f"https://api.cpfhub.io/cpf/{cpf}", headers={ "x-api-key": api_key, "Accept": "application/json" }, timeout=30 ) if response.status_code == 200: dados = response.json()["data"] # Tokenizar o CPF antes de armazenar token = cofre.tokenizar( cpf=dados["cpf"], usuario="api_gateway", finalidade="consulta_cadastral" ) # Retornar dados com token no lugar do CPF dados_tokenizados = { "cpf_token": token, "name": dados.get("name"), "gender": dados.get("gender"), "birthDate": dados.get("birthDate") } return dados_tokenizados except requests.exceptions.Timeout: print("[ERROR] Timeout ao consultar API") return {} # Teste via cURL # curl -X GET "https://api.cpfhub.io/cpf/12345678901" \ # -H "x-api-key: SUA_API_KEY" \ # -H "Accept: application/json" \ # --max-time 30 ``` Consulta direta via cURL para validação: ```bash curl -X GET "https://api.cpfhub.io/cpf/12345678901" \ -H "x-api-key: SUA_API_KEY" \ -H "Accept: application/json" \ --max-time 30 ``` --- ## Fluxo completo de tokenização 1. **Coleta**: o CPF é recebido via formulário ou API. 2. **Validação**: o CPF é validado consultando a API do CPFHub.io. 3. **Tokenização**: o CPF real é substituído por um token. 4. **Armazenamento**: apenas o token é salvo no banco de dados principal. 5. **Uso**: todas as operações internas utilizam o token. 6. **Destokenização**: quando necessário (ex: enviar para a Receita Federal), o CPF real é recuperado do cofre, com registro de auditoria. 7. **Revogação**: quando o titular solicita exclusão, o token é revogado. --- ## Segurança do cofre de tokens O cofre de tokens é o componente mais crítico do sistema. Proteja-o com: - **Isolamento de rede**: o cofre deve estar em uma rede separada, acessível apenas pelo serviço de tokenização. - **Autenticação mútua (mTLS)**: toda comunicação com o cofre deve usar certificados de cliente. - **Criptografia em repouso**: os dados no cofre devem ser criptografados com chaves gerenciadas por um HSM. - **Backup seguro**: backups do cofre devem seguir as mesmas políticas de segurança. - **Acesso restrito**: apenas um número limitado de serviços e pessoas deve ter acesso ao cofre. - **Monitoramento contínuo**: registre e monitore toda operação realizada no cofre. --- ## Benefícios da tokenização para conformidade - **Redução de escopo PCI DSS e LGPD**: sistemas que utilizam apenas tokens não precisam das mesmas proteções exigidas para dados reais de CPF. - **Minimização de impacto em vazamentos**: mesmo que o banco principal seja comprometido, os tokens são inúteis sem o cofre. - **Facilitação do direito de exclusão**: revogar um token efetivamente "exclui" o CPF de todo o sistema. - **Auditoria simplificada**: toda operação de destokenização é registrada, facilitando a rastreabilidade. --- ## Perguntas frequentes ### Tokenização de CPF é exigida pela LGPD? A [LGPD](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2018/lei/l13709.htm) não exige tokenização especificamente, mas determina que dados pessoais sejam protegidos com medidas técnicas adequadas. A tokenização é uma das técnicas mais reconhecidas para cumprir os princípios de segurança e minimização de dados — e simplifica a resposta ao direito de exclusão: basta revogar o token. ### Qual a diferença prática entre tokenizar e criptografar um CPF? Na criptografia, quem tem a chave consegue recuperar o CPF de qualquer banco que armazene o dado cifrado. Na tokenização, o CPF real fica isolado em um cofre separado — mesmo que o banco principal seja comprometido, o atacante só obtém tokens sem utilidade. A tokenização reduz a superfície de ataque de forma estrutural. ### O sistema de tokenização impacta a latência das consultas à API? A chamada à API do CPFHub.io retorna em ~900ms. A tokenização ocorre localmente após a resposta, adicionando apenas alguns milissegundos ao processo — imperceptível para o usuário final. O cofre de tokens pode ser consultado em cache para operações que não exigem CPF real. ### A API CPFHub.io funciona para todos os volumes de consulta? Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. ### Leia também - [Vazamento de CPF: responsabilidades da empresa e como prevenir](https://cpfhub.io/blog/vazamento-de-cpf-responsabilidades-da-empresa-e-como-prevenir) - [LGPD: CPF é dado pessoal sensível ou não? Entenda a classificação correta](https://cpfhub.io/blog/lgpd-cpf-e-dado-pessoal-sensivel-ou-nao-entenda-a-classificacao-correta) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) - [APIs de CPF podem ser usadas no setor imobiliário?](https://cpfhub.io/blog/apis-cpf-setor-imobiliario) --- ## Conclusão A tokenização de CPF é uma das medidas mais eficazes para reduzir o risco de vazamento de dados pessoais. Ao substituir o CPF real por tokens sem valor intrínseco, você limita o impacto de uma eventual brecha de segurança. Combinada com criptografia no cofre, controle de acesso rigoroso e logs de auditoria, a tokenização fortalece a postura de segurança da sua empresa e simplifica a conformidade com a LGPD. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito.