Passo a passo

Solicitação de credenciais

As credenciais de acesso aos ambientes de homologação/teste e produção da API de Assinatura Eletrônica devem ser solicitadas por um Gestor Público, por meio do Serviço de Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/governodigital/pt-br/estrategias-e-governanca-digital/transformacao-digital/servico-de-integracao-aos-produtos-de-identidade-digital-gov.br

Para iniciar a solicitação, clique no botão “Iniciar” e siga as instruções fornecidas pelo sistema.

⚠️ Importante: A liberação das credenciais de produção está condicionada à integração prévia do sistema com o Login Único e à sua hospedagem em um domínio oficial do governo (ex.: gov.br, mil.br, edu.br, jus.br, leg.br, def.br, mp.br, tc.br, entre outros), conforme estabelecido nos artigos 3º e 5º da Portaria SGD/MGI nº 7.076, de 2 de outubro de 2024.

Prazo para liberação das credenciais

Após o recebimento e a análise da solicitação, não havendo necessidade de ajustes negociais ou técnicos, os prazos estimados para o envio das credenciais da API de Assinatura Eletrônica Avançada são os seguintes:

Ambiente de Homologação: até 3 dias úteis
Ambiente de Produção: até 5 dias úteis

Alteração de URL(s)

Para alterar a(s) URL(s) de retorno, siga as orientações abaixo:

Integrações em andamento

1. Acesse o Portal do Serviço de Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/governodigital/pt-br/estrategias-e-governanca-digital/transformacao-digital/servico-de-integracao-aos-produtos-de-identidade-digital-gov.br

Clique no botão “Acompanhamento”.
Na aba “Enviar dados/dúvidas” do seu protocolo de solicitação, forneça as seguintes informações:
- client_id
- ambiente (homologação ou produção)
- nova Url de Retorno

Integrações concluídas

Acesse o Portal de Serviço de Pós-Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/governodigital/pt-br/estrategias-e-governanca-digital/transformacao-digital/servico-de-pos-integracao-aos-produtos-do-ecossistema-da-identidade-digital-gov.br
Clique no botão “Iniciar”.
Na aba “Dados da Solicitação” do seu protocolo, selecione o tipo de solicitação “Atualização de URLs” e preencha as informações necessárias.

Dúvidas, Problemas, Alterações

Integrações em andamento

1. Acesse o Portal do Serviço de Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/governodigital/pt-br/estrategias-e-governanca-digital/transformacao-digital/servico-de-integracao-aos-produtos-de-identidade-digital-gov.br

Clique no botão “Acompanhamento”.
Na aba “Enviar dados/dúvidas” do seu protocolo de solicitação, escreva sobre a solicitação.

Integrações concluídas

Acesse o Portal de Serviço de Pós-Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/pt-br/servicos/ofertar-servicos-de-pos-integracao-aos-produtos-do-ecossistema-da-identidade-digital-gov-br
Clique no botão “Iniciar”.
Na aba “Dados da Solicitação” do seu protocolo, selecione o tipo de solicitação “Outras solicitações” e e preencha as informações necessárias.

Integrações disponibilizadas para diversos outros órgãos ou entidades públicas

De acordo com o artigo 13 da Portaria SGD/MGI nº 7.076, de 2 de outubro de 2024, as informações sobre adesão às integrações disponibilizadas a diferentes órgãos ou entidades públicas devem ser enviadas à Secretaria de Governo Digital pelo órgão gestor da respectiva integração.

## Procedimento para o envio

1. Acesse o Portal do Serviço de Pós-Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. Link para a página: https://www.gov.br/pt-br/servicos/ofertar-servicos-de-pos-integracao-aos-produtos-do-ecossistema-da-identidade-digital-gov-br

Clique no botão “Iniciar”.
Na aba “Dados da Solicitação” do seu protocolo, selecione o tipo de solicitação “Atualização de integrações disponibilizadas para diversos órgãos/entidades públicas” e preencha os campos necessários.

As informações devem ser enviadas mensalmente até o dia 05 de cada mês, contendo os dados referentes às integrações realizadas no mês anterior.

Em caso de dúvidas sobre este procedimento, utilize o canal de comunicação oficial: integracaoid@gestao.gov.br

Orientações para testes

De Acordo com a portaria SGD/MGI 11230/2025 as contas digitais da plataforma gov.br são classificadas em três tipos: Bronze, Prata e Ouro. A conta digital bronze permite ao usuário somente a realização de assinaturas simples. Nesta plataforma para realizar uma assinatura avançada, seja qual for o ambiente, o usuário deve possuir conta digital prata ou ouro.

Importante

Documentos assinados digitalmente no ambiente de HOMOLOGAÇÃO são validados em: https://validar.staging.iti.br

Importante

Documentos assinados no ambiente de PRODUÇÃO podem ser validados no serviço de validação de assinaturas eletrônicas do ITI https://validar.iti.gov.br

Troubleshoot:

atributo IdMessageDigest inválido ❌

Mensagem de alerta: Falha ao construir o atributo. Problemas ao obter o hash

Corretude: Invalid

