3. Consumindo Utilizando 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.3
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
01/12/2004
1.3
Adequação de Texto as sugestões da Área de Negócio
DEINF – Gilmar Santos
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Autor
Versão: 1.2
Data: 19/11/2004
Página 2 de 18
Sumário
1.
2.
Consulta da Posição de Clientes
4
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
1.9
1.10
4
4
4
4
4
4
5
5
6
6
6
6
6
Regras de Negócio Específicas
6
2.1
2.2
6
6
6
6
6
6
7
7
7
8
8
8
8
2.3
2.4
2.5
2.6
2.7
2.8
2.9
3.
4.
5.
Breve Descrição
Atores
Aplicativo da IF.
Pré-condições
Fluxo de Eventos
Fluxo Básico
Fluxos Alternativos
Exceções
Pós-condições
De acordo com o tipo de arquivo gerado:
1.10.1 Informações solicitadas retornadas ao aplicativo da IF
1.10.2 Log de Consulta de Clientes atualizado
1.10.3 Informações para cobrança registradas
(RN01) Parâmetros a serem informados pelas IF's
(RN02) Critérios para os campos informados pela IF
2.2.1 Campo Tipo de Cliente
2.2.2 Campo Código de Cliente
2.2.3 Campo Data-base
2.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
(RN04) Critério para verificar se a data-base está disponível para consulta
(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 para Tarifação
(RN09) Datas-Base
Utilizando Web Services
8
3.1
O documento WSDL
3.1.1 Acesso ao documento WSDL
3.2
Acesso ao Web Service
3.2.1 Estrutura da URL
3.2.2 O Protocolo HTTPS
8
9
9
9
9
Clientes Java Stand-alone
9
4.1
Suporte a SSL (JSSE)
4.1.1 Configurando o JSSE em JVMs 1.3
4.1.2 Reconhecendo o Protocolo HTTPS
4.2
Certificados Digitais
4.2.1 Certificados e o Utilitário "keytool"
4.3
Autenticação
4.4
Possíveis Erros
9
10
10
10
11
13
14
Clientes J2EE
15
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 3 de 18
5.1.1 JBoss 3.2.x
5.1.2 WebSphere 5.x
6.
7.
15
16
Clientes .NET
17
6.1
6.2
6.3
17
17
18
Importando os certificados
Importando o WSDL
Observações adicionais
Observações Finais
18
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.
1.2
Atores
1.3
Aplicativo da IF.
1.4
Pré-condições
Não há.
1.5
Fluxo de Eventos
1.6
Fluxo Básico
(P01) Este caso de uso começa quando o aplicativo de uma determinada IF efetua uma consulta ao SCR de
um determinado cliente no SFN para uma 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 formatados adequadamente [RN02] [E01] [E05]
[E06] [E07]
(P02.3) Verifica se a IF está habilitada a efetuar a consulta[RN03] [E02]
(P02.4) Verifica se a data-base indicada está disponível para consulta [RN04] [RN09] [E03] [E08]
(P02.5) Monta a estrutura de dados de retorno.[RN05] [RN06] [E04]
(P02.6) Atualiza o log de consulta a clientes[RN07]
(P03) O sistema efetiva o registro para fins de Tarifação [RN08] [Include: UC09 – Registro de Serviço
SCR - Sistema de Informações de Crédito
Versão: 1.2
Manual de Utilização do Web Services
Data: 19/11/2004
841066416
Página 4 de 18
para fins de Tarifação]
(P04) O caso de uso termina quando conclui o processo de consulta.
1.7
Fluxos Alternativos
Não identificados.
1.8
Exceções
(E01) Tipo de Cliente Inválido
Caso o tipo de cliente seja inválido, o sistema deverá enviar a seguinte mensagem : ' 57 - Tipo de
Cliente informado inválido: tipo_cliente'.
(E02) IF não habilitada para Consulta
Se a IF não estiver habilitada para a consulta, o sistema deverá enviar a seguinte mensagem : '52 Data-base indisponível para a Instituição Financeira'.
(E03) Data-Base Indisponível para Consulta
Caso a Data-base não esteja disponivel para a IF o sistema enviará a seguinte mensagem: ’52 Data-base indisponível para a Instituição Financeira’.
(E04)
O Cliente não possui dados no SCR
Caso o cliente consultado não possua operação no SFN na data-base solicitada o sistema deverá
enviar a seguinte mensagem: ’50 - Cliente não possui dados na data-base consultada’.
(E05)
Campo data-base não formatado corretamente
Caso o campo data-base não esteja formatado corretamente, não podendo ser interpretado como
mês e ano válidos, o sistema irá enviar a mensagem: ' 54 - Data-base não formatada (AAAA-MM)
ou não é válida’.
(E06)
Campo código do cliente inválido
Se o código informado não estiver adequado ao tipo de cliente, o sistema deve enviar uma das
seguintes mensagens: ’55 - CPF inválido: código_cliente’ ou ’56 - CNPJ inválido: código_cliente’.
(E07)
Campos requeridos não informados
Se um dos campos requeridos não for informado, o sistema deverá enviar as seguintes mensagens,
respectivamente: ’60 - Data-base não informada: campo obrigatório’, ’58 - Código do cliente não
informado: campo obrigatório’, ’59 - Tipo do cliente não informado: campo obrigatório’.
(E08)
Data-Base Consultada fora do período
Caso a database consultada esteja fora do período permitido, o sistema deverá enviar a seguinte
mensagem: ’51 – Data-base indisponível para consulta’.
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 5 de 18
1.9
Pós-condições
1.10
De acordo com o tipo de arquivo gerado:
1.10.1
Informações solicitadas retornadas ao aplicativo da IF
1.10.2
Log de Consulta de Clientes atualizado
1.10.3 Informações para cobrança registradas
2.
Regras de Negócio Específicas
2.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')
2.2
(RN02) Critérios para os campos informados pela IF
2.2.1
Campo Tipo de Cliente
O campo Tipo de Cliente 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. [E01]
2.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 : [E06]
a. Tipo de Cliente = 1 (Pessoa Física) : Código do Cliente de 11 dígitos (CPF)
b. Tipo de Cliente = 2 (Pessoa Jurídica) : Código do Cliente de 8 dígitos (CNPJ)
2.2.3
Campo Data-base
O campo Data-base deverá estar no formato ano/mês ('AAAA-MM'). [E05]
2.2.4
Tratamento para os campos não informados
Os campos que devem ser obrigatoriamente informados para realização do serviço são: Data-base, Código
do Cliente, Tipo do Cliente. [E07]
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 6 de 18
2.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'.
2.4
(RN04) Critério para verificar se a data-base está disponível para consulta
A data-base requisitada deverá estar dentro do período parametrizado para consulta, que corresponde
atualmente as 14 datas-base anteriores ao mês corrente.
Por exemplo: considerando que o mês corrente seja Julho/2004, o período parametrizado será de Maio/2003 a
Junho/2004 (14 datas-base).
2.5
(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á processada (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 à
moeda estrangeira. Somente serão informados códigos de vencimento cujos valores sejam maiores que
zero.
As modalidades a serem consideradas são as descritas no “Anexo 3: Modalidade de Operação – Mod” do
leiaute.
A vinculação à moeda estrangeira a ser considerada é a descrita no “Anexo 18: Vinculação à Moeda
Estrangeira – VincME” do leiaute. O campo Vinculação à Moeda Estrangeira por não ser informado no
Doc3020 deverá ter seu conteúdo deduzido do campo Variação Cambial (“Anexo 6: Variação Cambial –
VarCamb”) constante daquele documento. 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 “Anexo 1: Código de Vencimento -
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 7 de 18
CodVenc”.
Os campos referentes à operação sub judice somente serão listados caso o cliente possua operações que
estejam nessa situação.
2.6
(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.
2.7
(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)
2.8
(RN08) Registro de informações para Tarifação
Caso a consulta resulte em erro e não tenha sido enviada nenhuma informação, não haverá registro para
cobrança. No entanto, se a consulta não incorrer em erro e o cliente não possuir operação a ser informado
(RN06 e RN07) o registro para cobrança será efetuado.
2.9
(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”.
3.
Utilizando Web Services
3.1
O documento WSDL
Todo web service é descrito por um documento WSDL (Web Service Definition Language). Este
documento descreve todos 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 Bacen 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, caberá
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 8 de 18
à IDE 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.
3.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/
3.2
Acesso ao Web Service
3.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
3.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
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.
"6Clientes .NET"). Para clientes Java/J2EE (v. "4Clientes 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).
4.
Clientes Java Stand-alone
Aplicações Java stand-alone podem decerto utilizar web services. Em teoria, qualquer aplicação que seja
capaz de produzir um request HTTP poderia ser capaz de utilizar 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.
4.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
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 9 de 18
produto para certificar-se de 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.
4.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());
É 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.
4.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");
4.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:
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 10 de 18
Figura 1 - Certificado inválido
Pressionando-se o botão ‘Exibir certificado’ será exibida uma descrição mais detalhada do problema:
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 reconhecer 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.
4.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
1
Os certificados do SERPRO também podem ser baixados e instalados diretamente do site
https://thor.serpro.gov.br/ACSERPROSPB.
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 11 de 18
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"):
Figura 3 - Caminho de certificação
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
841066416
Versão: 1.2
Data: 19/11/2004
Página 12 de 18
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
que efetivamente estará sendo utilizada.
Figura 5 - Importando certificados para a JVM
4.3
Autenticação
Web services também podem demandar autenticação de seus usuários. Neste caso, como o cliente
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 13 de 18
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.
4.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
841066416
Versão: 1.2
Data: 19/11/2004
Página 14 de 18
5.
Clientes J2EE
O caso de uso mais comum para um web service do Bacen 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.
5.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
841066416
Versão: 1.2
Data: 19/11/2004
Página 15 de 18
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").
5.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
841066416
Versão: 1.2
Data: 19/11/2004
Página 16 de 18
6.
Clientes .NET
6.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".
6.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
841066416
Versão: 1.2
Data: 19/11/2004
Página 17 de 18
6.3
Observações adicionais
Embora a documentação fornecida dos web services implementados pelo Bacen tenha tipicamente a sintaxe
Java, trata-se apenas de exemplos que ilustram o uso.
7.
Observações Finais
O uso de web services é ainda experimental. O Bacen conta com a ajuda das IFs envolvidas no processo
para que se alcance um resultado satisfatório.
O Bacen 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 Cláudio Ferreira (61-414-3640);
 André Carvalho (61-414-3537).
SCR - Sistema de Informações de Crédito
Manual de Utilização do Web Services
841066416
Versão: 1.2
Data: 19/11/2004
Página 18 de 18