Mudaram cinco coisas para quem desenvolve com o Cartão de Cidadão v2. As chaves passaram de RSA para ECDSA. [...]
Para operações em modo de contacto, actualizar o middleware é em geral suficiente, sem alteração significativa de integração. O contactless, esse, exige métodos novos do SDK. Tudo o que verifique assinaturas ou use os métodos criptográficos do SDK precisa de atenção por causa do ECDSA, e é aí que a maioria de quem desenvolve para o Cartão de Cidadão v2 perde tempo.
O novo Cartão de Cidadão é emitido desde junho de 2024, redesenhado para as normas de segurança e formato do Regulamento (UE) 2019/1157, que estava em aplicação desde 2 de agosto de 2021 e foi substituído pelo Regulamento (UE) 2025/1208 a 9 de julho de 2025. Os cartões antigos que continuam válidos mantêm-se a funcionar, por isso o seu código tem de lidar com ambos indefinidamente em vez de migrar de um para o outro.
Cartão de Cidadão v2 para quem desenvolve: o que mudou em relação ao v1?
Porque é que o ECDSA quebra código que parecia agnóstico ao algoritmo?
Porque muito código não é tão agnóstico como se lê. Aparece em quatro sítios: um identificador de algoritmo escrito no código numa rotina de verificação de assinatura, redigido quando o RSA era a única opção; uma biblioteca de validação configurada com uma lista de algoritmos permitidos que ninguém revisitou; pressupostos de tamanho de chave em tratamento de buffers ou em definições de colunas de base de dados; e fixtures de teste que contêm apenas material assinado com RSA.
O quarto custa mais tempo, porque produz um build verde e um sistema a falhar. Se os seus dados de teste foram capturados antes de meados de 2024, não contêm nenhum cartão ECDSA.
O que é o CAN, e o que está o PACE a fazer?
Duas coisas diferentes, frequentemente confundidas. O Card Access Number é um código de seis dígitos impresso no canto inferior direito do novo cartão, e existe para prevenir leitura contactless não autorizada. Não é um PIN. É distinto dos PIN de autenticação, assinatura e morada, e não é secreto da mesma maneira: qualquer pessoa que segure o cartão consegue lê-lo. Prova posse física, não consentimento. Um detalhe de implementação: ao invocar C_Login através de PKCS#11 em modo contactless com um cartão v2, o CAN é passado como parâmetro de PIN, o que nada no nome do parâmetro sugere.
O PACE é o protocolo de autenticação que protege o uso contactless, descrito na parte 11 do Documento 9303 da ICAO. O controlo de acesso aos dados no chip contactless é feito através de PACE usando dados lidos da Zona de Leitura Automática do documento, ou opcionalmente, no caso dos cartões, através do CAN. A segurança é adicionalmente garantida por autenticação passiva dos datagrupos, e por autenticação do chip através de mecanismos de Active Authentication e Chip Authentication.
Um detalhe de experiência de utilizador que vale desenhar. A aplicação de desktop pede o CAN na primeira utilização contactless e não volta a pedir nas utilizações seguintes com o mesmo cartão, com opção de não o guardar. Se construir o seu próprio fluxo, decida deliberadamente se guarda o CAN em cache, porque o argumento da conveniência e o da segurança apontam em direcções opostas e a decisão pertence ao responsável de produto e não a quem escreve a caixa de diálogo.
O que muda na cadeia de certificação?
Esta é a alteração com maior probabilidade de chegar a produção sem ser detectada, porque depende da interface que o seu código usa. A construção da cadeia passa a ser responsabilidade sua em vez de algo que o módulo lhe entrega. Código que assumia que uma cadeia completa vem do token vai falhar a validação no v2 enquanto continua a funcionar no v1, que é exactamente o padrão que é diagnosticado como cartão avariado.
E se buscar as intermédias em tempo de execução através de AIA, introduziu uma dependência de rede num caminho de verificação. Decida se isso é aceitável, e se não for, pré-carregue e guarde em cache com um plano de actualização. A documentação da aplicação de desktop inclui uma secção de resolução de problemas com a nova cadeia de confiança, que é um sinal razoável de que isto não é uma preocupação teórica.
Qual é a lista de migração mais curta para o Cartão de Cidadão v2?
Existe um modo de testes, e importa mais do que parece. A documentação do SDK refere a configuração de um, junto à secção de acesso contactless. Os códigos PIN bloqueiam ao fim de três tentativas erradas, o desbloqueio exige uma ida presencial com a carta de PIN, e há developers a testar fluxos de assinatura contra cartões reais que os bloquearam. Encontre essa secção antes do seu primeiro teste de assinatura, não depois.
O sexto item é o único desenvolvimento genuinamente novo. Os primeiros cinco são uma manhã a ler o seu próprio código seguida de corrigir o que encontrar, e são o que separa uma integração que funciona em ambos os cartões de uma que funciona nos cartões que o seu developer por acaso tem. Se está a começar de zero em vez de migrar, o nosso guia sobre integrar o Cartão de Cidadão em aplicações privadas cobre o terreno anterior a este.
Leitura relacionada
Perguntas frequentes
Cartão de Cidadão v2 para quem desenvolve: o que mudou
O que mudou entre o Cartão de Cidadão v1 e v2?
Código escrito para o Cartão de Cidadão antigo continua a funcionar?
CAN e detecção de versão
O que é o CAN no Cartão de Cidadão?
Como se sabe se um cartão é v1 ou v2?
Certificados e testes
Porque é que a validação de certificados falha no cartão novo e não no antigo?
Pode testar fluxos de assinatura sem bloquear cartões reais?