O Hash do PDF foi calculado errado. Verifique a Seção Assinaturas PKCs7 e PDF.

Criar uma conta nível prata gov.br

Acesse https://sso.staging.acesso.gov.br/ e siga passos do tutorial abaixo:

Tutorial conta prata

API de assinatura digital gov.br

Esta API de assinatura segue os princípios do estilo de arquitetura REST e fornece serviços web baseados em HTTP que implementam a assinatura digital utilizando certificados avançados gov.br. Para acesso a esses serviços a API adota o uso do protocolo OAuth 2.0, que é um padrão aberto de delegação de autorização. Deste modo, o uso da API envolve duas etapas:

Geração do token de acesso (Access Token)
Consumo dos serviços de assinatura da API

Diagrama de sequência aplicação cliente e API

O diagrama abaixo apresenta o fluxo de interação entre a aplicação cliente e os serviços de autenticação do Login único e os serviços da API de assinatura.

Requisitar Autenticação e Verificar nível conta

Para as 2 etapas iniciais (“Requisitar Autenticação” e “Verificar nível conta”), acesse https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#passo-a-passo-para-integrar.

Geração do access token

Passo 1: Gerar code

Endereço servidor autorização:

https://cas.staging.iti.br/oauth2.0/authorize?

A aplicação cliente deve redirecionar o navegador do usuário para o endereço do servidor de autorização para de obter seu consentimento para o uso de seu certificado para a assinatura. Nesse processo, a aplicação deve usar credenciais previamente autorizadas no servidor. Esta requisição possui os parâmetros abaixo:

Parâmetro	Valor
response_type	code
client_id	Chave de acesso, que identifica o serviço consumidor da aplicação cadastrada.
scope	Valores possíveis: sign, signature_session, govbr, icp_brasil
redirect_uri	URL de retorno cadastrada para a aplicação cliente. Não necessita utilizar o formato URL Encode.
state	Valor usado para manter o estado entre a solicitação e o retorno de chamada.
nonce	Sequência de caracteres usado para associar uma sessão do serviço consumidor ao token.

O parâmetro scope aceita múltiplos valores separados por espaços, conforme RFC 6749.

Importante

Os escopos sign e signature_session são mutuamente exclusivos, ou seja, apenas um deles deve ser preenchido em cada chamada.

Deve-se incluir no parâmetro scope o valor sign para gerar um token que permite a assinatura de um único hash, de forma que o token gerado só pode ser utilizado uma única vez. Na tentativa de uma nova assinatura com esse mesmo token, um erro será retornado.

Deve-se incluir no parâmetro scope o valor signature_session para gerar um token que permita a assinatura de vários hashes, de forma que o token gerado pode ser utilizado para várias vezes. Neste caso, durante a validade do token, este poderá ser utilizado para realizar várias assinaturas em lote.

https://<Servidor OAuth>/authorize?response_type=code&redirect_uri=<URI de redirecionamento>&scope=sign&client_id=<client_id>

Se o órgão integrador desejar permitir que o cidadão utilize certificados em nuvem fornecidos pelos Prestadores de Serviço de Confiança (PSC) da ICP-Brasil para realizar assinaturas digitais qualificadas através da API de Assinatura, deve-se incluir o valor icp_brasil no parâmetro scope.

Neste caso, será exibida uma tela com todos os PSCs da ICP-Brasil nos quais o cidadão possui certificados qualificados emitidos, para que ele escolha qual certificado utilizar.

A seguir, as regras de combinação de escopos e o tipo de assinatura resultante:

Se nem o escopo icp_brasil e nem o escopo govbr for utilizado, será realizada assinatura com certificado GOV.BR (assinatura avançada que é o comportamento padrão de versões anteriores da API).

Se apenas o escopo govbr estiver presente, será realizada assinatura com certificado GOV.BR (assinatura avançada).

Se apenas o escopo icp_brasil estiver presente, será realizada assinatura com certificado ICP-Brasil (assinatura qualificada).

Se ambos os escopos icp_brasil e govbr estiverem presentes, o cidadão poderá optar por realizar sua assinatura com o certificado ICP-Brasil (assinatura qualificada) ou com o certificado GOV.BR (assinatura avançada).

Importante

O comportamento dos escopos sign e signature_session é o mesmo, independentemente de a assinatura ser GOV.BR ou ICP-Brasil.

Exemplo de url permitindo assinaturas em lote tanto avançadas quanto qualificadas:

https://<Servidor OAuth>/authorize?response_type=code&redirect_uri=<URI de redirecionamento>&scope=signature_session+govbr+icp_brasil&client_id=<client_id>

Caso o cidadão opte por utilizar o certificado da ICP-Brasil (assinatura avançada), ele será direcionado para o PSC da ICP-Brasil para realizar a liberação de acesso à sua chave privada.

Caso o cidadão opte por utilizar o certificado GOV.BR (assinatura qualificada), o serviço pede a autorização expressa do usuário para acessar seu certificado para assinatura. Neste instante será pedido um código de autorização a ser enviado por SMS.

Atenção

