Como implementar tokenização de CPF para reduzir risco de 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

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:

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:

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 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.

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 — 50 consultas mensais gratuitas, sem cartão de crédito.