Tutorial: Como Assinar XML para Envio de NF-e na SEFAZ

Introdução

A assinatura digital fornece mecanismos para verificar a autoria associada ao certificado e a integridade de um XML de NF-e quando o perfil, a cadeia e a verificação estão corretos. Uma assinatura incompatível ou inválida pode levar à rejeição pela SEFAZ; a autorização depende também do schema e das regras de negócio.

Neste tutorial, vamos explicar o processo de assinatura XML passo a passo, incluindo XMLDSig, canonização e boas práticas.

O que é Assinatura Digital XML?

A assinatura digital XML (XMLDSig) é um padrão W3C para assinar conteúdo XML. Quando validada com o certificado e as referências corretos, ela permite verificar:

• Autenticidade técnica: O certificado apresentado corresponde à chave que produziu a assinatura
• Integridade: Alterações no conteúdo referenciado podem ser detectadas
• Vínculo documental: A assinatura registra a associação entre o conteúdo e o certificado; efeitos jurídicos dependem do contexto legal

Como Funciona

1. Resumo criptográfico (digest): O XML é processado para gerar um hash
2. Assinatura do Digest: O hash é assinado com a chave privada do certificado
3. Inclusão no XML: A assinatura é adicionada ao documento XML

Estrutura do XMLDSig

Tags Principais

<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
  <SignedInfo>
    <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
    <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha256"/>
    <Reference URI="#NFe123456789">
      <Transforms>
        <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      </Transforms>
      <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
      <DigestValue>...</DigestValue>
    </Reference>
  </SignedInfo>
  <SignatureValue>...</SignatureValue>
  <KeyInfo>
    <X509Data>
      <X509Certificate>...</X509Certificate>
    </X509Data>
  </KeyInfo>
</Signature>

Canonização

A canonização é o processo de normalizar o XML antes de calcular o hash. Dentro do algoritmo e das regras de canonização escolhidos, ela torna comparáveis representações equivalentes do conteúdo referenciado.

Algoritmos comuns:

• C14N: Canonical XML 1.0
• C14N2.0: Canonical XML 2.0
• Exclusive C14N: Canonização exclusiva

Processo de Assinatura

Passo 1: Preparar o XML

1. Monte o XML: Com todos os campos obrigatórios
2. Valide o schema: Use o XSD oficial da SEFAZ
3. Gere o Digest: Calcule o hash do conteúdo a ser assinado

Passo 2: Assinar com o Certificado

1. Extraia a chave privada: Do certificado PFX ou PEM
2. Assine o Digest: Use o algoritmo RSA-SHA256
3. Gere a assinatura: Crie a tag <SignatureValue>

Passo 3: Incluir no XML

1. Posicione a assinatura: Geralmente no final do <infNFe>
2. Referencie corretamente: Use o atributo URI correto
3. Valide a assinatura: Verifique se está correta

Algoritmos de Assinatura

RSA-SHA256

• Algoritmo: RSA com hash SHA-256
• Tamanho da chave: 2048 bits mínimo
• Uso: Pode aparecer em perfis de NF-e; confirme o manual e o destinatário
• Segurança: Depende do algoritmo, da implementação, da chave e do processo de validação

ECDSA-SHA256

• Algoritmo: ECDSA com hash SHA-256
• Curva: P-256 ou P-384
• Uso: Pode aparecer em certificados compatíveis; confirme o perfil exigido
• Segurança: Depende da curva, da implementação, da chave e do processo de validação

Erros Comuns

Reference URI Incorreto

Erro: "Reference URI not found"

Causa: O atributo URI na tag <Reference> não aponta para o elemento correto

Solução: Verifique se o URI corresponde ao id do elemento <infNFe>

Digest Inválido

Erro: "Digest verification failed"

Causa: O hash calculado não confere com o hash na assinatura

Solução: Verifique se o XML não foi alterado após a assinatura

Certificado Inválido

Erro: "Certificate not valid" ou "Key usage not supported"

Causa: O certificado não tem as extensões necessárias ou está vencido

Solução: Use um certificado válido com extensão de assinatura digital

Ferramentas Úteis

Nosso Assinador XML

Use nossa ferramenta online para assinar XMLs de NF-e:

1. Selecione o arquivo XML
2. Selecione o certificado PFX
3. Informe a senha
4. Clique em assinar
5. Baixe o XML assinado

Validação

Após assinar, sempre valide:

1. Schema: Use nosso Validador XML
2. Assinatura: Verifique com ferramentas de validação
3. Teste: Envie para homologação antes de produção

Boas Práticas

1. Valide o XML antes de assinar: Evite erros posteriores
2. Use certificado válido: Verifique validade e extensões
3. Armazene a assinatura: Guarde XML assinado para auditoria
4. Teste em homologação: Sempre valide antes de produção
5. Mantenha o certificado seguro: Nunca compartilhe a chave privada

Conclusão

A assinatura XML é um processo crítico para emissão de NF-e. Compreender XMLDSig, canonização e algoritmos de assinatura é essencial para desenvolvedores fiscais.

Use nossas ferramentas para experimentar e diagnosticar assinaturas XML. Confira o perfil exigido pelo destinatário e valide o resultado em ambiente de testes antes de qualquer transmissão.