No ambiente de homologação, o código de autorização é enviado por SMS e também pode ser utilizado o código 12345. No ambiente de Produção o código de autenticação é enviado por notificação do aplicativo gov.br ou por SMS se usuário não possuir aplicativo gov.br instalado.

Após a autorização, o usuário é redirecionado para o endereço <URI de redirecionamento> enviado no redirect_uri e retorna, como um parâmetro de query, o atributo code e o atributo state. O <URI de redirecionamento> deve ser um endpoint da aplicação correspondente ao padrão autorizado no servidor de autorização, e capaz de receber e tratar o parâmetro “code”. Este atributo deve ser utilizado na fase seguinte para solicitar um Access Token ao servidor de autorização.

Nota

A URL de retorno deve pertencer ao domínio do órgão. Por exemplo: https://www.nomeorgao.gov.br/assinar. Cada órgão e ou serviço que será integrado a API de assinatura deve solicitar credenciais separadas.

Troubleshoot:

Retorno 401: Unauthorized/Acesso não Autorizado

Um dos motivos pode ser que a URL de retorno cadastrada não é exatamente igual à que está sendo utilizada no parâmetro redirect_uri. Neste caso, deve-se solicitar o ajuste da informação no processo aberto.

Passo 2: Solicitar Access Token

Realizar a seguinte requisição HTTP com método POST para o endereço https://cas.staging.iti.br/oauth2.0/token? passando as informações abaixo:

Parâmetro	Valor
code	Código de autorização gerado pelo servidor.
client_id	Chave de acesso, que identifica o serviço consumidor da aplicação cadastrada.
grant_type	authorization_code
client_secret	Chave secreta conhecida apenas pela aplicação cliente e servidor de autorização.
redirect_uri	URI de retorno cadastrada para a aplicação cliente.
Content-Type	application/x-www-form-urlencoded

O parâmetro <redirect_uri> deve ter exatamente o mesmo valor informado no passo 1. Sendo feita corretamente as duas requisições, o servidor OAuth retornará um objeto JSON contendo o Access Token, que deve ser usado nas requisições subsequentes aos endpoints do serviço.

Exemplo de código HTTP de sucesso:

Retorno 200: sucesso

{
"access_token": "eyJhbGciOiJIUzI1NiJ9.
                ZXlKNmFYQWlPaUpFUlVZaUxDSmxibU1pT2lKQk1USTRRMEpETFVoVE1qVTJJaXdpWVd4bklqb2laR2x5SW4wLi5HRWxyUDlFTWJUZTgtc
                2g1ZU5LWWNRLjBUU2o5dnpfZGdyLTMxTEdhamxHbGFza1NzQTU0RFhOVlREWUZFUVF6TWdoeTNsSFc3U0NsSlFqUDJER3BPdHM0M1N1W
                GhwdFBDQmlUN3ZfMmNScWR5cjFhRm5CUk9PRU9aN2hrVHUyTTBrTlprWld0UzEyVUljMllZVnNlMjB1eUhnWTF2Y0pkS3JZWi1Lc
                Wt0d1JuU01KbENhdjZfZV9qaEtKbkUycW10X3Z2Rm5WSldiVWgzaXQ4LXpydEtQVkktdndWVTRfUUhaaGpWb0dUVWF5c2xVRWtVeVBw
                X3RNUjdySV9pcC1NVHp0SnJ0QS1rajB0WUZRWjlBTE1VSGxCaGJZVTBja0FEMWxTREtoVDhER0FyOWxOSVZCQmUxUlU0ZW81OUxkV
                lZCX1VHTVNKMzE3U2FjdmFoeE91cEo5VjFxRU96SlJnQzJ3eEY0blI2Nml1U3ZWeVVLcTFuNUhHZ0dxUFNNZnhwdjBHUmFPNjhDSTVfdW
                lldXdYcncwejRtTndpM19MWFFnNnZ3WGhOTmRCdVluNkh1c0E2eUgtNmV0ZXF0QTY4NkkuVWU3eHNQcWxUZWFtSDJkQUxLVTJKdw.DwbD
                PSdZsRYvyfH-sKx7lanle219DQvt65kRzqsGxyZ",
"token_type": "bearer",
"expires_in": 600
}

Exemplos de códigos HTTP de erro:

Retorno 401: Algum valor do parâmetro informado incorretamente. Exemplo:

{
        "timestamp": 1688566398186,
        "status": 401,
        "error": "Unauthorized",
        "message": "No message available",
        "path": "/oauth2.0/token"
}

Retorno 400: Parâmetro <code> utilizado por mais de uma vez ou inválido.

error=invalid_request

Nota

O servidor OAuth de homologação está delegando a autenticação ao ambiente de staging do gov.br.

Importante: Para valor do parâmetro scope igual a sign, o access token gerado autoriza o uso da chave privada do usuário para a confecção de uma única assinatura eletrônica avançada. O token deve ser usado em até 10 minutos. O tempo de validade do token poderá ser modificado no futuro à discrição do ITI. No caso do valor do parâmetro scope igual a signature_session (assinatura em lote), o access token gerado autoriza o uso da chave privada do usuário para a confecção de várias (até 100 arquivos) assinaturas eletrônicas avançadas durante o prazo de validade do token.

