7. Consumindo Web Services

SCR – Sistema de Informações de Crédito
Manual de Utilização de Web Services: UC19 Consultar Informações de Cliente no SFN por meio de
Web Service
Versão 1.2
Histórico de Revisão
Data
Versão
Descrição
19/10/2004
1.0
Manual de Utilização de Web Services
DEINF - Gilmar Santos
09/11/2004
1.1
Alteração do prefixo do usuário virtual
DEINF – Gilmar Santos
19/11/2004
1.2
Esclarecimento para Keystore da configuração do
certificado
DEINF – Gilmar Santos
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Autor
Versão: 1.2
Data: 19/11/2004
Página 2 de 20
Sumário
1.
2.
Consulta da Posição de Clientes
4
1.1
4
Atores
2.1
3.
4.
5.
6.
Aplicativo da IF.
4
4
3.1
Para utilização do Caso de Uso: UC19 – Consultar Informações de Cliente no SFN por meio
de WebService:

O usuário deverá está cadastrado no serviço WSCR0001 no sistema AUTRAN do Bacen;

O usuário virtual deverá ter o prefixo ‘s_’.
4
4
4
Fluxo de Eventos
4
4.1
4
Fluxo Básico
Pós-condições
5
5.1
5
5
5
5
De acordo com o tipo de arquivo gerado:
5.1.1 Informações solicitadas retornadas ao aplicativo da IF,
5.1.2 Log de Consulta de Clientes atualizado e
5.1.3 Informações para cobrança registradas
Regras de Negócio Específicas
6.3
6.4
6.5
6.6
6.7
6.8
8.
4
Pré-Condições
6.1
6.2
7.
Breve Descrição
5
(RN01) Parâmetros a serem informados pelas IF's
(RN02) Critérios para os campos informados pela IF
6.2.1 Campo Tipo de Pessoa
6.2.2 Campo Código de Cliente
6.2.3 Campo Data-base
6.2.4 Tratamento para os campos não informados
(RN03) Critério para verificar se a If está habilitada a consultar a data-base solicitada
(RN05) Informações a serem retornadas por consulta
(RN06) Dados alterados por Decisão Judicial ou Vícios de Contrato
(RN07) Atualização do log de consulta a clientes
(RN08) Registro de informações de cobrança
(RN09) Datas-Base
5
5
5
5
6
6
6
6
10
10
10
11
Consumindo Web Services
11
7.1
O documento WSDL
7.1.1 Acesso ao documento WSDL
7.2
Acesso ao Web Service
7.2.1 Estrutura da URL
7.2.2 O Protocolo HTTPS
11
11
11
11
11
Clientes Java Stand-alone
12
8.1
12
12
13
Suporte a SSL (JSSE)
8.1.1 Configurando o JSSE em JVMs 1.3
8.1.2 Reconhecendo o Protocolo HTTPS
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 3 de 20
9.
8.2
Certificados Digitais
8.2.1 Certificados e o Utilitário "keytool"
8.3
Autenticação
8.4
Possíveis Erros
13
14
16
16
Clientes J2EE
17
10.
10.1
10.2
10.3
11.
9.1.1 JBoss 3.2.x
9.1.2 WebSphere 5.x
17
18
Clientes .NET
19
Importando os certificados
Importando o WSDL
Observações adicionais
Observações Finais
19
19
20
20
Manual de Utilização de Web Services: UC19 Consultar Informações de Cliente no SFN por meio de
Web Services
1.
Consulta da Posição de Clientes
1.1
Breve Descrição
Possibilita às Instituições Financeiras consultarem informações no SCR de Clientes no SFN utilizando o
recurso Web Service como forma de acesso.
Cada consulta efetuada por uma IF será referente a um único cliente e a uma única data-base.
2.
Atores
2.1
Aplicativo da IF.
3.
Pré-Condições
3.1
Para utilização do Caso de Uso: UC19 – Consultar Informações de Cliente no SFN por meio de Web
Services:

O usuário deverá está cadastrado no serviço WSCR0001 no sistema AUTRAN do Bacen;

