...
Estas palavras-chave não são usadas como termos de dicionário, de modo que qualquer ocorrência deles deve ser interpretada como palavras-chave e não devem ser interpretados com seus significados de linguagem natural.
1. Escopo
Este documento especifica os tipos de certificados necessários para:
Autenticar mutuamente (MTLS - Mutual TLS) as aplicações dos participantes;
Assinatura de Mensagens (JWS - JSON Web Signature) de aplicações para garantir a autenticidade e não repúdio de mensagens entre os participantes;
Apresentar um canal seguro e confiável para clientes do Open Finance Brasil;
Autenticar participantes no Diretório de participantes do Open Finance Brasil.
2. Referências Normativas
Os seguintes documentos referenciados são indispensáveis para a aplicação deste documento. Para referências datadas, apenas a edição citada se aplica. Para referências não datadas, a última edição do documento referenciado (incluindo quaisquer emendas) se aplica.
[ISODIR2] - ISO/IEC Directives Part 2 [ISODIR2]: https://www.iso.org/sites/directives/current/part2/index.xhtml
[RFC5280] - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile: https://datatracker.ietf.org/doc/html/rfc5280
[RFC7519] - JSON Web Token (JWT) [RFC7519]:https://tools.ietf.org/html/rfc7519
[RFC7515] - JSON Web Signature (JWS) [RFC7515] :https://datatracker.ietf.org/doc/html/rfc7515
[RFC7591] - OAuth 2.0 Dynamic Client Registration Protocol [RFC7591]:https://tools.ietf.org/html/rfc7591
[RFC7592] - OAuth 2.0 Dynamic Client Registration Management Protocol [RFC7592]:https://tools.ietf.org/html/rfc7592
[BCP195] - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) [BCP195]: https://tools.ietf.org/html/bcp195
[RFC8705] - OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens [RFC8705]: https://tools.ietf.org/html/rfc8705
[OFB-FAPI] - Open Finance Brasil Financial-grade API Security Profile 1.0 [OFB-FAPI]: https://github.com/OpenBanking-Brasil/specs-seguranca/open-banking-brasil-financial-api-1_ID3.html
[OFB-FAPI-DCR] - Open Finance Brasil Financial-grade API Dynamic Client Registration Profile 1.0 [OFB-FAPI-DCR]: [PT] Open Finance Brasil Financial-grade API Dynamic Client Registration 1.0 Implementers Draft 3
[DOC-ICP-01] - DECLARAÇÃO DE PRÁTICAS DE CERTIFICAÇÃO DA AUTORIDADE CERTIFICADORA RAIZ DA ICP-BRASIL: https://www.gov.br/iti/pt-br/centrais-de-conteudo/doc-icp-01-v-5-2-dpc-da-ac-raiz-da-icp-brasil-pdf
[RFC6749] - The OAuth 2.0 Authorization Framework [RFC6749]: https://tools.ietf.org/html/rfc6749
[BCB-IN134] - Manual de Segurança do Open Finance: https://www.in.gov.br/web/dou/-/instrucao-normativa-bcb-n-134-de-22-de-julho-de-2021-3345585364
[RFC2818] - HTTP Over TLS: https://datatracker.ietf.org/doc/html/rfc2818
[RFC5246] - The Transport Layer Security (TLS) Protocol Version 1.2 https://www.rfc-editor.org/rfc/rfc5246.txt
3. Termos e Definições
Para o propósito deste documento os termos definidos na [RFC5280], [BCP195], [RFC8705], e ISO29100 são aplicáveis.
4. Glossário
API - Application Programming Interface
DCR - Dynamic Client Registration
HTTP - Hyper Text Transfer Protocol
ICP - Infraestrutura de Chave Públicas Brasileira
SS - Software Statement
SSA - Software Statement Assertion
TLS - Transport Layer Security
mTLS - Mutual Transport Layer Security
subjectDN – Subject Distinguished Name
RDN – Relative Distinguished Name
5. Padrão de Certificados Open Finance Brasil
5.1 Introdução
O ecossistema do Open Finance Brasil faz uso de cadeias de certificados e protocolo TLS para garantir a confidencialidade, autenticação e integridade do canal de comunicação utilizado pelas APIs das instituições participantes, bem como dos clientes de cada um dos participantes.
Os certificados utilizados pelo Open Finance Brasil também são necessários para autenticar as aplicações através do oAuth 2.0 mTLS ou private_key_jwt, além de também servirem para realizar a assinatura de payload pelo uso de JWS. Outra atribuição importante dos certificados é autenticar e apresentar um canal seguro para o usuário final no ato de autenticação e uso dos serviços prestados pela entidade participante.
5.2 Certificados ICP-Brasil
Os certificados emitidos pelas Autoridades Certificadoras autorizadas pelo ICP-Brasil são utilizados apenas na comunicação entre as entidades participantes do ecossistema do Open Finance Brasil.
...
Tipo A do ICP-Brasil;
Algoritmo de Chaves: RSA 2048 bits;
Message Digest: SHA 256 bits.
5.2.1. Certificado Servidor
O Certificado Servidor deve ser emitido para proteger e autenticar o canal TLS utilizado pelas APIs que serão consumidas pelas aplicações cliente de entidades participantes do Open Finance.
...
O certificado de servidor precisa ser enviado com a cadeia intermediária, conforme RFC5246.
5.2.2. Certificado Cliente
Os Certificados de Aplicação Cliente (Transporte) são utilizados para autenticar o canal mTLS e para realizar a autenticação da aplicação cliente através de oAuth2.0 mTLS ou private_key_jwt, de acordo com o cadastro da aplicação realizado pelo processo de Dynamic Client Registration junto à entidade transmissora. Sobre o mTLS, o certificado cliente precisa ser enviado com a cadeia intermediária, conforme RFC5246.
Para emissão de Certificado Cliente é necessário que a instituição participante do Open Finance Brasil tenha realizado o cadastro da aplicação no Serviço de Diretório, através do processo de emissão de Software Statement Assertion, e com isso já tenha obtido o valor de Software Statement ID.
5.2.2.1. Atributos Open Finance Brasil
serialNumber: Cadastro Nacional de Pessoal Jurídica (CNPJ) da pessoa jurídica titular do certificado e associado ao atributo UID e Software Statement ID, durante validação junto ao Serviço de Diretório do Open Finance Brasil;
organizationIdentifier: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Finance Brasil; Para certificados emitidos até 31 de Agosto de 2022 o campo utilizado para essa informação era o organizationalUnitName.
UID: Software Statement ID cadastrado no Serviço de Diretório do Open Finance Brasil e pertencente ao CNPJ e Código de Participante.
...
Subject Alternative Name
dNSName: FQDN ou Wildcard
5.2.3. Certificado de Assinatura
Os Certificados de Assinatura são utilizados para realizar assinatura do payload através do uso de JWS (JSON Web Signature).
5.2.3.1. Atributos Open Finance Brasil Presentes no Certificado
UID: Código de Participante associado ao CNPJ listado no Serviço de Diretório do Open Finance Brasil;
commonName: Razão Social cadastrado no Serviço de Diretório do Open Finance Brasil e pertencente ao CNPJ e Código de Participante.
...
Apenas deverá ser aceito certificados indicados com "Situação: válido
" nestes repositórios do ITI acima referenciados que são de Cadeia ICP-Brasil v5 e v10.
5.2.4. Certificado para Front-End
Os certificados para Front-End são utilizados para disponibilizar serviços, em geral páginas Web, com uso de TLS, que são acessados pelo usuário final. Dado a sua finalidade, e para garantir maior interoperabilidade, os certificados devem ser do tipo EV (Extended Validation) e devem ser ser gerados através de uma autoridade certificadora válida, seguindo as regras definidas na RFC 5280 e RFC 2818, em conformidade com os princípios e critérios WebTrust.
5.2.5. Sobre certificados para troca de informações entre instituições autorizadas e parceiros
De acordo com a seção IV da Resolução Conjunta nº 1 de 4 de maio de 2020, o estabelecimento de parcerias bilaterais entre instituições autorizadas e parceiros é um arranjo previsto na regulação e que deve observar, no que couber, inclusive os mesmos padrões e certificados de segurança que são aplicáveis para a troca de informações entre as instituições participantes.
...
Os valores para o preenchimento dos atributos exigidos nessa especificação, mas não aplicáveis ao parceiro, deveriam ser definidos em comum acordo entre a instituição autorizada e o parceiro, o que não isenta da instituição autorizada a responsabilidade pelo preenchimento.
6. Reconhecimento
Agradecemos a todos que estabeleceram as bases para o compartilhamento seguro e seguro de dados por meio da formação do Grupo de Trabalho FAPI da OpenID Foundation, o GT-Segurança do Open Finance Brasil e aos pioneiros que ficarão em seus ombros.
...
João Rodolfo Vieira (Itaú)
José Michael Dias (Grupo Pan)
Marcos Rodrigues (Itaú)
Nic Marcondes (Quanto)
Ralph Bragg (Raidiam)
7. Informativo
Copyright (c) 2023 Estrutura Inicial do Open Finance Brasil.
...
A tecnologia descrita nesta especificação foi disponibilizada a partir de contribuições de várias fontes, incluindo membros da OpenID Foundation, do GT-Segurança do Open Finance Brasil e outros. Embora a Estrutura Inicial do Open Finance Brasil tenha tomado medidas para ajudar a garantir que a tecnologia esteja disponível para distribuição, ela não toma posição quanto à validade ou escopo de qualquer propriedade intelectual ou outros direitos que possam ser reivindicados como pertencentes à implementação ou uso do tecnologia descrita nesta especificação ou até que ponto qualquer licença sob tais direitos pode ou não estar disponível; nem representa que fez qualquer esforço independente para identificar tais direitos. A Estrutura Inicial do Open Finance Brasil e os contribuidores desta especificação não oferecem (e por meio deste expressamente se isentam de quaisquer) garantias (expressas, implícitas ou de outra forma), incluindo garantias implícitas de comercialização, não violação, adequação a uma finalidade específica ou título, relacionados a esta especificação, e todo o risco quanto à implementação desta especificação é assumido pelo implementador. A política de Direitos de Propriedade Intelectual do Open Finance Brasil exige que os contribuidores ofereçam uma promessa de patente de não fazer valer certas reivindicações de patentes contra outros contribuidores e implementadores. A Estrutura Inicial do Open Finance Brasil convida qualquer parte interessada a trazer à sua atenção quaisquer direitos autorais, patentes, pedidos de patentes ou outros direitos de propriedade que possam abranger a tecnologia que possa ser necessária para praticar esta especificação.
8. Apêndice
8.1. Modelo de Configuração de Certificado Cliente - OpenSSL *Para certificados emitidos até 31 Agosto de 2022
Bloco de código |
---|
[req] default_bits = 2048 default_md = sha256 encrypt_key = yes prompt = no string_mask = nombstr distinguished_name = client_distinguished_name req_extensions = req_cert_extensions [ client_distinguished_name ] businessCategory = <tipo de entidade> jurisdictionCountryName = BR serialNumber = <CNPJ> countryName = BR organizationName = <Razao Social> stateOrProvinceName = <UF> localityName = <Cidade> organizationalUnitName = <Código de Participante> UID = <Software Statement ID emitido pelo diretório> commonName = <FQDN|Wildcard> [ req_cert_extensions ] basicConstraints = CA:FALSE subjectAltName = @alt_name keyUsage = critical,digitalSignature,keyEncipherment extendedKeyUsage = clientAuth [ alt_name ] DNS = <FQDN|Wildcard> |
8.2. Modelo de Configuração de Certificado Cliente - OpenSSL *Para certificados emitidos após 31 Agosto 2022
Bloco de código |
---|
oid_section = OIDs [req] default_bits = 2048 default_md = sha256 encrypt_key = yes prompt = no string_mask = nombstr distinguished_name = client_distinguished_name req_extensions = req_cert_extensions [ OIDs ] organizationIdentifier = 2.5.4.97 [ client_distinguished_name ] businessCategory = <tipo de entidade> jurisdictionCountryName = BR serialNumber = <CNPJ> countryName = BR organizationName = <Razao Social> stateOrProvinceName = <UF> localityName = <Cidade> organizationIdentifier = OFBBR-<Código de Participante> UID = <Software Statement ID emitido pelo diretório> commonName = <FQDN|Wildcard> [ req_cert_extensions ] basicConstraints = CA:FALSE subjectAltName = @alt_name keyUsage = critical,digitalSignature,keyEncipherment extendedKeyUsage = clientAuth [ alt_name ] DNS = <FQDN|Wildcard> |
8.3. Modelo de Configuração de Certificado de Assinatura
Bloco de código |
---|
[req] default_bits = 2048 default_md = sha256 encrypt_key = yes prompt = no string_mask = nombstr distinguished_name = client_distinguished_name req_extensions = req_cert_extensions [ client_distinguished_name ] UID = <Código de Participante> countryName = BR organizationName = ICP-Brasil 0.organizationalUnitName = <Autoridade Certificadora> 1.organizationalUnitName = <CNPJ da Autoridade Registradora> 2.organizationalUnitName = <Tipo de validação> commonName = <Razão Social> [ req_cert_extensions ] basicConstraints = CA:FALSE subjectAltName = @alt_name keyUsage = critical,digitalSignature,nonRepudiation [ alt_name ] otherName.0 = 2.16.76.1.3.2;PRINTABLESTRING:<Nome da pessoal responsável pela entidade>#CNPJ otherName.1 = 2.16.76.1.3.3;PRINTABLESTRING:<CNPJ> otherName.2 = 2.16.76.1.3.4;PRINTABLESTRING:<CPF/PIS/RF da Pessoa responsável> otherName.3 = 2.16.76.1.3.7;PRINTABLESTRING:<Número de INSS> |
8.4. Tabela com Endpoints vs Tipo de Certificado e mTLS
Abaixo apresentamos quais endpoints podem ser publicados utilizando certificado EV como autenticação do consentimento e os endpoints de autenticação de APIs privadas/negócios que devem ser publicadas usando certificado ICP. Você também poderá verificar quais endpoints devem proteger suas conexões utilizando mTLS.
...
Fase | Grupo | API | Certificado | mTLS |
---|---|---|---|---|
NA | OIDC | .well-known/openid-configuration | EV ou ICP WEB SSL | |
NA | OIDC | jwks_uri | EV ou ICP WEB SSL | |
NA | OIDC | authorization_endpoint | EV | |
NA | OIDC | token_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | userinfo_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | pushed_authorization_request_endpoint | ICP WEB SSL | Obrigatório |
NA | DCR | registration_endpoint | ICP WEB SSL | Obrigatório |
NA | OIDC | revocation_endpoint | ICP WEB SSL | Obrigatório |
2 | Consentimentos | /consents/* | ICP WEB SSL | Obrigatório |
2 | Resources | /resources/* | ICP WEB SSL | Obrigatório |
2 | Dados | /customers/* | ICP WEB SSL | Obrigatório |
2 | Cartão | /credit-cards-accounts/* | ICP WEB SSL | Obrigatório |
2 | Contas | /accounts/* | ICP WEB SSL | Obrigatório |
2 | Empréstimos | /loans/* | ICP WEB SSL | Obrigatório |
2 | Financiamentos | /financings/* | ICP WEB SSL | Obrigatório |
2 | Adiantamento | /unarranged-accounts-overdraft/* | ICP WEB SSL | Obrigatório |
2 | Direitos Creditórios | /invoice-financings/* | ICP WEB SSL | Obrigatório |
3 | Pagamentos | /payments/* | ICP WEB SSL | Obrigatório |
9. Padrão do Subject DN do Certificado Cliente Open Finance - Após 19 de janeiro de 2023 {#subjectDNtemplates}
Em 19 de Janeiro de 2023 foi padronizado a sequência e codificação do Subject DN utilizado nos Certificados Open Finance Cliente. Abaixo é determinado a sequência e codificação de como os atributos dos certificados devem ser apresentados no Subject DN.
...
busque pelo KID do certificado, posteriormente busque pela Claim: x5dn
9.1. Chave Pública de Certificado Exemplo:
9.2. Exemplo Subject Distinguished Name do Certificado - Legível para Humanos:
Bloco de código |
---|
subject=businessCategory = Private Organization, jurisdictionC = BR, serialNumber = 43142666000197, C = BR, O = Chicago Advisory Partners, ST = SP, L = Sao Paulo, organizationIdentifier = OFBBR-d7384bd0-842f-43c5-be02-9d2b2d5efc2c, UID = bc97b8f0-cae0-4f2f-9978-d93f0e56a833, CN = web.conftpp.directory.openbankingbrasil.org.br |
9.3. Relative Distinguished Name (RDN) - Legível para Humanos
...
Bloco de código |
---|
subject=CN=web.conftpp.directory.openbankingbrasil.org.br,UID=bc97b8f0-cae0-4f2f-9978-d93f0e56a833,organizationIdentifier=OFBBR-d7384bd0-842f-43c5-be02-9d2b2d5efc2c,L=Sao Paulo,ST=SP,O=Chicago Advisory Partners,C=BR,serialNumber=43142666000197,jurisdictionC=BR,businessCategory=Private Organization |
9.4. Relative Distinguished Name (RDN) usando OID - ANS.1:
Bloco de código |
---|
subject=2.5.4.3=#0C2E7765622E636F6E667470702E6469726563746F72792E6F70656E62616E6B696E6762726173696C2E6F72672E6272,0.9.2342.19200300.100.1.1=#0C2462633937623866302D636165302D346632662D393937382D643933663065353661383333,2.5.4.97=#0C2A4F464242522D64373338346264302D383432662D343363352D626530322D396432623264356566633263,2.5.4.7=#0C0953616F205061756C6F,2.5.4.8=#0C025350,2.5.4.10=#0C194368696361676F2041647669736F727920506172746E657273,2.5.4.6=#13024252,2.5.4.5=#130E3433313432363636303030313937,1.3.6.1.4.1.311.60.2.1.3=#13024252,2.5.4.15=#0C1450726976617465204F7267616E697A6174696F6E |
9.5. Subject DN em RDN - Conforme RFC4514 - Padrão do Ecossistema Open Finance Brasil:
Bloco de código |
---|
CN=web.conftpp.directory.openbankingbrasil.org.br,UID=bc97b8f0-cae0-4f2f-9978-d93f0e56a833,2.5.4.97=#0c2a4f464242522d64373338346264302d383432662d343363352d626530322d396432623264356566633263,L=Sao Paulo,ST=SP,O=Chicago Advisory Partners,C=BR,2.5.4.5=#130e3433313432363636303030313937,1.3.6.1.4.1.311.60.2.1.3=#13024252,2.5.4.15=#0c1450726976617465204f7267616e697a6174696f6e |
9.6. Tabela com RDN e detalhamento dos OIDs e Codificações.
Ordem no RDN | OID | Atributo | ASN.1 - Bit String | Codificação |
---|---|---|---|---|
1 | 2.5.4.3 | CN | #0C | UTF8 |
2 | 0.9.2342.19200300.100.1.1 | UID | #0C | UTF8 |
3 | 2.5.4.97 | organizationIdentifier | #0C | UTF8 |
4 | 2.5.4.7 | L | #0C | UTF8 |
5 | 2.5.4.8 | ST | #0C | UTF8 |
6 | 2.5.4.10 | O | #0C | UTF8 |
7 | 2.5.4.6 | C | #13 | PrintableString |
8 | 2.5.4.5 | serialNumber | #13 | PrintableString |
9 | 1.3.6.1.4.1.311.60.2.1.3 | jurisdictionCountryName | #13 | PrintableString |
10 | 2.5.4.15 | businessCategory | #0C | UTF8 |