Obtenção do certificado do usuário

Para obtenção do certificado do usuário deve-se fazer uma requisição HTTP GET para endereço https://assinatura-api.staging.iti.br/externo/v2/certificadoPublico enviando o cabeçalho Authorization com o tipo de autorização Bearer e o access token obtido anteriormente. Segue abaixo o parâmetros para requisição:

Parâmetro	Valor
Authorization	Bearer <access token>

Exemplo de requisição:

GET /externo/v2/certificadoPublico HTTP/1.1
Host: assinatura-api.staging.iti.br
Authorization: Bearer AT-183-eRE7ot2y3FpEOTCIo1gwnZ81LMmT5I8c

Será retornado o certificado digital com formato PEM na resposta.

Atenção

Para emissão do certificado é realizada, previamente, a validação da situação cadastral do CPF e do nível identidade da conta gov.br do usuário.

Nível de identidade bronze Se usuário possui nível identidade bronze a API impede a emissão de certificado e retorna código e mensagem abaixo:

Response: 403

Cidadão não possui a identidade (Prata ou Ouro) necessária para uso da assinatura eletrônica digital.

CPF situação cancelada, nula, falecido Se CPF de usuário com as seguintes situações: 1. Titular Falecido - quando há data de óbito vinculada ao CPF; 2. Cancelada por Multiplicidade - quando há mais de uma inscrição no CPF para a mesma pessoa; nesse caso, elege-se um para permanecer ativo e os demais são vinculados a ele; 3. Nula - quando constatada a fraude. 4. Cancelada de Ofício - ato de ofício, no interesse da administração tributária ou determinação judicial. A API impede a emissão de certificado e retorna código e mensagem abaixo:

Response: 403

CPF com situação cancelada, nula ou falecido na Receita Federal não permite uso da assinatura eletrônica digital.

Realização da assinatura digital de um HASH SHA-256 em PKCS#7

Para gerar um pacote PKCS#7 contendo a assinatura digital de um HASH SHA-256 utilizando a chave privada do usuário, deve-se fazer uma requisição HTTP POST para o endereço https://assinatura-api.staging.iti.br/externo/v2/assinarPKCS7 enviando os seguintes parâmetros:

Parâmetros	Valor
Content-Type	application/json
Authorization	Bearer <access token>

Body da requisição:

{ "hashBase64": "<Hash SHA256 codificado em Base64>"}

Exemplo de requisição:

POST /externo/v2/assinarPKCS7 HTTP/1.1
Host: assinatura-api.staging.iti.br
Content-Type: application/json
Authorization: Bearer AT-183-eRE7ot2y3FpEOTCIo1gwnZ81LMmT5I8c

{"hashBase64":"kmm8XNQNIzSHTKAC2W0G2fFbxGy24kniLuUAZjZbFb0="}

Será retornado um arquivo contendo o pacote PKCS#7 com a assinatura digital do hash SHA256-RSA e com o certificado público do usuário. O arquivo retornado pode ser validado em https://verificador.staging.iti.br/.

Atenção

Do mesmo modo do serviço para obtenção do certificado, para gerar uma ou mais assinaturas é realizada, previamente, a validação da situação cadastral do CPF e do nível identidade da conta gov.br do usuário.

Nível de identidade bronze Se usuário possui nível identidade bronze a API impede a assinatura e retorna código e mensagem abaixo:

Response: 403

Cidadão não possui a identidade (Prata ou Ouro) necessária para uso da assinatura eletrônica digital.

CPF situação cancelada, nula, falecido Se CPF de usuário com as seguintes situações: 1. Titular Falecido - quando há data de óbito vinculada ao CPF; 2. Cancelada por Multiplicidade - quando há mais de uma inscrição no CPF para a mesma pessoa; nesse caso, elege-se um para permanecer ativo e os demais são vinculados a ele; 3. Nula - quando constatada a fraude. 4. Cancelada de Ofício - ato de ofício, no interesse da administração tributária ou determinação judicial. A API impede a assinatura e retorna código e mensagem abaixo:

Response: 403

CPF com situação cancelada, nula ou falecido na Receita Federal não permite uso da assinatura eletrônica digital.

Assinatura em Lote: Para gerar múltiplos pacotes PKCS#7, cada qual correspondente a assinatura digital de um HASH SHA-256 distinto (correspondentes a diferentes documentos), deve-se seguir as orientações do tópico Geração do Access Token para solicitação do token que permita esta operação (scope signature_session). Após a obtenção deste token, deve ser feita uma requisição para o endereço https://assinatura-api.staging.iti.br/externo/v2/assinarPKCS7 para cada hash a ser assinado, enviando os mesmo parâmetros informados acima. No código de Exemplo de aplicação pode-se verificar no arquivo assinar.php um exemplo de implementação da chamada ao serviço para uma assinatura em lote. O retorno desta operação será um arquivo contendo o pacote PKCS#7 correspondente a cada hash enviado na requisição ao serviço.