O usuário virtual deverá ter o prefixo ‘s-.
4.
Fluxo de Eventos
4.1
Fluxo Básico
(P01) Este caso de uso começa quando o aplicativo de uma determinada IF efetua uma consulta ao SCR de
SCR - Sistema de Informações de Crédito
Versão: 1.2
Manual de Utilização do Web Services
Data: 19/11/2004
769908663
Página 4 de 20
um determinado cliente no SFN para uma determinada data-base. [RN01]
(P02) Para cada consulta, o sistema do Bacen, efetua todos os passos abaixo :
(P02.1) Lê os parâmetros da consulta informados pela IF
(P02.2) Verifica se os parâmetros são válidos e, se estão, formatados adequadamente [RN02]
(P02.3) Verifica se a IF está habilitada a efetuar consulta[RN03]
(P02.4) Verifica se a data-base indicada está disponível para consulta [RN09]
(P02.5) Monta a estrutura de dados de retorno.[RN05] [RN06]
(P02.6) Atualiza o log de consulta a clientes[RN07]
(P03) O caso de uso termina quando o sistema efetua o Registro de Informações de Cobrança. [RN08]
5.
Pós-condições
5.1
De acordo com o tipo de arquivo gerado:
5.1.1
Informações solicitadas retornadas ao aplicativo da IF,
5.1.2
Log de Consulta de Clientes atualizado e
5.1.3
Informações para cobrança registradas
6.
Regras de Negócio Específicas
6.1
(RN01) Parâmetros a serem informados pelas IF's
As IF's deverão informar os seguintes parâmetros para cada consulta efetuada :
- Código do Cliente consultado (CNPJ / CPF)
- Tipo do Cliente (1 ou 2)
- Data-base a ser consultada ('AAAA-MM')
6.2
(RN02) Critérios para os campos informados pela IF
6.2.1
Campo Tipo de Pessoa
O campo Tipo de Pessoa deverá ser composto por 1 dígito numérico, sendo válidos apenas os valores '1'
para Pessoa Física com CPF e '2' para Pessoa Jurídica com CNPJ. Caso estas condições não sejam
atendidas deverá ser enviada a mensagem : ' Tipo de Cliente informado inválido: tipo_cliente'
6.2.2
Campo Código de Cliente
O Código do Cliente deverá ser composto por 8 ou 11 dígitos numéricos e deverá está formatado conforme
a definição abaixo :
a.
Tipo de Pessoa = 1 (Pessoa Física) : Código do Cliente de 11 dígitos (CPF)
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 5 de 20
b.
Tipo de Pessoa = 2 (Pessoa Jurídica) : Código do Cliente de 8 dígitos (CNPJ)
Se o código informado não estiver adequado ao tipo de pessoa, conforme a definição acima, o sistema deve
enviar uma das seguintes mensagens: ‘CPF inválido: código_cliente’ ou ‘CNPJ inválido: código_cliente’.
6.2.3
Campo Data-base
O campo Data-base deverá estar no formato ano/mês ('AAAA-MM').
Caso o campo não esteja formatado corretamente e não puder ser interpretado como um mês válido, o
sistema irá enviar a mensagem: ' Data-base : formato inválido'.
6.2.4
Tratamento para os campos não informados
Se um dos campos não for informado deverá ser enviada a mensagem correspondente ao campo em
questão. A mensagem a ser enviada: ' Tipo de Cliente : informação obrigatória' ou ' Código de Cliente:
informação obrigatória' ou 'Data-base : informação obrigatória'.
6.3
(RN03) Critério para verificar se a If está habilitada a consultar a data-base solicitada
As informações serão fornecidas apenas se o status da IF na data-base requisitada para o Doc3020 for
“Disponível Externamente” ou 'Dispensada'.
Se a condição acima não for satisfeita deverá ser enviada a seguinte mensagem : 'Data-base indisponível
para a Instituição Financeira' .
6.4
(RN05) Informações a serem retornadas por consulta
Para cada consulta, serão retornadas as seguintes informações:
- Código do cliente
- Tipo do cliente
- Data-base
% dos documentos 3020 esperados para a data-base e que já foram processados
(desconsiderando as IF’s Dispensadas)
- % do volume esperado para a data-base e que já está processado (desconsiderando as IF’s
Dispensadas)
- Quantidade de operações do cliente no SFN
- Quantidade de IFs nas quais o cliente possui operações
- Quantidade de operações sub judice
- Responsabilidade total de operações sub judice
- O valor correspondente a cada código de vencimento para cada:
o Modalidade de operação
o Vinculação à moeda estrangeira
O valor de cada código de vencimento a ser informado é dado pelo somatório de todas as operações de
cliente, consolidadas ou individualizadas, que tiverem a mesma modalidade/submodalidade e vinculação à
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 6 de 20
moeda estrangeira. Somente serão informados códigos de vencimento cujos valores sejam maiores que
zero.
As modalidades a serem consideradas estão descritas no leiaute a seguir:
Layout 1: Modalidade Operação - Mod
Domínio Abreviação (40)
01
Adiantamento à depositante
02
Empréstimos
03
Títulos descontados
04
Financiamentos
05
Fin à exportação
06
Fin à importação
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Sub
00
01
00
01
02
03
04
05
06
07
08
09
90
99
00
01
02
03
99
00
01
02
03
04
05
90
99
00
01
02
03
04
90
99
00
01
90
00
01
Abreviação (40)
Adiantamento à depositante
Adiant depos - adiantamento
Empréstimos
Emp - chq especial ou cta garant
Emp - pessoal com consignação
Emp - pessoal sem consignação
Emp - vinculado a cartão crédito
Emp - cap giro inferior 30d
Emp - cap giro igual ou super 30d
Emp - vendor
Emp - compror
Emp - ARO
Emp - financ projeto
Emp - outros
Títulos Descontados
Tít Desc - duplicatas
Tít Desc - cheques
Tít Desc - fatura cartão crédito
Tít Desc - outros
Financiamentos
Financ - veículos autom
Financ - outros bens
Financ - microcrédito
Financ - vendor
Financ - compror
Financ - financ projeto
Financ - outros
Fin à exportação
Fin Export - financ à export
Fin Export - ACC
Fin Export - ACE
Fin Export - export note
Fin Export - financ projeto
Fin Export - outros
Fin à importação
Fin Import - financ à importação
Fin Import - financ projeto
Fin com interveniência
Fin Interv - veículos automotores
Versão: 1.2
Data: 19/11/2004
Página 7 de 20
07
Fin com interveniência
08
Fin rural e agroind
09
Fin imobiliários
10
Fin TVM
11
Fin infra-estr e desenv
12
Op. de arrendamento
13
Outros créditos
14
Repasses interfinanceiros
15
Coobrigações
16
Créditos a liberar
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
02
90
99
00
01
02
03
90
00
01
02
03
90
00
01
00
01
90
00
01
02
03
04
90
00
01
02
03
90
99
00
01
00
01
02
03
11
12
90
99
00
01
02
90
99
Fin Interv - outros bens
Fin Interv - financ projeto
Fin Interv - outros
Fin Rural e Agroind
Fin Rural - custeio
Fin Rural - investimento
Fin Rural - comercialização
Fin Rural - financ projeto
Fin Imobiliários
Fin Imob - SFH
Fin Imob - carteira hipotecária
Fin Imob - empreendimentos
Fin Imob - financ projeto
Fin TVM
Fin TVM - finaciamento de TVM
Fin Infra-Estr e Desenv
Fin Infra-Estr - financ
Fin Infra-Estr - financ projeto
Op. de Arrendamento
Arrend - financeiro
Arrend - financeiro imobiliário
Arrend - subarrendamento
Arrend - financeiro vinculado
Arrend - financ projeto
Outros créditos
Outros - avais e fianças honrados
Outros - devedor compra de bens
Outros - títulos e créditos a receb
Outros - financ projeto
Outros - com característica créd
Repasses interfinanceiros
Repasses interfinanceiros - repasses
Coobrigações
Coobrig - beneficiário PJ financ
Coobrig - beneficiário outras pess
Coobrig - fundos constitucionais
Coobrig - cessão a PJ financ
Coobrig - cessão a outras pess
Coobrig - financ projeto
Coobrig - outras
Créditos a liberar
Créd liberar - SFH
Créd liberar - crédito rotativo
Créd liberar - financ projeto
Créd liberar - outros
Versão: 1.2
Data: 19/11/2004
Página 8 de 20
17
Operações vinculadas
50
Créditos baixados como prejuízo
01 Op. Vinculadas - op. de crédito
00 Não informada
01 Não informada
A vinculação à moeda estrangeira a ser considerada é a descrita no leiaute a seguir:
Layout 02: Vinculação à Moeda Estrangeira - VincME
Domínio
S
N
Sim
Não
O campo Vinculação à Moeda Estrangeira por não ser informado no Doc3020 deverá ter seu conteúdo deduzido do
campo Variação Cambial, segundo o modelo a seguir:
Layout 3: Variação Cambial - VarCamb
Domínio
220
425
470
540
978
999
Abreviação (40)
Dólar
Franco
Iene
Libra
Euro
Outras
Assim, quando existir variação cambial, o campo Vinculação à Moeda Estrangeira será informado com valor "Sim".
Caso contrário (não existir valor cambial) esse campo não será informado.
Os códigos de vencimentos a serem considerados são os descritos no documento a seguir:
Layout 4: Código do Vencimento - CodVenc
Domínio
110
120
130
140
150
160
165
170
175
180
190
199
Abreviação (40)
a vencer até 30d
a vencer 31 a 60d
a vencer 61 a 90d
a vencer 91 a 180d
a vencer 181 a 360d
a vencer 361 a 720d
a vencer 721 a 1080d
a vencer 1081 a 1440d
a vencer 1441 a 1800d
a vencer 1801 a 5400d
a vencer acima de 5400d
a vencer indeterminado
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 9 de 20
205
210
220
230
240
245
250
255
260
270
280
290
310
320
vencido 1 a 14d
vencido 15 a 30d
vencido 31 a 60d
vencido 61 a 90d
vencido 91 a 120d
vencido 121 a 150d
vencido 151 a 180d
vencido 181 a 240d
vencido 241 a 300d
vencido 301 a 360d
vencido 361 a 540d
vencido acima de 540d
baixado até 12m
baixado de 12m a 48m
Caso o cliente consultado não possua operação no SFN na data-base solicitada será retornada apenas a
Data-base consultada, o Código e o Tipo do Cliente.
Os campos referentes à operação sub judice somente serão listados caso o cliente possua operações que
estejam nessa situação.
6.5
(RN06) Dados alterados por Decisão Judicial ou Vícios de Contrato
As “operações excluídas por determinação judicial” e as “operações excluídas por vícios de contrato” não
serão consideradas nas informações a serem retornadas.
As informações de uma IF referentes a um “cliente excluído por determinação judicial” ou referentes a um
cliente com todas as operações excluídas, seja por determinação judicial, seja por vícios de contrato, não
serão consideradas. Caso o cliente possua exclusivamente operações na referida IF, será considerado
cliente sem operação no SFN na data-base solicitada.
Para as “operações marcadas sub judice”, devem ser considerados normalmente os valores das operações.
6.6
(RN07) Atualização do log de consulta a clientes
- Data e hora do processamento
- Código do Cliente consultado (CNPJ / CPF)
- Tipo do Cliente (1 ou 2)
- CNPJ da IF Solicitante
- Tipo da consulta (consulta Web Service = 'S')
- Operador Solicitante (o código sisbacen do operador logado, é o mesmo da IF solicitante).
6.7
(RN08) Registro de informações de cobrança
As informações serão registradas, por consulta realizada, para cobrança futura.
Caso a consulta resulte em erro e não tenha sido enviada nenhuma informação, não haverá registro para
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 10 de 20
cobrança. No entanto, se a consulta não incorrer em erro e o cliente não possuir operação a ser informada
(RN06 e RN07) o registro para cobrança será efetuado.
6.8
(RN09) Datas-Base
As informações serão fornecidas apenas se o status da IF na data-base requisitada para o Doc3020 for
“Disponível Externamente” ou “Dispensada”.
Se a condição acima não for satisfeita deverá ser enviada a seguinte mensagem: ‘Data-base indisponível
para a Instituição Financeira’.
7.
Consumindo Web Services
7.1
O documento WSDL
Todo web service é descrito por um documento WSDL (Web Service Definition Language). Este
documento descreve todas os serviços, seus parâmetros de entrada e saída e até mesmo a estrutura de dados destes
parâmetros caso esta seja complexa.
O documento WSDL sempre estará disponível através de um link ou no site do BC ou na própria aplicação
web provedora do web service:
O documento WSDL deve ser utilizado pelos desenvolvedores das aplicações que consomem os web
services para a geração de stubs de comunicação através de uma IDE apropriada. Uma IDE tipicamente irá analisar
o WSDL e produzir código que implemente a comunicação de rede para invocação dos serviços. Mais ainda, a IDE
caberá também reproduzir, na linguagem de programação em questão, as estruturas de dados necessárias para
representar os parâmetros de entrada e saída do web service.
7.1.1
Acesso ao documento WSDL
As URLs para acesso ao documento WSDL em homologação e em produção são obtidas através dos
seguintes links, respectivamente:
Homologação: https://www3.bcb.gov.br/hml/wsscr/ e
Produção: https://www3.bcb.gov.br/wsscr/ - a partir do momento em que o sistema esteja disponibilizado
em produção.
7.2
Acesso ao Web Service
7.2.1
Estrutura da URL
O stub gerado pela importação do WSDL inclui uma URL de acesso ao web service. Embora esta URL
certamente possa ser manipulada após a geração do stub é preciso lembrar que ela deve obviamente representar um
caminho que possa alcançar o servidor web que hospeda o web service.
As URLs para acesso ao web services em homologação e em produção são as seguintes:
Homologação: https://www3.bcb.gov.br/hml/wsscr/services/ControleCliente e
Produção: https://www3.bcb.gov.br/wsscr/services/ControleCliente - a partir do momento em que o sistema
esteja disponibilizado na produção
7.2.2
O Protocolo HTTPS
Quando as requisições SOAP trafegam pela rede o seu conteúdo - texto XML - poderia ser observado por
terceiros. Embora existam diversas propostas para se impor segurança por criptografia em mensagens SOAP, a
arquitetura mais simples consiste em delegar esta tarefa ao transporte da mensagem, utilizando-se HTTPS no lugar
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 11 de 20
de HTTP.
Quando o web service estiver disponível apenas via HTTPS há que se observar que o reconhecimento das
autoridades emissoras dos certificados digitais dos servidores é pré-requisito para o funcionamento das aplicações
clientes. Para clientes .NET a instalação dos certificados digitais pode ser feita diretamente pelo browser (v.
"10Clientes .NET"). Para clientes Java/J2EE (v. "8Clientes Java"), a instalação dos certificados digitais deve ser
feita pela ferramenta de linha de comando keytool (ou, antes ainda, em JVMs 1.3 talvez seja necessário instalar o
pacote JSSE da Sun).
8.
Clientes Java Stand-alone
Aplicações Java stand-alone podem decerto consumir web services. Em teoria, qualquer aplicação que seja
capaz de produzir um request HTTP poderia ser capaz de consumir web services. Todavia produzir manualmente
uma requisição SOAP é um trabalho braçal impraticável; tais documentos XML são extensos e de sintaxe não
trivial.
Felizmente hoje em dia qualquer IDE Java traz consigo assistentes para a criação de stubs Java a partir de
documentos WSDL, tornando a criação de clientes de web services simples e direta. Para os adeptos do mundo open
source, o Projeto Apache Web Services (http://ws.apache.org) possui uma implementação de SOAP bastante
evoluída: o Projeto Axis (http://ws.apache.org/axis). De fato, boa parte das implementações SOAP do mercado
baseiam-se no Axis.
8.1
Suporte a SSL (JSSE)
A JVM J2SE 1.3 original da Sun não incorpora suporte ao protocolo SSL (utilizado no HTTPS), sendo
necessária a instalação do pacote opcional JSSE (Java Secure Socket Extension). O JSSE pode ser baixado do site da
Sun (http://java.sun.com/products/jsse).
JVMs 1.3 que acompanham a instalação de produtos de terceiros (ex: JVM 1.3 da IBM que acompanha o
WebSphere 5.0) possivelmente já trazem consigo o próprio pacote JSSE da Sun ou alguma extensão do mesmo,
sendo portanto desnecessária sua instalação. O administrador (ou desenvolvedor) deve consultar a documentação do
produto para certificar-se que esta instalação se faz necessária. Uma maneira alternativa é simplesmente inspecionar
a pasta [JAVA_HOME]/jre/lib/ext e procurar pelo arquivo "jsse.jar" (ou "*jsse.jar") - sua existência é uma indicação
de que o JSSE (ou extensão semelhante) foi instalado.
Por outro lado JVMs 1.4 já incluem o JSSE, sendo desnecessária sua instalação manual. É preciso lembrar
que não importa qual é a versão de JVM em que executam os servidores que implementam os web services (de fato
tampouco é relevante se estes foram desenvolvidos em Java ou não). Assim sendo, aplicações cliente stand-alone
escritas em Java teriam uma instalação mais simples caso rodem sobre JVMs 1.4.
8.1.1
Configurando o JSSE em JVMs 1.3
Este tópico diz respeito apenas a JVMs 1.3. Usuários de JVMs 1.4 podem seguir diretamente para o tópico
seguinte. Usuários de JVMs 1.3 devem verificar se a instalação do JSSE é realmente necessária antes de fazê-la.
Basicamente a instalação do JSSE traduz-se na cópia de alguns JARs para a pasta de extensão da JVM
([JAVA_HOME]/jre/lib/ext). Além da cópia destes arquivos, é sugerido que seja feita a inclusão de uma linha na
configuração de segurança da JVM (arquivo "([JAVA_HOME]/jre/lib/security/java.security") para que seja
registrado o provedor de criptografia SSL:
security.provider.X=com.sun.net.ssl.internal.ssl.Provider
Note que "X" é o próximo inteiro livre na seqüência de provedores enumerados. Se esta configuração
estática não for feita, ainda assim a aplicação pode realizar este registro dinamicamente em tempo de execução:
Security.addProvider((Provider)Class.forName(
"com.sun.net.ssl.internal.ssl.Provider").newInstance());
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 12 de 20
É bom lembrar que JARs copiados para a pasta de extensão supra-citada automaticamente estarão no
classpath de qualquer aplicação executada por esta JVM.
8.1.2
Reconhecendo o Protocolo HTTPS
Além do suporte à criptografia SSL, o suporte a um "novo" protocolo (HTTPS) deve ser configurado para
que o pacote java.net o reconheça. Trata-se aqui de uma simples variável de sistema ajustada pelo parâmetro "-D"
da JVM:
java -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol
Se esta configuração estática não for feita, ainda assim a aplicação pode ajustar esta variável de sistema em
tempo de execução:
System.setProperty("java.protocol.handler.pkgs",
"com.sun.net.ssl.internal.www.protocol");
8.2
Certificados Digitais
Toda conexão HTTPS pressupõe a existência de um certificado digital válido no servidor web com o qual a
conexão é estabelecida. Este certificado, por sua vez, foi emitido por uma autoridade certificadora, a qual também
deve ser considerada confiável.
Quando se navega em um site via HTTPS, o browser sempre nos alerta caso o certificado digital do mesmo
não seja considerado válido ou confiável. O exemplo abaixo se refere a um certificado cujo emissor não é
considerado confiável:
Figura 1 - Certificado inválido
Pressionando-se o botão ‘Exibir certificado’ será exibida uma descrição mais detalhada do problema:
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 13 de 20
Figura 2 - Exibição do certificado
Neste caso, é o certificado da autoridade certificadora (SERPRO) que não é considerado confiável pelo
browser. Há, nesta tela, a possibilidade de se instalar o certificado de forma que o browser passe a reconher o
SERPRO como uma autoridade confiável1.
Cabe observar que as telas (e procedimentos para exportação dos certificados para arquivos) que aqui
foram exibidas são as apresentadas pelo Internet Explorer. Todavia qualquer browser há de apresentar as mesmas
funcionalidades.
8.2.1
Certificados e o Utilitário "keytool"
Instalados no browser ou não, estes certificados devem ser gravados em arquivos locais para que possamos
importá-los para dentro do keystore da JVM. O keystore é, entre outras coisas, a ferramenta que gerencia os
repositórios de certificados de autoridades confiáveis. Fisicamente, o keystore é um arquivo binário cuja localização
default é "[JAVA_HOME]/jre/lib/security/cacerts", embora possa ser configurada para qualquer caminho de arquivo
pela propriedade de sistema "javax.net.ssl.trustStore".
Para manipular o keystore existe a ferramenta keytool. Para, por exemplo, listar todos os certificados e
chaves armazenadas no keytool basta digitar:
keytool -list -keystore [KEYSTORE]2 -storepass changeit
O certificado do servidor aceito pelo browser (veja figura abaixo) pode ser exportado para um arquivo
".cer". Este arquivo contém não apenas o certificado do servidor como também o da autoridade certificadora que o
emitiu (i.e. o "caminho de certificação"):
1
Os certificados do SERPRO também podem ser baixados e instalados diretamente do site
https://thor.serpro.gov.br/ACSERPROSPB.
2
Considere [KEYSTORE] = [JAVA_HOME]/jre/lib/security/cacerts. A senha padrão para o keystore do JDK da Sun é "changeit",
mas isto pode ser mudado pelo próprio keytool.
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 14 de 20
Figura 3 - Caminho de certificação
Figura 4 - Exportando o certificado
Pela opção "Copiar para arquivo..." pode ser gerado localmente um arquivo com o certificado (ex:
"C:\TEMP\bccert.cer").
Para importar para dentro do keystore os certificados das autoridades certificadoras basta portanto o
comando abaixo:
keytool -import -alias bccerts -file C:\TEMP\bccert.cer
-keystore [KEYSTORE] -storepass changeit
[KEYSTORE] = p. ex: C:\j2sdk1.4.2_03\jre\lib\security\cacerts; esse certificado deverá ser instalado para a JVM
SCR - Sistema de Informações de Crédito
Versão: 1.2
Manual de Utilização do Web Services
Data: 19/11/2004
769908663
Página 15 de 20
que efetivamente estará sendo utilizada.
Figura 5 - Importando certificados para a JVM
8.3
Autenticação
Web services também podem demandar autenticação de seus usuários. Neste caso, como o cliente
provavelmente é uma aplicação que executa de forma não assistida, a forma de autenticação é a clássica BASIC3, e
não um formulário HTML (o qual não faria sentido neste contexto).
Os objetos criados pelas IDEs para utilização do web service decerto terão métodos para o fornecimento de
login e senha. Portanto, as IFs farão uso de usuários virtuais para a autenticação em web services4.
8.4
Possíveis Erros
Os erros de execução mais comuns de aplicações Java stand-alone que consomem web services podem ser
explicados na lista abaixo:
"java.net.MalformedURLException: unknown protocol: https": o JSSE pode não estar instalado na
JVM que executa a aplicação, ou a propriedade de sistema "java.protocol.handler.pkgs" não foi ajustada;
"javax.net.ssl.SSLException: untrusted server cert chain" ou "javax.net.ssl.SSLHandshakeException:
bad certificate": os certificados digitais do servidor web apontado na URL não são válidos e/ou não estão
registrados no keystore.
3
Ao contrário do que geralmente se escuta, as formas BASIC e FORM são, na prática, igualmente inseguras - a não ser que
trafeguem sobre HTTPS, onde então ambas serão seguras.
4
O uso de certificados digitais que dispensem a autenticação por login e senha está previsto para o futuro.
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 16 de 20
9.
Clientes J2EE
O caso de uso mais comum para um web service do BC poderá ser, muito em breve, não o de uma
aplicação stand-alone (como uma aplicação batch, por exemplo), mas sim o de um componente acionado por uma
aplicação on-line disponibilizada pelas próprias IFs aos seus clientes e agências.
Neste caso, o cliente do web service é o próprio servidor de aplicações, o qual opera por definição de forma
não assistida. Em ambientes de maior complexidade o administrador deve atentar para a possibilidade de haver
diferentes máquinas executando cada uma diversas instâncias do servidor de aplicações (como nos ambientes
clusterizados). Isto significa que certos cuidados devem ser tomados: os keystores de todas as JVMs devem ser
mantidos idênticos, por exemplo, ou eventuais parâmetros de JVM devem ser fornecidos da maneira apropriada.
Sobretudo, deve ser previamente estudado o impacto destas mudanças no servidor J2EE.
O consumo de web services via HTTP a partir das aplicações que executam sobre um servidor J2EE não
exige a priori nenhuma configuração adicional no mesmo. Para o servidor de aplicações estes eventos são
transparentes. Contudo, se o acesso aos web services remotos se dá via HTTPS, devemos saber se o servidor J2EE (e
sua JVM) estão preparados para fazê-lo.
Todo servidor J2EE tem suas particularidades, e uma cuidadosa inspeção deve ser feita antes de se
modificar uma configuração global na JVM, como veremos.
9.1.1
JBoss 3.2.x
A instalação do JBoss 3.2.x não traz consigo nenhuma JVM – pressupõe-se que o administrador fez uma
instalação prévia de um JDK 1.3 ou superior. Para que uma aplicação que executa sobre o JBoss possa fazer
requisições HTTPS é necessário habilitar o protocolo HTTPS (v. “Reconhecendo o Protocolo HTTPS”) de uma
maneira que não afete o funcionamento normal do JBoss. É necessário também importar os certificados de
segurança para a JVM (v. “Certificados Digitais”).
O boot do JBoss 3.2.x já impõe um valor default para a propriedade "java.protocol.handler.pkgs" da JVM,
uma vez que este produto define um protocolo proprietário ("jnp://"). O ideal é que possamos acrescentar o
protocolo HTTPS aos protocolos com os quais o JBoss já sabe lidar.
Temos diversas maneiras de modificar esta configuração. A forma "padrão" ainda é acrescentar o
parâmetro "-D" na JVM, modificando o arquivo batch que executa o JBoss (arquivo "[JBOSS_HOME]/bin/run.bat"
em máquinas Windows). Neste batch é fácil localizar a linha de comando que dispara a JVM do servidor e
acrescentar a entrada "-D":
"%JAVA%" %JAVA_OPTS% -Djava.protocol.handler.pkgs=
com.sun.net.ssl.internal.www.protocol
-classpath "%JBOSS_CLASSPATH%" org.jboss.Main
No arquivo "boot.log" criado após levantar o JBoss pode ser vista a lista de protocol handler packages que
o mesmo agora reconhece:
07:10:02,656 DEBUG [ServerInfo]
java.protocol.handler.pkgs:
com.sun.net.ssl.internal.www.protocol|org.jboss.net.protocol
Note que o JBoss acrescentou também um handler modificando esta propriedade de sistema sem
sobrescrever o valor sugerido. Devemos proceder da mesma forma caso optemos por alterar esta configuração em
tempo de execução (e não via script):
String prop = System.getProperty("java.protocol.handler.pkgs");
if (prop == null)
prop = "com.sun.net.ssl.internal.www.protocol";
else if (prop.indexOf("com.sun.net.ssl.internal.www.protocol") < 0)
prop = prop + "|com.sun.net.ssl.internal.www.protocol";
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 17 de 20
System.setProperty("java.protocol.handler.pkgs",prop);
Ainda outra forma possível é acrescentar uma entrada no arquivo "properties-service.xml" (localizado na
pasta "[JBOSS_HOME]/server/default/deploy"), tomando o devido cuidado para não sobrescrever o valor que
sabemos ser o default:
<mbean code="org.jboss.varia.property.SystemPropertiesService"
name="jboss:type=Service,name=SystemProperties">
<attribute name="Properties">
…
java.protocol.handler.pkgs=org.jboss.net.protocol|
com.sun.net.ssl.internal.www.protocol
…
</attribute>
</mbean>
Qualquer uma destas três abordagens terá sucesso em habilitar o protocolo HTTPS. Note que o próprio
JBoss já traz consigo o pacote JSSE, não sendo necessário instalá-lo diretamente sobre a JVM.
A importação dos certificados, por sua vez, pode ser feita exatamente como descrito no capítulo anterior
(tópico "Certificados Digitais").
9.1.2
WebSphere 5.x
O WebSphere já vem configurado com o que é necessário para se estabelecer conexões HTTPS, não sendo
necessário nem instalar o JSSE nem tampouco fornecer qualquer propriedade de sistema.
A única coisa que deve ser feita é a importação dos certificados, a exemplo do capítulo anterior. A
localização default do keystore, porém, é diferente da default para JVMs, sendo no WebSphere o caminho
"[WAS_ROOT]/etc/DummyServerTrustFile.jks". O administrador deve verificar no console administrativo quais
são os keystores (ou mesmo apontar no console para outros keystores que tenha criado arbitrariamente com o
keytool).
O mesmo keytool apresentado no capítulo anterior deve ser utilizado para importar os certificados,
tomando cuidado para fornecer o caminho correto do keystore. A senha padrão no WebSphere para os keystores
criados na instalação do produto é "WebAS".
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 18 de 20
10.
Clientes .NET
10.1
Importando os certificados
Clientes .NET também exigem que os certificados tenham sido importados e registrados como confiáveis.
Isto pode ser feito a partir do próprio browser, na opção "Instalar certificado".
10.2
Importando o WSDL
Em uma aplicação (stand-alone ou web) deve ser criada uma web reference:
Figura 6 - Criando uma web reference
No passo seguinte deve ser fornecido o caminho para o documento WSDL (pode ser um caminho local para
onde foi feito um download do WSDL ou mesmo uma URL para o documento original):
Figura 7 - Importando o WSDL
Após este passo as classes de dados e o stub serão criados pelo próprio Visual Studio .NET, sendo sua
manipulação bastante simples.
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 19 de 20
10.3
Observações adicionais
Embora a documentação fornecida dos web services implementados pelo BC tenha tipicamente a sintaxe
Java, trata-se apenas de exemplos que ilustram o uso.
11.
Observações Finais
O uso de web services é ainda experimental. O BC conta com a ajuda das IFs envolvidas no processo para
que se alcance um resultado satisfatório.
O BC pode ser contatado pelas IFs para ajudá-las nesta fase inicial do desenvolvimento de suas próprias
aplicações-clientes.
Para dúvidas sobre o conteúdo e APIs dos web services do SCR, entrar em contato com:
 Suely Haruko Takahashi Iwamoto (61-414-3602);
 Henrique Claudio Ferreira (61-414-3640);
 André Carvalho (61-414-3537).
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
769908663
Versão: 1.2
Data: 19/11/2004
Página 20 de 20