├── .gitignore ├── requirements.txt ├── .DS_Store ├── images ├── conta1.png ├── conta2.png ├── conta3.png ├── image.png ├── pgp1.png ├── pgp2.png ├── pgp3.png ├── diagrama_sequencia.png └── diagrama_sequencia2.png ├── arquivos ├── Tutorial.pdf ├── Template_Plug-in_Estados_e_Municipios_Atual.csv └── Template_Plug-in_Estados_e_Municipios_Atual.xlsx ├── .pre-commit-config.yaml ├── downloadFiles ├── exemploApiPhp.zip └── exemploApiPhpITI.zip ├── .gitlint ├── README.md ├── index.rst ├── .readthedocs.yaml ├── Makefile ├── make.bat ├── introducao.rst ├── conf.py ├── LICENSE └── iniciarintegracao.rst /.gitignore: -------------------------------------------------------------------------------- 1 | .Python 2 | build/ 3 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==5.3.0 2 | sphinx_rtd_theme==1.1.1 3 | readthedocs-sphinx-search==0.1.1 4 | -------------------------------------------------------------------------------- /.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/.DS_Store -------------------------------------------------------------------------------- /images/conta1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/conta1.png -------------------------------------------------------------------------------- /images/conta2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/conta2.png -------------------------------------------------------------------------------- /images/conta3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/conta3.png -------------------------------------------------------------------------------- /images/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/image.png -------------------------------------------------------------------------------- /images/pgp1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/pgp1.png -------------------------------------------------------------------------------- /images/pgp2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/pgp2.png -------------------------------------------------------------------------------- /images/pgp3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/pgp3.png -------------------------------------------------------------------------------- /arquivos/Tutorial.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/arquivos/Tutorial.pdf -------------------------------------------------------------------------------- /images/diagrama_sequencia.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/diagrama_sequencia.png -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | repos: 2 | - repo: https://github.com/jorisroovers/gitlint 3 | rev: v0.15.0 4 | hooks: 5 | - id: gitlint 6 | -------------------------------------------------------------------------------- /downloadFiles/exemploApiPhp.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/downloadFiles/exemploApiPhp.zip -------------------------------------------------------------------------------- /images/diagrama_sequencia2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/images/diagrama_sequencia2.png -------------------------------------------------------------------------------- /downloadFiles/exemploApiPhpITI.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/downloadFiles/exemploApiPhpITI.zip -------------------------------------------------------------------------------- /.gitlint: -------------------------------------------------------------------------------- 1 | [general] 2 | ignore=B6 3 | # You HAVE to add the rule here to enable it, only configuring (such as below) 4 | # does NOT enable it. 5 | contrib=contrib-title-conventional-commits 6 | -------------------------------------------------------------------------------- /arquivos/Template_Plug-in_Estados_e_Municipios_Atual.csv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/arquivos/Template_Plug-in_Estados_e_Municipios_Atual.csv -------------------------------------------------------------------------------- /arquivos/Template_Plug-in_Estados_e_Municipios_Atual.xlsx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/servicosgovbr/manual-integracao-assinatura-eletronica/HEAD/arquivos/Template_Plug-in_Estados_e_Municipios_Atual.xlsx -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Roteiro de Integração API de Assinaturas Avançadas 2 | =================================================== 3 | 4 | Sobre 5 | ----- 6 | Documentação de apoio e orientação para entidades públicas interessadas em integrar suas aplicações clientes a API de Assinatura Digital Avançada. 7 | 8 | Como contribuir 9 | --------------- 10 | 11 | Fique livre para enviar issues e contribuir para o projeto. 12 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | .. Roteiro de Integração da Assinatura Eletrônica master file, created by 2 | sphinx-quickstart on Mon Feb 18 09:35:23 2019. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | Roteiro de integração da API de Assinatura Eletrônica GOV.BR 7 | ============================================================= 8 | 9 | .. toctree:: 10 | :maxdepth: 3 11 | :caption: Legislação e conceitos 12 | 13 | introducao 14 | 15 | .. toctree:: 16 | :maxdepth: 3 17 | :caption: Informações técnicas para integração 18 | 19 | iniciarintegracao 20 | 21 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yaml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: 2 7 | 8 | # Set the version of Python and other tools you might need 9 | build: 10 | os: ubuntu-22.04 11 | tools: 12 | python: "3.11" 13 | 14 | # Build documentation in the docs/ directory with Sphinx 15 | sphinx: 16 | configuration: conf.py 17 | 18 | # We recommend specifying your dependencies to enable reproducible builds: 19 | # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 20 | python: 21 | install: 22 | - requirements: requirements.txt -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd -------------------------------------------------------------------------------- /introducao.rst: -------------------------------------------------------------------------------- 1 | Introdução 2 | ============ 3 | A Plataforma de Assinatura GOV.BR pertence a um conjunto de serviços que foram criados com escopo engajado 4 | aos princípios e diretrizes da eficiência pública referenciados na `Lei n° 14.129, de 29 de março de 2021`_. 5 | Composta pelo `Portal de asssinaturas gov.br`_ e pela API de Serviços de Assinatura Eletrônica GOV.BR, a plataforma 6 | disponibiliza, aos gestores públicos, aos provedores de serviços públicos e aos cidadãos, um mecanismo simplificado 7 | para a criação e verificação de assinaturas eletrônicas digitais com validade jurídica e previsão legal estabelecida 8 | na `Lei Nº 14.063, de 23 de setembro de 2020`_. 9 | 10 | Este documento é um roteiro técnico-operacional visa para orientar a integração à API de Serviços de Assinatura 11 | Eletrônica GOV.BR a qualquer ambiente. Contém alguns os passos operacionais e procedimentos administrativos essenciais para autorizar o 12 | acesso aos serviços da API e detalha as formas de chamadas a operações, parâmetros e métodos de integração, e, por último, os procedimentos para permitir a conectividade entre os 13 | ambientes de implantação. 14 | 15 | 16 | .. _`Lei n° 14.129, de 29 de março de 2021`: http://www.planalto.gov.br/ccivil_03/_Ato2019-2022/2021/Lei/L14129.htm 17 | 18 | .. _`Lei Nº 14.063, de 23 de setembro de 2020`: http://www.planalto.gov.br/ccivil_03/_ato2019-2022/2020/lei/L14063.htm 19 | 20 | .. _`Portal de asssinaturas gov.br`: http://www.gov.br/assina -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | # import os 14 | # import sys 15 | # sys.path.insert(0, os.path.abspath('.')) 16 | 17 | 18 | # -- Project information ----------------------------------------------------- 19 | 20 | project = 'Roteiro de Integracão API Assinatura avançada gov.br' 21 | copyright = '2021, Gov.br' 22 | author = 'Gov.br' 23 | 24 | # The full version, including alpha/beta/rc tags 25 | release = '1.0' 26 | 27 | 28 | # -- General configuration --------------------------------------------------- 29 | 30 | # Add any Sphinx extension module names here, as strings. They can be 31 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 32 | # ones. 33 | extensions = [ 34 | ] 35 | 36 | # Add any paths that contain templates here, relative to this directory. 37 | templates_path = ['_templates'] 38 | 39 | # The language for content autogenerated by Sphinx. Refer to documentation 40 | # for a list of supported languages. 41 | # 42 | # This is also used if you do content translation via gettext catalogs. 43 | # Usually you set "language" from the command line for these cases. 44 | language = 'pt-br' 45 | 46 | # List of patterns, relative to source directory, that match files and 47 | # directories to ignore when looking for source files. 48 | # This pattern also affects html_static_path and html_extra_path. 49 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 50 | 51 | 52 | # -- Options for HTML output ------------------------------------------------- 53 | 54 | # The theme to use for HTML and HTML Help pages. See the documentation for 55 | # a list of builtin themes. 56 | # 57 | html_theme = 'sphinx_rtd_theme' 58 | 59 | # Add any paths that contain custom static files (such as style sheets) here, 60 | # relative to this directory. They are copied after the builtin static files, 61 | # so a file named "default.css" will overwrite the builtin "default.css". 62 | html_static_path = ['_static'] -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /iniciarintegracao.rst: -------------------------------------------------------------------------------- 1 | Passo a passo 2 | ================================ 3 | 4 | Solicitação de credenciais 5 | +++++++++++++++++++++++++++ 6 | 7 | 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. 8 | 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 `_ 9 | 10 | Para iniciar a solicitação, clique no botão "Iniciar" e siga as instruções fornecidas pelo sistema. 11 | 12 | ⚠️ **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 `_. 13 | 14 | Prazo para liberação das credenciais 15 | ++++++++++++++++++++++++++++++++++++ 16 | 17 | 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: 18 | 19 | * Ambiente de Homologação: até 3 dias úteis 20 | * Ambiente de Produção: até 5 dias úteis 21 | 22 | Alteração de URL(s) 23 | ++++++++++++++++++++ 24 | 25 | Para alterar a(s) URL(s) de retorno, siga as orientações abaixo: 26 | 27 | **Integrações em andamento** 28 | 29 | 1. Acesse o Portal do Serviço de Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. 30 | 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 `_ 31 | 32 | 2. Clique no botão “Acompanhamento”. 33 | 34 | 3. Na aba “Enviar dados/dúvidas” do seu protocolo de solicitação, forneça as seguintes informações: 35 | 36 | - client_id 37 | - ambiente (homologação ou produção) 38 | - nova Url de Retorno 39 | 40 | 41 | **Integrações concluídas** 42 | 43 | 1. 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 `_ 44 | 45 | 2. Clique no botão **“Iniciar”**. 46 | 47 | 3. 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. 48 | 49 | 50 | Dúvidas, Problemas, Alterações 51 | +++++++++++++++++++++++++++++++ 52 | 53 | **Integrações em andamento** 54 | 55 | 1. Acesse o Portal do Serviço de Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. 56 | 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 `_ 57 | 58 | 2. Clique no botão “Acompanhamento”. 59 | 60 | 3. Na aba “Enviar dados/dúvidas” do seu protocolo de solicitação, escreva sobre a solicitação. 61 | 62 | 63 | **Integrações concluídas** 64 | 65 | 1. 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 `_ 66 | 67 | 2. Clique no botão **“Iniciar”**. 68 | 69 | 3. 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. 70 | 71 | 72 | Integrações disponibilizadas para diversos outros órgãos ou entidades públicas 73 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 74 | 75 | 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. 76 | 77 | ## Procedimento para o envio 78 | 79 | 1. Acesse o Portal do Serviço de Pós-Integração aos Produtos do Ecossistema da Conta Digital GOV.BR. 80 | 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 `_ 81 | 82 | 2. Clique no botão **"Iniciar"**. 83 | 84 | 3. 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. 85 | 86 | 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. 87 | 88 | Em caso de dúvidas sobre este procedimento, utilize o canal de comunicação oficial: integracaoid@economia.gov.br. 89 | 90 | 91 | Orientações para testes 92 | ++++++++++++++++++++++++++ 93 | 94 | 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. 95 | 96 | .. important:: 97 | Documentos assinados digitalmente no ambiente de **HOMOLOGAÇÃO** são validados em: https://h-validar.iti.gov.br/index.html 98 | 99 | .. important:: 100 | 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 101 | 102 | 103 | **Troubleshoot:** 104 | 105 | - atributo *IdMessageDigest* inválido ❌ 106 | - Mensagem de alerta: Falha ao construir o atributo. Problemas ao obter o hash 107 | - Corretude: Invalid 108 | 109 | O Hash do PDF foi calculado errado. Verifique a `Seção Assinaturas PKCs7 e PDF `_. 110 | 111 | Criar uma conta nível prata gov.br 112 | +++++++++++++++++++++++++++++++++++++++ 113 | 114 | 1. Acesse https://sso.staging.acesso.gov.br/ e siga passos do tutorial abaixo: 115 | 116 | `Tutorial conta prata `_ 117 | 118 | API de assinatura digital gov.br 119 | +++++++++++++++++++++++++++++++++++++ 120 | 121 | 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. 122 | 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: 123 | 124 | 1. Geração do token de acesso (Access Token) 125 | 126 | 2. Consumo dos serviços de assinatura da API 127 | 128 | Diagrama de sequência aplicação cliente e API 129 | ++++++++++++++++++++++++++++++++++++++++++++++ 130 | 131 | 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. 132 | 133 | .. image:: images/diagrama_sequencia2.png 134 | 135 | Requisitar Autenticação e Verificar nível conta 136 | +++++++++++++++++++++++++++++++++++++++++++++++ 137 | 138 | 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 `_. 139 | 140 | Geração do access token 141 | +++++++++++++++++++++++ 142 | 143 | **Passo 1: Gerar code** 144 | 145 | **Endereço servidor autorização:** 146 | 147 | .. code-block:: console 148 | 149 | https://cas.staging.iti.br/oauth2.0/authorize? 150 | 151 | 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: 152 | 153 | ================== ================================================================================================== 154 | **Parâmetro** **Valor** 155 | ------------------ -------------------------------------------------------------------------------------------------- 156 | **response_type** code 157 | **client_id** Chave de acesso, que identifica o serviço consumidor da aplicação cadastrada. 158 | **scope** Valores possíveis: sign, signature_session, govbr, icp_brasil 159 | **redirect_uri** URL de retorno cadastrada para a aplicação cliente. Não necessita utilizar o formato URL Encode. 160 | **state** Valor usado para manter o estado entre a solicitação e o retorno de chamada. 161 | **nonce** Sequência de caracteres usado para associar uma sessão do serviço consumidor ao token. 162 | ================== ================================================================================================== 163 | 164 | O parâmetro **scope** aceita múltiplos valores separados por espaços, conforme RFC 6749. 165 | 166 | .. important:: 167 | Os escopos **sign** e **signature_session** são mutuamente exclusivos, ou seja, apenas um deles deve ser preenchido em cada chamada. 168 | 169 | 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. 170 | 171 | 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**. 172 | 173 | .. code-block:: console 174 | 175 | https:///authorize?response_type=code&redirect_uri=&scope=sign&client_id= 176 | 177 | 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**. 178 | 179 | 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. 180 | 181 | A seguir, as regras de combinação de escopos e o tipo de assinatura resultante: 182 | 183 | - 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). 184 | - Se apenas o escopo **govbr** estiver presente, será realizada assinatura com **certificado GOV.BR** (assinatura avançada). 185 | - Se apenas o escopo **icp_brasil** estiver presente, será realizada assinatura com **certificado ICP-Brasil** (assinatura qualificada). 186 | - 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). 187 | 188 | .. important:: 189 | O comportamento dos escopos **sign** e **signature_session** é o mesmo, independentemente de a assinatura ser GOV.BR ou ICP-Brasil. 190 | 191 | Exemplo de url permitindo assinaturas em lote tanto avançadas quanto qualificadas: 192 | 193 | .. code-block:: console 194 | 195 | https:///authorize?response_type=code&redirect_uri=&scope=signature_session+govbr+icp_brasil&client_id= 196 | 197 | 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. 198 | 199 | 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. 200 | 201 | .. Attention:: 202 | 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. 203 | 204 | 205 | Após a autorização, o usuário é redirecionado para o endereço enviado no **redirect_uri** e retorna, como um parâmetro de query, o atributo **code** e o atributo **state**. O 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. 206 | 207 | .. note:: 208 | 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. 209 | 210 | **Troubleshoot:** 211 | 212 | Retorno **401**: Unauthorized/Acesso não Autorizado 213 | 214 | 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. 215 | 216 | **Passo 2: Solicitar Access Token** 217 | 218 | 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: 219 | 220 | ================== ================================================================================================== 221 | **Parâmetro** **Valor** 222 | ------------------ -------------------------------------------------------------------------------------------------- 223 | **code** Código de autorização gerado pelo servidor. 224 | **client_id** Chave de acesso, que identifica o serviço consumidor da aplicação cadastrada. 225 | **grant_type** authorization_code 226 | **client_secret** Chave secreta conhecida apenas pela aplicação cliente e servidor de autorização. 227 | **redirect_uri** URI de retorno cadastrada para a aplicação cliente. 228 | **Content-Type** application/x-www-form-urlencoded 229 | ================== ================================================================================================== 230 | 231 | O parâmetro 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. 232 | 233 | **Exemplo de código HTTP de sucesso:** 234 | 235 | Retorno **200**: sucesso 236 | 237 | .. code-block:: JSON 238 | 239 | { 240 | "access_token": "eyJhbGciOiJIUzI1NiJ9. 241 | ZXlKNmFYQWlPaUpFUlVZaUxDSmxibU1pT2lKQk1USTRRMEpETFVoVE1qVTJJaXdpWVd4bklqb2laR2x5SW4wLi5HRWxyUDlFTWJUZTgtc 242 | 2g1ZU5LWWNRLjBUU2o5dnpfZGdyLTMxTEdhamxHbGFza1NzQTU0RFhOVlREWUZFUVF6TWdoeTNsSFc3U0NsSlFqUDJER3BPdHM0M1N1W 243 | GhwdFBDQmlUN3ZfMmNScWR5cjFhRm5CUk9PRU9aN2hrVHUyTTBrTlprWld0UzEyVUljMllZVnNlMjB1eUhnWTF2Y0pkS3JZWi1Lc 244 | Wt0d1JuU01KbENhdjZfZV9qaEtKbkUycW10X3Z2Rm5WSldiVWgzaXQ4LXpydEtQVkktdndWVTRfUUhaaGpWb0dUVWF5c2xVRWtVeVBw 245 | X3RNUjdySV9pcC1NVHp0SnJ0QS1rajB0WUZRWjlBTE1VSGxCaGJZVTBja0FEMWxTREtoVDhER0FyOWxOSVZCQmUxUlU0ZW81OUxkV 246 | lZCX1VHTVNKMzE3U2FjdmFoeE91cEo5VjFxRU96SlJnQzJ3eEY0blI2Nml1U3ZWeVVLcTFuNUhHZ0dxUFNNZnhwdjBHUmFPNjhDSTVfdW 247 | lldXdYcncwejRtTndpM19MWFFnNnZ3WGhOTmRCdVluNkh1c0E2eUgtNmV0ZXF0QTY4NkkuVWU3eHNQcWxUZWFtSDJkQUxLVTJKdw.DwbD 248 | PSdZsRYvyfH-sKx7lanle219DQvt65kRzqsGxyZ", 249 | "token_type": "bearer", 250 | "expires_in": 600 251 | } 252 | 253 | **Exemplos de códigos HTTP de erro:** 254 | 255 | Retorno **401**: Algum valor do parâmetro informado incorretamente. Exemplo: 256 | 257 | .. code-block:: JSON 258 | 259 | { 260 | "timestamp": 1688566398186, 261 | "status": 401, 262 | "error": "Unauthorized", 263 | "message": "No message available", 264 | "path": "/oauth2.0/token" 265 | } 266 | 267 | Retorno **400**: Parâmetro utilizado por mais de uma vez ou inválido. 268 | 269 | .. code-block:: console 270 | 271 | error=invalid_request 272 | 273 | 274 | .. note:: 275 | O servidor OAuth de homologação está delegando a autenticação ao ambiente de **staging** do gov.br. 276 | 277 | 278 | **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. 279 | 280 | Obtenção do certificado do usuário 281 | ++++++++++++++++++++++++++++++++++ 282 | 283 | 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: 284 | 285 | ================== ====================================================================== 286 | **Parâmetro** **Valor** 287 | ------------------ ---------------------------------------------------------------------- 288 | **Authorization** Bearer 289 | ================== ====================================================================== 290 | 291 | Exemplo de requisição: 292 | 293 | .. code-block:: console 294 | 295 | GET /externo/v2/certificadoPublico HTTP/1.1 296 | Host: assinatura-api.staging.iti.br 297 | Authorization: Bearer AT-183-eRE7ot2y3FpEOTCIo1gwnZ81LMmT5I8c 298 | 299 | Será retornado o certificado digital com formato PEM na resposta. 300 | 301 | .. Attention:: 302 | 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. 303 | 304 | **Nível de identidade bronze** 305 | Se usuário possui nível identidade bronze a API impede a emissão de certificado e retorna código e mensagem abaixo: 306 | 307 | Response: **403** 308 | 309 | .. code-block:: console 310 | 311 | Cidadão não possui a identidade (Prata ou Ouro) necessária para uso da assinatura eletrônica digital. 312 | 313 | **CPF situação cancelada, nula, falecido** 314 | Se CPF de usuário com as seguintes situações: 315 | 1. Titular Falecido - quando há data de óbito vinculada ao CPF; 316 | 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; 317 | 3. Nula - quando constatada a fraude. 318 | 4. Cancelada de Ofício - ato de ofício, no interesse da administração tributária ou determinação judicial. 319 | A API impede a emissão de certificado e retorna código e mensagem abaixo: 320 | 321 | Response: **403** 322 | 323 | .. code-block:: console 324 | 325 | CPF com situação cancelada, nula ou falecido na Receita Federal não permite uso da assinatura eletrônica digital. 326 | 327 | 328 | Realização da assinatura digital de um HASH SHA-256 em PKCS#7 329 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 330 | 331 | 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: 332 | 333 | ================== ====================================================================== 334 | **Parâmetros** **Valor** 335 | ------------------ ---------------------------------------------------------------------- 336 | **Content-Type** application/json 337 | **Authorization** Bearer 338 | ================== ====================================================================== 339 | 340 | Body da requisição: 341 | 342 | .. code-block:: JSON 343 | 344 | { "hashBase64": ""} 345 | 346 | Exemplo de requisição: 347 | 348 | .. code-block:: console 349 | 350 | POST /externo/v2/assinarPKCS7 HTTP/1.1 351 | Host: assinatura-api.staging.iti.br 352 | Content-Type: application/json 353 | Authorization: Bearer AT-183-eRE7ot2y3FpEOTCIo1gwnZ81LMmT5I8c 354 | 355 | {"hashBase64":"kmm8XNQNIzSHTKAC2W0G2fFbxGy24kniLuUAZjZbFb0="} 356 | 357 | 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/. 358 | 359 | .. Attention:: 360 | 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. 361 | 362 | **Nível de identidade bronze** 363 | Se usuário possui nível identidade bronze a API impede a assinatura e retorna código e mensagem abaixo: 364 | 365 | Response: **403** 366 | 367 | .. code-block:: console 368 | 369 | Cidadão não possui a identidade (Prata ou Ouro) necessária para uso da assinatura eletrônica digital. 370 | 371 | **CPF situação cancelada, nula, falecido** 372 | Se CPF de usuário com as seguintes situações: 373 | 1. Titular Falecido - quando há data de óbito vinculada ao CPF; 374 | 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; 375 | 3. Nula - quando constatada a fraude. 376 | 4. Cancelada de Ofício - ato de ofício, no interesse da administração tributária ou determinação judicial. 377 | A API impede a assinatura e retorna código e mensagem abaixo: 378 | 379 | Response: **403** 380 | 381 | .. code-block:: console 382 | 383 | CPF com situação cancelada, nula ou falecido na Receita Federal não permite uso da assinatura eletrônica digital. 384 | 385 | **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. 386 | 387 | Assinaturas PKCS#7 e PDF 388 | +++++++++++++++++++++++++ 389 | 390 | Existem duas formas principais de assinar um documento PDF: 391 | 392 | * Assinatura *detached* 393 | * Assinatura envelopada 394 | 395 | 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). 396 | 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). 397 | 398 | 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). 399 | 400 | 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: 401 | 402 | 1. Preparar o documento de assinatura 403 | 2. 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. 404 | 3. Calcular o hash SHA256 desses *bytes* 405 | 4. Submeter o hash SHA256 à operação **assinarPKCS7** desta API. 406 | 5. 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. 407 | 408 | 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`_). 409 | 410 | Recomendações para assinaturas digitais em PDF 411 | ++++++++++++++++++++++++++++++++++++++++++++++ 412 | 413 | 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. 414 | 415 | 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. 416 | 417 | 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. 418 | 419 | Recomenda-se fortemente que a **primeira assinatura realizada** em um documento PDF seja configurada da seguinte forma: 420 | 421 | 1. 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: 422 | 423 | .. code-block:: console 424 | 425 | 166 0 obj 426 | << 427 | /Type /Sig 428 | /Filter /Adobe.PPKLite 429 | /SubFilter /adbe.pkcs7.detached 430 | /M 431 | /Reference [168 0 R] 432 | /Contents <24730....> 433 | /ByteRange [0 36705 55651 8985] 434 | >> 435 | Endobj 436 | 437 | 2. 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: 438 | 439 | .. code-block:: console 440 | 441 | 168 0 obj 442 | << 443 | /Type /SigRef 444 | /TransformMethod /DocMDP 445 | /TransformParams 170 0 R 446 | >> 447 | 448 | 3. O dicionário *“TransformParams”* com uma entrada *P* com valor 2 e entrada *V* com valor 1.2. 449 | 450 | .. code-block:: console 451 | 452 | 170 0 obj 453 | << 454 | /Type /TransformParams 455 | /P 2 456 | /V /1.2 457 | >> 458 | 459 | .. important:: 460 | Não é recomendado o uso do dicionário */Perms* com entrada */DocMDP* por questões de compatibilidade com o Adobe. 461 | 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**. 462 | 463 | Outros valores de *P* possíveis de serem usados: 464 | 465 | * **P = 1** -> Nenhuma alteração é admitida; 466 | * **P = 2** -> Alterações permitidas em formulários, templates e inclusão de novas assinaturas; e 467 | * **P = 3** -> Além das permissões admitidas para P = 2, admite-se também anotações, deleções e modificações. 468 | 469 | .. note:: 470 | 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 471 | em Manual de uso da marca `Link manual`_ 472 | 473 | Orientações para homologação do sistema integrado 474 | ++++++++++++++++++++++++++++++++++++++++++++++++++ 475 | 476 | A homologação será realizada através da demonstração por video anexado ao processo, demonstrando os fluxos abaixo: 477 | 478 | 1. Fluxo via Login Único GovBR 479 | ------------------------------ 480 | 481 | Deve-se apresentar o fluxo completo de assinatura, tanto para conta **Bronze**, quanto para contas **Prata/Ouro**, conforme descrito a seguir. 482 | 483 | ### 1.1 Conta Bronze 484 | 485 | **Passo 1: Login no sistema** 486 | 487 | - Apresentar a tela inicial. 488 | - Demonstrar o usuário realizando sua autenticação via Login Único GovBR. 489 | 490 | **Passo 2: Assinatura não permitida** 491 | 492 | - Caso o sistema permita login com conta nível Bronze, a funcionalidade de assinatura deve estar **bloqueada ou indisponível**. 493 | - **Não se deve permitir** que o usuário chegue à **tela de Autorização**. 494 | - É **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**. 495 | 496 | - Link que deve ser utilizado na mensagem para upgrade da conta: https://confiabilidades.acesso.gov.br/ 497 | 498 | - Exemplo: 499 | 500 | .. code-block:: none 501 | 502 | É necessário possuir conta gov.br nível prata ou ouro para utilizar o serviço de assinatura. `Clique aqui ` para realizar o upgrade da conta. 503 | 504 | .. Attention:: 505 | Problema: Usuário conta BRONZE está sendo redirecionado automaticamente para a **tela de Autorização**. 506 | Verifique: 507 | 1. Na url do browser, se o client_id está com o valor correto. Se não estiver, corrija e teste novamente. 508 | 2. 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. 509 | 510 | 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. 511 | 512 | 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 `_ 513 | 514 | 515 | **Passo 3: Logout do sistema** 516 | 517 | - Demonstrar o usuário realizando o logout. 518 | - O usuário deve ser redirecionado para a **tela inicial** do sistema. 519 | - O logout é **obrigatório** para a integração com Login Único. 520 | 521 | - Orientações no link: `https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#acesso-ao-servico-de-log-out `_. 522 | 523 | ### 1.2 Conta Prata/Ouro 524 | 525 | **Passo 1: Login no sistema** 526 | 527 | - Apresentar a tela inicial. 528 | - Demonstrar o usuário realizando sua autenticação via Login Único GovBR. 529 | 530 | **Passo 2: Realização da assinatura** 531 | 532 | - Apresentar como o usuário realiza a assinatura. 533 | - 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. 534 | 535 | **Passo 3: Download do arquivo assinado** 536 | 537 | - Apresentar como usuário faz a visualização/download do arquivo assinado para a validação. 538 | - 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**. 539 | 540 | **Passo 4: Logout do sistema** 541 | 542 | - Demonstrar o usuário realizando o logout. 543 | - O usuário deve ser redirecionado para a **tela inicial** do sistema. 544 | - O logout é **obrigatório** para a integração com Login Único. 545 | 546 | - Orientações no link: `https://acesso.gov.br/roteiro-tecnico/iniciarintegracao.html#acesso-ao-servico-de-log-out `_. 547 | 548 | 2. Fluxo via Login Alternativo 549 | ------------------------------ 550 | 551 | 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. 552 | 553 | .. note:: 554 | Caso o login alternativo **não tenha acesso à área de assinatura**, o vídeo deve evidenciar este comportamento. 555 | 556 | ### 2.1 Conta Bronze 557 | 558 | **Passo 1: Autenticação via login alternativo** 559 | 560 | - Apresentar a tela inicial. 561 | - Demonstrar o usuário realizando sua autenticação via login alternativo. 562 | 563 | **Passo 2: Solicitação de login GovBR ao tentar assinar** 564 | 565 | - Ao clicar em "Assinar", deve-se solicitar autenticação via Login Único GovBR. 566 | 567 | **Passo 3: Assinatura não permitida após login GovBR** 568 | 569 | Ao realizar o login, demonstrar que o usuário está impossibilitado de realizar a assinatura 570 | 571 | - **Não se deve permitir** que o usuário chegue à **tela de Autorização**. 572 | - É **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**. 573 | 574 | - Link que deve ser utilizado na mensagem para upgrade da conta: https://confiabilidades.acesso.gov.br/ 575 | 576 | - Exemplo: 577 | 578 | .. code-block:: none 579 | 580 | É necessário possuir conta gov.br nível prata ou ouro para utilizar o serviço de assinatura. `Clique aqui ` para realizar o upgrade da conta. 581 | 582 | .. Attention:: 583 | Problema: Usuário conta BRONZE está sendo redirecionado automaticamente para a **tela de Autorização**. 584 | Verifique: 585 | 1. Na url do browser, se o client_id está com o valor correto. Se não estiver, corrija e teste novamente. 586 | 2. 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. 587 | 588 | 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. 589 | 590 | 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 `_ 591 | 592 | 593 | **Passo 4: Logout do sistema** 594 | 595 | - Demonstrar o usuário realizando o logout. 596 | - O usuário deve ser redirecionado para a **tela inicial** do sistema. 597 | 598 | ### 2.2 Conta Prata/Ouro 599 | 600 | **Passo 1: Autenticação via login alternativo** 601 | 602 | - Apresentar a tela inicial. 603 | - Demonstrar o usuário realizando sua autenticação via login alternativo. 604 | 605 | **Passo 2: Solicitação de login GovBR ao tentar assinar** 606 | 607 | - Ao clicar em "Assinar", deve-se solicitar autenticação via Login Único GovBR. 608 | 609 | **Passo 3: Realização da assinatura** 610 | 611 | - Apresentar como o usuário realiza a assinatura. 612 | - 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. 613 | 614 | **Passo 4: Download do arquivo assinado** 615 | 616 | - Apresentar como usuário faz a visualização/download do arquivo assinado para a validação. 617 | - 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**. 618 | 619 | **Passo 5: Logout do sistema** 620 | 621 | - Demonstrar o usuário realizando o logout. 622 | - O usuário deve ser redirecionado para a **tela inicial** do sistema. 623 | 624 | 625 | .. Attention:: 626 | O video deverá mostrar no navegador a url da aplicação em todas as etapas da demonstração da jornada. 627 | 628 | Exemplo de aplicação 629 | ++++++++++++++++++++ 630 | 631 | Logo abaixo, encontra-se um pequeno exemplo PHP para prova de conceito. 632 | 633 | `Download Exemplo PHP `_ 634 | 635 | Este exemplo é composto por 4 arquivos: 636 | 637 | * **index.php** Formulário para upload de um arquivo 638 | * **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. 639 | * **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. 640 | * **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. 641 | 642 | .. image:: images/image.png 643 | 644 | 645 | Para executar o exemplo, é possível utilizar Docker com o comando abaixo: 646 | 647 | .. code-block:: console 648 | 649 | docker-compose up -d 650 | 651 | e acessar o endereço http://127.0.0.1:8080 652 | 653 | 654 | Chave PGP: Validação dos dados 655 | ++++++++++++++++++++++++++++++ 656 | Ao anexar as credenciais ao processo, certifique-se de que: 657 | 658 | - A chave esteja dentro de uma data de validade (não será aceito chave sem data de expiração) 659 | 660 | - A chave não esteja expirada 661 | 662 | 663 | Como criar um par de chaves PGP 664 | +++++++++++++++++++++++++++++++ 665 | 666 | **GnuPG para Windows** 667 | 668 | Faça o download do aplicativo Gpg4win em: https://gpg4win.org/download.html 669 | 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: 670 | 671 | 1. Após o download, execute a instalação e deixe os seguintes componentes marcados conforme imagem abaixo: 672 | 673 | .. image:: images/pgp1.png 674 | 675 | 2. 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: 676 | 677 | .. image:: images/pgp2.png 678 | 679 | 3. 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...** 680 | 681 | 4. 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. 682 | 683 | .. image:: images/pgp3.png 684 | 685 | 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 686 | botão direito na chave criada e depois clique em **Exportar...** 687 | 688 | **GnuPG para Linux** 689 | 690 | 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: 691 | 692 | 693 | 1. 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. 694 | 695 | .. code-block:: console 696 | 697 | $ gpg --gen-key 698 | 699 | gpg (GnuPG) 2.2.19; Copyright (C) 2019 Free Software Foundation, Inc. 700 | This is free software: you are free to change and redistribute it. 701 | There is NO WARRANTY, to the extent permitted by law. 702 | gpg: directory '/home/user/.gnupg' created 703 | gpg: keybox '/home/user/.gnupg/pubring.kbx' created 704 | Note: Use "gpg --full-generate-key" for a full featured key generation dialog. 705 | 706 | O GnuPG precisa construir uma ID de usuário para identificar sua chave. 707 | 708 | Nome completo: **Fulano de Tal** 709 | Endereço de correio eletrônico: **fulanodetal@email.com** 710 | Você selecionou este identificador de usuário: "Fulano de Tal " 711 | Change (N)ame, (E)mail, or (O)kay/(Q)uit? O 712 | 713 | gpg: /home/user/.gnupg/trustdb.gpg: banco de dados de confiabilidade criado 714 | gpg: chave D5882F501CC722AA marcada como plenamente confiável 715 | gpg: directory '/home/user/.gnupg/openpgp-revocs.d' created 716 | gpg: revocation certificate stored as '/home/user/.gnupg/openpgprevocs.d/269C3D6B65B150A9B349170D5882F501CC722AA.rev' 717 | 718 | Chaves pública e privada criadas e assinadas. 719 | 720 | pub rsa3072 2021-04-30 [SC] [expira: 2023-04-30] 269C3D6B65B150A9B349170D5882F501CC722AA uid Fulano de Tal 721 | sub rsa3072 2021-04-30 [E] [expira: 2023-04-30] 722 | 723 | 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 724 | 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** 725 | 726 | .. code-block:: console 727 | 728 | $ gpg --export 269C3D6B65B150A9B449170D5882F501CC722AA> MinhaChave.asc 729 | 730 | 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). 731 | 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. 732 | 733 | 3. 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. 734 | 735 | .. code-block:: console 736 | 737 | $ gpg -d NomeArquivo.gpg > ArquivoTextoClaro 738 | 739 | gpg: criptografado com 3072-bit RSA chave, ID 4628820328759F85, criado 2021-04-24 "Fulano de Tal " 740 | 741 | 742 | 743 | 744 | 745 | 746 | .. |site externo| image:: images/site-ext.gif 747 | .. _`codificador para Base64`: https://www.base64decode.org/ 748 | .. _`OpenID Connect`: https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse 749 | .. _`auth 2.0 Redirection Endpoint`: https://tools.ietf.org/html/rfc6749#section-3.1.2 750 | .. _`Exemplos de Integração`: exemplointegracao.html 751 | .. _`Design System do Governo Federal`: http://dsgov.estaleiro.serpro.gov.br/ds/componentes/button 752 | .. _`Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Selos)`: iniciarintegracao.html#resultado-esperado-do-acesso-ao-servico-de-confiabilidade-cadastral-selos 753 | .. _`Resultado Esperado do Acesso ao Serviço de Confiabilidade Cadastral (Categorias)` : iniciarintegracao.html#resultado-esperado-do-acesso-ao-servico-de-confiabilidade-cadastral-categorias 754 | .. _`Documento verificar Código de Compensação dos Bancos` : arquivos/TabelaBacen.pdf 755 | .. _`Login Único`: https://acesso.gov.br/roteiro-tecnico/index.html 756 | .. _`Lei n° 14.063`: http://www.planalto.gov.br/ccivil_03/_ato2019-2022/2020/lei/L14063.htm 757 | .. _`SEDGGME Nº 2.154/2021`: https://www.in.gov.br/web/dou/-/portaria-sedggme-n-2.154-de-23-de-fevereiro-de-2021-304916270 758 | .. _`Link manual`: https://www.gov.br/ds/downloads/manuais-orientadores 759 | .. _`Link`: https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf 760 | .. _`Exemplos iText`: https://kb.itextpdf.com/itext/examples 761 | --------------------------------------------------------------------------------