Assinaturas PKCS#7 e PDF

Existem duas formas principais de assinar um documento PDF:

Assinatura detached
Assinatura envelopada

A Assinatura detached faz uso de dois arquivos: (1) o arquivo PDF a ser assinado; e (2) um arquivo de assinatura (.p7s). Nesta modalidade de assinatura, nenhuma informação referente à assinatura é inclusa no PDF. Toda a informação da assinatura está encapsulada no arquivo (.p7s). Qualquer alteração no PDF irá invalidar a assinatura contida no arquivo no arquivo (.p7s). Para validar esta modalidade de assinatura, é necessário apresentar para o software de verificação os dois arquivos, PDF e (.p7s).

Para realizar esta modalidade de assinatura pela API de assinatura eletrônica avançada, deve-se calcular o hash sha256 sobre todo o arquivo PDF e enviá-lo através da operação assinarPKCS7 detalhada no tópico anterior. O arquivo binário retornado como resposta desta operação deve ser salvo com a extensão (.p7s).

A assinatura envelopada, por sua vez, inclui dentro do próprio arquivo PDF o pacote de assinatura PKCS#7. Portanto, não há um arquivo de assinatura separado. Para realizar essa modalidade de assinatura deve-se:

Preparar o documento de assinatura
Calcular quais os bytes (bytes-ranges) do arquivo preparado no passo 1 deverão entrar no computo do hash. Diferentemente da assinatura detached, o cálculo do hash para assinatura envelopadas em PDF não é o hash SHA256 do documento original (integral). É uma parte do documento preparado no passo 1.
Calcular o hash SHA256 desses bytes
Submeter o hash SHA256 à operação assinarPKCS7 desta API.
O resultado da operação assinarPKCS7 deve ser codificado em hexadecimal e embutido no espaço que foi previamente alocado no documento no passo 1.

O detalhamento de como preparar o documento, calcular os bytes-ranges utilizados no computo do hash e como embutir o arquivo PKCS7 no arquivo PDF previamente preparado podem ser encontrados na especificação ISO 32000-1:2008 (Link). Existem bibliotecas que automatizam esse procedimento de acordo com o padrão (ex: PDFBox para Java e iText para C# e Java Exemplos iText).

Recomendações para assinaturas digitais em PDF

O PDF foi especificado e desenvolvido pela empresa Adobe System. A partir da versão PDF 1.6, a Adobe utiliza o padrão ISO 32000-1 em sua especificação. Este padrão define a especificação do formato digital para representação de um documento PDF de forma que permita aos usuários trocar e visualizar documentos independente do ambiente que eles foram criados. Resumidamente, a especificação define a estrutura do conteúdo do arquivo PDF, como este conteúdo pode ser interpretado, acessado, atualizado e armazenado dentro do arquivo.

O padrão PDF possui a funcionalidade chamada Atualização Incremental. Essa funcionalidade permite que o PDF seja modificado acrescentando novas informações após o fim do arquivo. A assinatura de PDF é realizada incorporando uma assinatura digital ao fim do PDF utilizando o mecanismo de Atualização Incremental. Este tipo de implementação protege contra modificação todas as informações anteriores a Assinatura Digital a ser realizada e a própria Assinatura Digital incluída no arquivo. Entretanto, ela não impede que novas Atualizações Incrementais sejam realizadas, alterando visualmente o PDF após uma assinatura ter sido incluída. Ainda assim, sempre é possível recuperar a versão que foi efetivamente assinada, e esta versão não pode ser modificada de forma alguma.

A possibilidade de alteração visual em documentos previamente assinados pode causar confusão por parte de cidadãos e órgãos públicos no momento da validação e verificação de documentos assinados. Por esta razão a partir da Versão 1.5 do PDF, foi introduzido um mecanismo para proteção e controle de alterações passíveis de serem realizadas em documentos PDF assinados. Esse mecanismo é chamado MDP (modification detection and prevention - DocMDP), e permite que a primeira pessoa a assinar o documento, ou seja, o autor, possa especificar quais alterações poderão ser realizadas em futuras atualizações incrementais.

Recomenda-se fortemente que a primeira assinatura realizada em um documento PDF seja configurada da seguinte forma:

Incluir entrada Reference, com uma referência indireta a um Dicionário “Signature Reference”. Suprimir a entrada /M (Time of Signing - ISO32000/2008 - 12.8.1 - Tabela 252) no dicionário de assinatura (Signature Dictionary). Exemplo:

166 0 obj
<<
/Type /Sig
/Filter /Adobe.PPKLite
/SubFilter /adbe.pkcs7.detached
/M
/Reference [168 0 R]
/Contents <24730....>
/ByteRange [0 36705 55651 8985]
>>
Endobj

O dicionário “Signature Reference” conter as entradas “Transform Method” com o valor DocMDP; e, “TransformParams” com uma referência indireta para um dicionário de TransformParams. Exemplo:

168 0 obj
<<
/Type /SigRef
/TransformMethod /DocMDP
/TransformParams 170 0 R
>>

O dicionário “TransformParams” com uma entrada P com valor 2 e entrada V com valor 1.2.

170 0 obj
<<
/Type /TransformParams
/P 2
/V /1.2
>>

Importante

Não é recomendado o uso do dicionário /Perms com entrada /DocMDP por questões de compatibilidade com o Adobe. Ao configurar a primeira assinatura desta forma apenas serão permitidas as seguintes alterações: Preenchimento de formulários, templates e inclusão de novas assinaturas.

Outros valores de P possíveis de serem usados:

P = 1 -> Nenhuma alteração é admitida;
P = 2 -> Alterações permitidas em formulários, templates e inclusão de novas assinaturas; e
P = 3 -> Além das permissões admitidas para P = 2, admite-se também anotações, deleções e modificações.

Nota

A utilização da logo gov.br é permitida nas assinaturas que adicionam imagem ao PDF. A orientações quanto a aplicação da logo podem ser verificadas em Manual de uso da marca Link manual

Orientações para homologação do sistema integrado

A homologação será realizada através da demonstração por video anexado ao processo, demonstrando os fluxos abaixo:

1. Fluxo via Login Único GovBR

Deve-se apresentar o fluxo completo de assinatura, tanto para conta Bronze, quanto para contas Prata/Ouro, conforme descrito a seguir.

### 1.1 Conta Bronze

Passo 1: Login no sistema

Apresentar a tela inicial.
Demonstrar o usuário realizando sua autenticação via Login Único GovBR.

Passo 2: Assinatura não permitida

Caso o sistema permita login com conta nível Bronze, a funcionalidade de assinatura deve estar bloqueada ou indisponível.
Não se deve permitir que o usuário chegue à tela de Autorização.
É obrigatório, independente do usuário ter acesso ou não ao sistema, apresentar uma mensagem informando a impossibilidade de assinatura por ser usuário Bronze. Deve-se também disponibilizar um link para realizar o upgrade da conta.
- Link que deve ser utilizado na mensagem para upgrade da conta: https://confiabilidades.acesso.gov.br/
- Exemplo:
É necessário possuir conta gov.br nível prata ou ouro para utilizar o serviço de assinatura. `Clique aqui <https://confiabilidades.acesso.gov.br/>` para realizar o upgrade da conta.

Atenção

Problema: Usuário conta BRONZE está sendo redirecionado automaticamente para a tela de Autorização. Verifique:

Na url do browser, se o client_id está com o valor correto. Se não estiver, corrija e teste novamente.

Estando o item 1 correto, verifique se estão realizando as chamadas referentes às etapas iniciais “Requisitar Autenticação” e “Verificar nível conta” ANTES de chamar as requisições do contexto de assinatura. Se não estiverem, implemente as etapas faltantes e teste novamente.

Deve-se realizar as chamadas referentes às etapas iniciais pois só assim terão as informações da conta, evitando as chamadas do contexto de assinatura caso o usuário seja conta bronze.

Link para detalhamento da implementação das etapas “Requisitar Autenticação” e “Verificar nível conta”: https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#passo-a-passo-para-integrar

Passo 3: Logout do sistema

Demonstrar o usuário realizando o logout.
O usuário deve ser redirecionado para a tela inicial do sistema.
O logout é obrigatório para a integração com Login Único.
- Orientações no link: https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#acesso-ao-servico-de-log-out.

### 1.2 Conta Prata/Ouro

Passo 1: Login no sistema

Apresentar a tela inicial.
Demonstrar o usuário realizando sua autenticação via Login Único GovBR.

Passo 2: Realização da assinatura

Apresentar como o usuário realiza a assinatura.
Este processo poderá incluir a assinatura de um arquivo gerado pelo próprio sistema ou a assinatura de um arquivo que usuário tenha que anexar ao sistema, isso depende do fluxo de funcionamento do sistema do órgão.

Passo 3: Download do arquivo assinado

Apresentar como usuário faz a visualização/download do arquivo assinado para a validação.
Caso a aplicação utilize assinatura destacada (gerando dois arquivos: .p7s e o arquivo original), o vídeo deve mostrar como o usuário é orientado a fazer o download de ambos os arquivos.

Passo 4: Logout do sistema

Demonstrar o usuário realizando o logout.
O usuário deve ser redirecionado para a tela inicial do sistema.
O logout é obrigatório para a integração com Login Único.
- Orientações no link: https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#acesso-ao-servico-de-log-out.

2. Fluxo via Login Alternativo

Nos sistemas que oferecem login alternativo (diferente do Login Único GovBR), deve-se mostrar o fluxo completo de assinatura, também considerando os diferentes níveis de conta.

Nota

Caso o login alternativo não tenha acesso à área de assinatura, o vídeo deve evidenciar este comportamento.

### 2.1 Conta Bronze

Passo 1: Autenticação via login alternativo

Apresentar a tela inicial.
Demonstrar o usuário realizando sua autenticação via login alternativo.

Passo 2: Solicitação de login GovBR ao tentar assinar

Ao clicar em “Assinar”, deve-se solicitar autenticação via Login Único GovBR.

Passo 3: Assinatura não permitida após login GovBR

Ao realizar o login, demonstrar que o usuário está impossibilitado de realizar a assinatura

Não se deve permitir que o usuário chegue à tela de Autorização.
É obrigatório apresentar uma mensagem informando a impossibilidade de assinatura por ser usuário Bronze. Deve-se também disponibilizar um link para realizar o upgrade da conta.
- Link que deve ser utilizado na mensagem para upgrade da conta: https://confiabilidades.acesso.gov.br/
- Exemplo:
É necessário possuir conta gov.br nível prata ou ouro para utilizar o serviço de assinatura. `Clique aqui <https://confiabilidades.acesso.gov.br/>` para realizar o upgrade da conta.

Atenção

Problema: Usuário conta BRONZE está sendo redirecionado automaticamente para a tela de Autorização. Verifique:

Na url do browser, se o client_id está com o valor correto. Se não estiver, corrija e teste novamente.

Estando o item 1 correto, verifique se estão realizando as chamadas referentes às etapas iniciais “Requisitar Autenticação” e “Verificar nível conta” ANTES de chamar as requisições do contexto de assinatura. Se não estiverem, implemente as etapas faltantes e teste novamente.

Deve-se realizar as chamadas referentes às etapas iniciais pois só assim terão as informações da conta, evitando as chamadas do contexto de assinatura caso o usuário seja conta bronze.

Link para detalhamento da implementação das etapas “Requisitar Autenticação” e “Verificar nível conta”: https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#passo-a-passo-para-integrar

Passo 4: Logout do sistema

Demonstrar o usuário realizando o logout.
O usuário deve ser redirecionado para a tela inicial do sistema.

### 2.2 Conta Prata/Ouro

Passo 1: Autenticação via login alternativo

Apresentar a tela inicial.
Demonstrar o usuário realizando sua autenticação via login alternativo.

Passo 2: Solicitação de login GovBR ao tentar assinar

Ao clicar em “Assinar”, deve-se solicitar autenticação via Login Único GovBR.

Passo 3: Realização da assinatura

Apresentar como o usuário realiza a assinatura.
Este processo poderá incluir a assinatura de um arquivo gerado pelo próprio sistema ou a assinatura de um arquivo que usuário tenha que anexar ao sistema, isso depende do fluxo de funcionamento do sistema do órgão.

Passo 4: Download do arquivo assinado

Apresentar como usuário faz a visualização/download do arquivo assinado para a validação.
Caso a aplicação utilize assinatura destacada (gerando dois arquivos: .p7s e o arquivo original), o vídeo deve mostrar como o usuário é orientado a fazer o download de ambos os arquivos.

Passo 5: Logout do sistema

Demonstrar o usuário realizando o logout.
O usuário deve ser redirecionado para a tela inicial do sistema.

Atenção

O video deverá mostrar no navegador a url da aplicação em todas as etapas da demonstração da jornada.

Exemplo de aplicação

Logo abaixo, encontra-se um pequeno exemplo PHP para prova de conceito.

Download Exemplo PHP

Este exemplo é composto por 4 arquivos:

index.php Formulário para upload de um arquivo
upload.php Script para recepção de arquivo e cálculo de seu hash SHA256. O Resultado do SHA256 é armazenado na sessão do usuário.
assinar.php Implementação do handshake OAuth, assim como a utilização dos dois endpoints acima. Como resultado, uma página conforme a figura abaixo será apresentada, mostrando o certificado emitido para o usuário autenticado e a assinatura.
config.php Arquivo de configuração para executar o exemplo. Os valores $clientid e $secret precisam ser substituídos pelas credenciais de homologação cadastradas para a aplicação cliente.

Para executar o exemplo, é possível utilizar Docker com o comando abaixo:

docker-compose up -d

e acessar o endereço http://127.0.0.1:8080

Erros Comuns

⚠️ Erro 401 – Acesso não autorizado

Este erro ocorre quando o cliente que está solicitando o credenciamento não utiliza corretamente os parâmetros da chamada de autorização.

Solução:

Verifique se as credenciais client_id e redirect_uri estão sendo corretamente utilizadas, pois esses dados devem ser exatamente os mesmos que foram cadastrados e encaminhados previamente no arquivo .txt.

Verifique se a URL de autorização está montada corretamente, garantindo que:

O redirect_uri esteja idêntico ao cadastrado (incluindo protocolo http/https e caminho completo).

O client_id seja exatamente o fornecido no credenciamento.

O scope esteja configurado corretamente (sign ou signature_session).

Exemplo de chamada correta:

https://cas.staging.iti.br/oauth2.0/authorize?response_type=code&scope=signature_session&redirect_uri=<redirect_uri_cadastrado>&client_id=<client_id_cadastrado>

Chave PGP: Validação dos dados

Ao anexar as credenciais ao processo, certifique-se de que:

A chave esteja dentro de uma data de validade (não será aceito chave sem data de expiração)

A chave não esteja expirada

Como criar um par de chaves PGP

GnuPG para Windows

Faça o download do aplicativo Gpg4win em: https://gpg4win.org/download.html O Gpg4win é um pacote de instalação para qualquer versão do Windows, que inclui o software de criptografia GnuPG. Siga abaixo as instruções detalhadas de como gerar um par de chaves PGP:

Após o download, execute a instalação e deixe os seguintes componentes marcados conforme imagem abaixo:

Concluída a instalação, execute o Kleopatra para a criação do par de chaves. Kleopatra é uma ferramenta para gerenciamento de certificados X.509, chaves PGP e também para gerenciamento de certificados de servidores. A janela principal deverá se parecer com a seguinte:

Para criar novo par de chaves (pública e privada), vá até o item do Menu Arquivo → Novo Par de chaves… selecione Criar um par de chaves OpenPGP pessoal. Na tela seguinte informe os detalhes Nome e Email, marque a opção para proteger a chave com senha e clique em Configurações avançadas…
Escolha as opções para o tipo do par de chaves e defina uma data de validade. Esta data pode ser alterada depois. Após confirmação da tela abaixo, abrirá uma janela para informar a senha. O ideal é colocar uma senha forte, que deve conter pelo menos 8 caracteres, 1 digito ou caractere especial.

5. Após concluído, o sistema permite o envio da chave pública por email clicando em Enviar chave pública por e-mail… ou o usuário tem a opção de clicar em Terminar e exportar a chave pública para enviá-la por email posteriormente. Para exportar a chave pública e enviá-la anexo ao email, clique com botão direito na chave criada e depois clique em Exportar…

GnuPG para Linux

Praticamente todas as distribuições do Linux trazem o GnuPG instalado e para criar um par de chaves pública e privada em nome do utilizador ‘Fulano de Tal’, por exemplo, siga os passos abaixo:

Abra o terminal e execute o comando abaixo e informe os dados requisitados (Nome e Email). Se não forem especificados os parâmetros adicionais, o tipo da chave será RSA 3072 bits. Será perguntado uma frase para a senha (frase secreta, memorize-a), basta responder de acordo com o que será pedido.

        $ gpg --gen-key

        gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc.
        This is free software: you are free to change and redistribute it.
        There is NO WARRANTY, to the extent permitted by law.
        gpg: directory '/home/user/.gnupg' created
        gpg: keybox '/home/user/.gnupg/pubring.kbx' created
        Note: Use "gpg --full-generate-key" for a full featured key generation dialog.

    O GnuPG precisa construir uma ID de usuário para identificar sua chave.

        Nome completo: **Fulano de Tal**
        Endereço de correio eletrônico: **fulanodetal@email.com**
        Você selecionou este identificador de usuário: "Fulano de Tal <fulanodetal@email.com>"
        Change (N)ame, (E)mail, or (O)kay/(Q)uit? O

        gpg: /home/user/.gnupg/trustdb.gpg: banco de dados de confiabilidade criado
gpg: chave D5882F501CC722AA marcada como plenamente confiável
gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created
gpg: revocation certificate stored as '/home/user/.gnupg/openpgprevocs.d/269C3D6B65B150A9B349170D5882F501CC722AA.rev'

        Chaves pública e privada criadas e assinadas.

        pub rsa3072 2021-04-30 [SC] [expira: 2023-04-30] 269C3D6B65B150A9B349170D5882F501CC722AA uid Fulano de Tal <fulanodetal@email.com>
sub rsa3072 2021-04-30 [E] [expira: 2023-04-30]

2. Para enviar um documento ou um e-mail cifrado com sua chave, é necessário que a pessoa tenha a sua chave pública. Partindo do ponto que a pessoa fez um pedido da sua chave pública, então é necessário criar um arquivo com a chave e passar o arquivo para o solicitante (por exemplo, podemos passar pelo e-mail). Execute o comando abaixo no terminal do Linux para exportar a sua chave para o arquivo MinhaChave.asc

$ gpg --export 269C3D6B65B150A9B449170D5882F501CC722AA> MinhaChave.asc

A sequência de números e letras “269C3D6B65B150A9B349170D5882F501CC722AA” é o ID da chave (da chave que criamos aqui no exemplo, substitua pelo seu ID) e MinhaChave.asc é o nome do arquivo onde será gravada a chave (pode ser outro nome). O próximo passo é o envio do arquivo com a chave pública para a pessoa e então ela poderá criptografar um e-mail ou um documento com a sua chave pública. Se foi criptografado com a sua chave pública, somente a sua chave privada será capaz de decodificar o documento e a frase secreta de sua chave será requisitada.

Para decifrar um documento que foi criptografado com a sua chave pública basta seguir os passos abaixo, substituindo NomeArquivo.gpg pelo nome do arquivo cifrado. Será solicitada a frase secreta de sua chave privada. Um arquivo com nome ArquivoTextoClaro será criado na mesma pasta. Este arquivo contêm as informações decifradas.

$ gpg -d NomeArquivo.gpg > ArquivoTextoClaro

gpg: criptografado com 3072-bit RSA chave, ID 4628820328759F85, criado 2021-04-24 "Fulano de Tal <fulanodetal@email.com>"