1. Introdução¶

O objetivo deste documento é descrever o funcionamento da solução GBS PSBio, os principais componentes, modos de funcionamento, configurações e principais procedimentos. Note que a solução GBS PSBio, compreende os módulos SPID Client, Módulo AC e Módulo PSBio, os quais serão detalhados posteriormente.

Esse manual está atualizado para a versão 5.1.1 do PSBio

2. Arquitetura¶

2.1. Introdução¶

A solução completa do GBS PSBio é composta por 3 módulos principais: SPID Client, Módulo AC e Módulo PSBio (Prestador de Serviços Biométricos).

Os módulos serão mais detalhados nas seções seguintes, porém, basicamente as seguintes funcionalidades são atribuídas a cada módulo:

SPID Client

é responsável pela coleta biométrica, autenticação de operadores e geração de laudos de coleta biométrica.

Módulo AC

é responsável por receber as coletas biométricas advindas das estações de trabalho, acessar o Serviço de Geração de IDN e encaminhar ao PSBio. Além disso, o Módulo AC armazena também a Base de Imagens da Autoridade Certificadora e realiza o cadastro/exclusão de operadores.

Módulo PSBio

É responsável por executar as buscas biométricas e implementar as regras de negócios do PSBio.

É importante ressaltar que os Módulos AC e PSBio trabalham como uma camada de integração por cima do GBS Cluster, o ABIS (Automated Biometric Identification System) da Griaule.

2.2. SPID Client¶

SPID Client é o software responsável por:

Realizar as coletas biométricas (face e impressão digital)
Realizar o cadastro de operadores
Realizar a autenticação de operadores
Fazer geração de laudos de coleta biométrica.

2.2.1. Utilização¶

Consulte o Manual de Utilização do SPID Client para maiores detalhes sobre a utilização do SPID Client.

2.2.2. Coleta Biométrica¶

Durante a coleta biométrica, o SPID Client realiza verificação da qualidade das biometrias, captura as biometrias caso estejam dentro dos padrões de qualidade configurados e monta o pacote biométrico que será enviado ao Módulo AC.

2.2.3. Encriptação dos Dados¶

Os dados biométricos das consultas são encriptados e armazenados na máquina local em banco de dados H2, tanto para coletas realizadas em modo online como em modo offline.

Para isso, o software cliente de coleta biométrica (Griaule SPID Client) encripta o pacote de dados enviado ao servidor utilizando chave aleatória AES, a qual é encriptada com uma chave RSA.

No servidor, esse pacote de dados é desencriptado utilizando chave privada RSA. A chamada ao servidor será realizada utilizando canal seguro HTTPS sem a necessidade de certificado embutido no software de coleta.

2.2.4. Apontamento para Módulo AC¶

É possível configurar para qual Módulo AC se deseja apontar o SPID Client através de edição do arquivo C:\Griaule\SPID\conf\GBSSpid2.properties. Para realizar tal configuração o campo server.url deve ser configurado com a URL do Módulo AC:

# GBS Server connection
server.url=https://<hostname_modulo_AC>:8082/gbs-spid-server/service/cluster
server.username=admin
server.password=admin

2.2.5. Logs¶

Os logs da aplicação podem ser encontrados em C:\Griaule\SPID\log.

2.3. Módulo AC¶

O módulo AC é responsável por receber as transações advindas das estações de trabalho, fazer a substituição do CPF por IDN (através de acesso ao Serviço de Geração de IDN) e encaminhar as transações para o Módulo PSBio.

Detalhes de como configurar o apontamento para o PSBio e autenticação mútua HTTPS Módulo AC-PSBio são apresentados nos procedimentos descritos na seção Toolkits.

No Módulo AC, o pacote biométrico é aberto e são salvos os dados biométricos e biográficos dos requerentes e operadores. Neste módulo ficam armazenados as informações de biometrias, CPFs e IDNs.

Além de serem autenticados durante a coleta biométrica no SPID Client, as biometrias dos operadores também são autenticadas no Módulo AC quando a transação chega no servidor.

2.3.1. Painel de Controle¶

O módulo AC possui painel de controle, acessado através de usuário e senha, no qual é possível realizar as seguintes ações:

Consultar transações realizadas e o resultado de cada
Incluir / excluir operadores autorizados a fazer login no SPID Client.

Transações:

As transações são filtradas por:

Data inicial e Data final (todas as transações dentro do período serão exibidas)
Tipo de transação:
- Cadastro
- Pesquisa
- Atualizações
Status
CPF do Cliente
CPF do Operador

Cadastro de Operadores:

Os CPFs de operadores podem ser inseridos em lista ou individualmente através do campo de adição. Para inserção em lista, os CPFs devem ser separados por vírgula, espaço ou quebras de linha.

Os números podem ser inseridos no padrão com pontos e hífen ou corridos.

2.3.2. Configuração do Módulo AC: spid.yaml¶

O arquivo de configuração do funcionamento do Módulo AC é /etc/griaule/spid/properties/spid.yaml. Abaixo são descritas as principais propriedades:

spid:

authenticationEnabled: Define o uso de autenticação no SPID.

Valor Exemplo: false

caName: Common name do certificado utilizado.

Valor Exemplo: ac1.griaule.com

documentID: Documento usado como chave que é enviado ao sistema.

Valor Exemplo: documentID

decryptionKeyPath: Caminho para o arquivo com a chave de encriptação.

Valor Exemplo: /etc/griaule/spid/conf/data_private.key

operator:

deduplicate: Propriedade booleana (true ou false) que define se o cadastro de operador será realizado com ou sem deduplicação. Caso o Módulo AC não esteja funcionando em conjunto com Módulo PSBio, a deduplicação de operador (quando habilitada) é realizada contra toda a base de operadores e clientes. Caso o Módulo AC esteja funcionando em conjunto com Módulo PSBio, a deduplicação de operador (quando habilitada) é realizada contra a base de operadores presente no Módulo AC.

Valor Exemplo: false

hadoop:

zookeeperPath: Caminho para conexão com o zookeeper do servidor, necessário para comunicação com o banco de dados.

Valor Exemplo: localhost:2181

idn:

serviceUrl: Caminho do serviço de IDN.

Valor Exemplo: http://url:8081/gbs-spid-server/service/idn

gbds:

host: Caminho para o serviço do GBS Cluster que é consumido

Valor Exemplo: localhost

port: Porta para o serviço do GBS Cluster que é consumido

Valor Exemplo: 8085

useSSL: Define se o protolo de segurança deve ser usado na conexão com o GBDS

Valor Exemplo: false

authenticationEnabled: Uso de autenticação no GBDS

Valor Exemplo: false

authenticationExpiration: Tempo de expiração do token

Valor Exemplo: 600000

username: Usuário cadastrado no GBDS

Valor Exemplo: admin

password: Senha do usuário cadastrado no GBDS

Valor Exemplo: admin

psbio:

active: Define se o PSBIO está ativo ou não.

Valor Exemplo: true

name: Nome do PSBio que está conectado. O nome deve ser exatamente o mesmo nome presente no certificado enviado pelo PSBio.

Valor Exemplo: psbio.griaule.com

apiUrl: Caminho para a API do psbio server.

Valor Exemplo: https://url:8444/gbs-psbio-server/service/ac-api

hubUrl: Caminho para o HUB do psbio server.

Valor Exemplo: https://url:8444/gbs-psbio-server/service/hub

dirUrl: Caminho para o diretório do psbio server.

Valor Exemplo: https://url:8444/gbs-psbio-server/service/directory

spidx:

organizationName: Nome da Autoridade Certificadora

Valor Exemplo: ac1

organizationCallback: Callback de final de coleta do SPIDX

Valor Exemplo: callback

organizationHostname: Hostname da AC que será usada para o SPIDX notificar o SPID Server.

Valor Exemplo: ac1

host: Caminho para o serviço do SPIDX

Valor Exemplo: spidx

port: Porta para o serviço do SPIDX

Valor Exemplo: 8090

qualityThreshold: Limiar de qualidade de captura de impressões digitais

Valor Exemplo: 50

server:

port: Porta onde funcionará o painel de controle do PSBio sem uso de SSL. Caso seja usado TLS, o valor padrão da porta é 8444.

Valor Exemplo: 8082

ssl:

protocol: Protocolo de segurança a ser usado.

Valor Exemplo: TLS

client-auth: Tipo de autenticação que o servidor deve ter com o cliente. Por exemplo, o valor want define que o servidor pedirá ao cliente um certificado de autenticação, mas não é mandatório que o cliente possua.

Valor Exemplo: want

key-store: Caminho da keystore com os certificados do PSBio utilizados para conexão segura com módulo AC e outros PSBios.

Valor Exemplo: /etc/griaule/psbio/keystore/ac1.griaulebiometrics.com.pfx

key-store-password: Senha da keystore do PSBio.

Valor Exemplo: password

trust-store: Caminho do repositório com os certificados autorizados para conexão segura.

Valor Exemplo: /etc/griaule/psbio/keystore/cacerts

trust-store-password: Senha do repositório com certificados para conexão segura.

Valor Exemplo: changeit

security:

require-ssl: Define se o protolo de segurança deve ser usado na aplicação

Valor Exemplo: false

legacy:

http-port: Porta de acesso legado

Valor Exemplo: 8081

2.3.3. Configuração do Módulo AC: controlpanel.properties¶

O arquivo de configuração do funcionamento do Painel de Controle do Módulo AC é /etc/griaule/spid/properties/controlpanel.properties. Abaixo são descritas as principais propriedades:

app.mode

Descrição: Usado para fins de controle do nível de informações que são impressas no log.

Valor Padrão: RELEASE

server.http.host

Descrição: Caminho para o serviço do módulo AC.

Valor Padrão: localhost

server.http.port

Descrição: Porta onde está funcionando o serviço do módulo AC.

Valor Padrão: 8082

server.port

Descrição: Porta onde funcionará o serviço do painel de controle do Módulo AC.

Valor Padrão: 58086

2.3.4. Autenticação entre Módulo AC-HSM (Geração de IDN)¶

Os arquivos keystore, que contêm os certificados x509 públicos e privados do módulo AC no formato JKS, estão localizados por padrão na pasta /etc/griaule/spid/keystore.

2.3.5. Configuração de Atualização Automática do SPID Client¶

O Módulo AC permite a configuração de atualização automática das aplicações SPID Client, utilizada para coleta biométrica. De maneira resumida, este recurso permite atualizar todas as estações que se conectam ao Módulo AC sem a necessidade de atualizar uma-a-uma. As configurações permitem a atualização com ou sem a confirmação do usuário. Ou seja, no primeiro caso é questionado ao usuário se ele deseja atualizar o SPID Client. Já no segundo caso a aplicação é atualizada diretamente, sem confirmação do usuário. Para maiores detalhes, consulte a seção Configuração do Módulo AC para atualização automatizada do SPID.

2.4. Módulo PSBio¶

O Módulo PSBio é responsável por implementar as regras de negócios do PSBio de acordo com as normativas da ICP-Brasil.

2.4.1. Tolerância a Falhas¶

Para fazer uso da tolerância a falhas na camada do PSBio, esse módulo deve ser instalado e configurado em todos os nós do GBS Cluster. A tolerância a falhas é realizada por meio de eleição de líder.

Quando os PSBios de um mesmo cluster sobem, apenas um deles é eleito o líder e apenas o líder pode realizar as atividades “proativas”, como por exemplo, tratamento de filas do sistema.

Todos os PSBios (inclusive o líder) podem receber requisições. Se o líder cair, os outros PSBio percebem e um deles toma a liderança para si.

Na integração com o Módulo PSBio, em caso de queda de um dos nós do cluster, as requisições subsqüentes devem ser encaminhadas para o nó subsqüente que assume a liderança.

2.4.2. Localização dos Arquivos de Certificado x509 do Módulo PSBio¶

Os arquivos de certificados x509 do Módulo PSBio estão localizados em /etc/griaule/psbio/keystore.

2.4.3. Configuração do Módulo PSBio: config.properties¶

O arquivo de configuração do funcionamento do Módulo PSBio é /etc/griaule/psbio/properties/config.properties. Abaixo são descritas as principais propriedades:

gbds.host

Descrição: Caminho para o serviço do GBS Cluster que é consumido.

Valor Padrão: localhost

gbds.port

Descrição: Porta para o serviço do GBS Cluster que é consumido.

Valor Padrão: 8085

zookeeper.path

Descrição: Caminho para conexão com o zookeeper do servidor, necessário para comunicação com o banco de dados.

Valor Padrão: localhost:2181

kafka.path

Descrição: Caminho para conexão com o kafka do servidor, necessário para o uso das métricas com ELK.

Valor Padrão: localhost:9092

psbio.name

Descrição: Nome do próprio PSBio. O valor desse campo é atribuído pelo ITI de forma única para cada PSBio.

Valor Padrão: Griaule-1

psbio-info.path

Descrição: Caminho para o JSON no formato da DOC ICP 5.03 contendo as informações sobre os outros PSBios da rede.

Valor Padrão: /etc/griaule/psbio/conf/psbio-info.json

ac-info.path

Descrição: Caminho para o JSON contendo as informações sobre os Módulos ACs aceitos.

Valor Padrão: /etc/griaule/psbio/conf/ac-info.json

connection.timeout

Descrição: Tempo de espera em segundos que o módulo espera para as conexões que faz com o módulo AC, com outros PSBios e com o GBS Cluster.

Valor Padrão: 10

read.timeout

Descrição: Tempo de espera em segundos que o módulo espera para as conexões que faz com o módulo AC, com outros PSBios e com o GBS Cluster.

Valor Padrão: 10

queue.interval

Descrição: Tempo entre varreduras de verificação de transações na fila de pendências.

Valor Padrão: 60

queue.size

Descrição: Tamanho máximo de transações executadas em paralelo na fila de pendências.

Valor Padrão: 1000

cache.start

Descrição: Hora de início do processo de reconstrução de cache, em UTC.

Valor Padrão: 1

cache.final

Descrição: Hora final do processo de reconstrução de cache, em UTC.

Valor Padrão: 9

pending.operations.delay

Descrição: Intervalo entre verificação de pendências entre PSBios, em minutos.

Valor Padrão: 60

server.http.port

Descrição: Porta onde funcionará o painel de controle do PSBio sem uso de SSL.

Valor Padrão: 8084

server.port

Descrição: Porta onde funcionarão as APIs do PSBio com uso de SSL.

Valor Padrão: 8444

server.ssl.key-store

Descrição: Caminho da keystore com os certificados do PSBio utilizados para conexão segura com módulo AC e outros PSBios.

Valor Padrão: /etc/griaule/psbio/keystore/psbio1.griaulebiometrics.com.pfx

server.ssl.key-store-password

Descrição: Senha da keystore do PSBio.

Valor Padrão: password

server.ssl.trust-store

Descrição: Caminho do repositório com os certificados autorizados para conexão segura.

Valor Padrão: /etc/griaule/psbio/keystore/cacerts

server.ssl.trust-store-password

Descrição: Senha do repositório com certificados para conexão segura.

Valor Padrão: changeit

resend-transaction.timeout

Descrição: (UNIX) Timestamp do momento de atualização do PSBio v2 para PSBio v3, caso se aplique. Todas as transações pendentes até esse timestamp serão reenviadas ao GBDS para reprocessar.

Valor Padrão: 0

external-bases.path

Descrição: Caminho até o json que possui informação sobre as bases de dados externas.

kafka.topic.elk.active

Descrição: Flag para envio de mensagem para o ELK.

Valor Padrão: false

2.4.4. End-point do Hub Biométrico e do Serviço de Diretório¶

O PSBio possui dois módulos responsáveis pela comunicação com os demais PSBios, são eles: Hub biométrico e o Serviço de Diretório. O primeiro é responsável por trafegar e receber os arquivos binários ou XMLs com as transações e imagens biométricas.

Já o Serviço de Diretório implementa a API de sincronização entre os PSBios, descrita no item 3.3.6 do DOC-ICP-05.03 e é responsável por manter a sincronia com os demais PSBios. Os end-points dos módulos estão descritos abaixo:

Hub Biométrico: https://<hostname>/gbs-psbio-server/service/hub

Onde hostname é o IP do servidor que está com o Módulo PSBio instalado.

Serviço de Diretório: https://<hostname>/gbs-psbio-server/service/directory

Onde hostname é o IP do servidor que está com o Módulo PSBio instalado.

2.4.5. Painel de Controle do PSBio¶

A conexão ao painel de controle do PSBio é realizada através de protocolo HTTPS. Dessa maneira, o certificado x509 (arquivo .cer) deve ser adicionado ao browser para que a conexão seja possível. O certificado pode ser localizado no diretório indicado na seção Localização dos Arquivos de Certificado x509 do Módulo PSBio.

2.5. Gerador de IDN¶

Para ambientes que utilizam o gerador de IDN , abaixo são descritos procedimentos para instalação, configuração, stop e start do serviço.

2.5.1. Instalação e Configuração¶

Os arquivos disponibilizados para instalação são:

idnservice.tar.gz
idnservice_*.tar.gz
idnservice
gbs-spid-idnservice_*.jar
config.properties

Os arquivos contendo ‘*’ possuem variações dependendo do fabricante do HSM e versão do software.

Além dos arquivos disponibilizados, caso necessário, deve ser importado o keystore, conforme manual do fabricante do HSM e salvo com nome keystore.jks.

Instalação:

Note

Todos os passos devem ser executados como root.
Mova os arquivos para a máquina onde será configurado o gerador de IDN.
Extraia os arquivos compactados nos diretórios listados:

idnservice.tar.gz em /var/lib/griaule

idnservice_*.tar.gz em /etc/griaule

Exemplo:
tar -zxvf idnservice.tar.gz -C /var/lib/griaule/
tar -zxvf idnservice_*.tar.gz -C /etc/griaule/
Mova o arquivo gbs-spid-idnservice_*.jar para /var/lib/griaule/idnservice:
mv gbs-spid-idnservice_*.jar /var/liv/griaule/idnservice
Instale o arquivo idnservice:
mv idnservice /etc/init.d/
chmod 0755 /etc/init.d/idnservice
Instale o arquivo keystore.jks:
mv keystore.jks /etc/griaule/idnservice/keystore/
Instale o arquivo config.properties:
mv config.properties /etc/griaule/idnservice/properties/

Configuração:

Edite o arquivo /etc/griaule/idnservice/properties/config.properties e ajuste o alias da chave a ser utilizada (definido no HSM) da e o modo de operação definido. Exemplo:
entry.alias=IDN
operation.mode=GRIAULE_HOM
server.port=8084

2.5.2. Start do Gerador de IDN¶

O gerador de IDN é instalado como serviço, e pode ser inicializado com o comando:

service idnservice start

A inicialização e o funcionamento podem ser acompanhados pelo arquivo de log:

tail -qF /var/log/griaule/idnservice/idnservice.log

2.5.3. Stop do Gerador de IDN¶

Para finalizar o serviço de geração de IDN, use o comando:

service idnservice stop

2.5.4. Monitoramento e Recuperação¶

Para fins de monitoramento e recuperação automática em caso de perda de comunicação com o HSM, é disponibilizado um script que deve ser inserido na crontab como usuário root, este pode ser configurado para envio de email em caso de falha.

Execute crontab -e e insira:

* * * * * /var/lib/griaule/idnservice/scripts/monitor-idnservice.sh | mail -E -s “Assunto” email1,email2

As mensagens enviadas são:

Failure detected, restarting IDN Service
Restart was successful
Unable to communicate with the Service
Start was successful

2.6. Principais Portas¶

As principais portas de comunicação utilizadas pelo GBS PSBio estão descritas no diagrama abaixo. Essas portas devem estar sem restrições de firewall nos dois sentidos para que a comunicação entre as aplicações não seja prejudicada.

As seguintes portas devem estar com os acessos liberados para as máquinas dos times que fazem a gestão do GBS Cluster:

  - Apache
- API Ambari
- API Cluster
- API SPID PSBio
- API Notificação PSBio
- Monitoramento
- Monitoramento
 - Monitoramento
- On Demand Broker
- Spark
- Monitoramento
- HDFS
- Painel de Controle
- HBase
- HBase
- HBase

2.7. Principais URLs¶

As URLs utilizadas pelas aplicações estão descritas abaixo:

SPID Client: http://<hostname modulo AC>:8082/gbs-spid-server/service/cluster

Note

Se for usada autenticação SSL, altere http para https na URL acima.

Painel de Controle de Operadores: https://<hostname modulo AC>:58086/gbs-spid-controlpanel/
Painel de Controle do PSBio: https://<hostname modulo PSBio>/gbs-psbio-server/

Note

Para acessar o painel de controle do PSBio é necessário que a estação de trabalho cliente tenha o certificado do PSBio conseguir se autenticar (Comunicação HTTPS). Caso contrário, a página do broswer não será carregada.

Agincourt: http://<host name GBS Cluster AC>:8081/gbscluster-api/rest/services/
GBS Apps: http://<host name GBS Cluster PSBio>:8081/gbscluster-api/rest/services/

Note

A configuração do GBS Apps - Tratamento de Exceções para ser utilizada em conjunto com o PSBio deve ser feita com atenção. O procedimento de configuração e utilização está descrito no documento GBS ETR.

É importante observar que o Módulo AC e Módulo PSBio são compostos por clusters de servidores (GBS Cluster). Dessa Maneira, as APIs do Módulo AC e do Módulo PSBio não necessariamente estão no mesmo servidor (hostname) da API do GBS Cluster para cada um dos Módulos. Essa informação é importante para que o apontamento das aplicações seja realizado corretamente. Nas seções posteriores deste manual será descrito o procedimento de como identificar em qual máquina está instalado o Módulo AC/PSBio.

2.8. Funcionamento Módulo AC e Módulo PSBio¶

O módulo AC pode operar de duas maneiras: sozinho ou em conjunto com o Módulo PSBio.

2.8.1. Operação do Módulo AC sem Módulo PSBio¶

Quando não conectado ao módulo PSBio, o Módulo AC realiza o cadastro de operadores e clientes na própria base do Módulo AC. Assim como o cadastro, a deduplicação é também realizada na base do Módulo AC, onde todos os cadastros são confrontados com os registros de operadores e clientes/requerentes. A chave de indexação utilizada no módulo AC é o documento de CPF.

2.8.2. Operação do Módulo AC com Módulo PSBio¶

Quando o Módulo AC está conectado ao PSBio, a transação biométrica segue o fluxo completo:

Coleta biométrica realizada no SPID Client.
Envio da transação para o Módulo AC.
Armazenamento das imagens no Módulo AC.
Geração do IDN ao consultar serviço de geração de IDN.
Envio da transação para o Módulo PSBio, que realizará a deduplicação do cadastro e enviará a transação para os demais PSBios.
Quando finalizada a transação, o resultado é retornado para o Módulo AC, o qual deixa o resultado disponível para consulta do SPID Client.

Em nível de arquitetura, a principal diferença é que nessa configuração (Modulo AC e PSBio) o cadastro de operadores é realizado no Módulo AC enquanto o cadastro e deduplicação de clientes/requerentes é realizado no Módulo PSBio

2.8.3. Dinâmica de Geração de Exceções¶

Abaixo são descritos os casos de duplicidades no PSBio, em conjunto com status reportados após o tratamento das exceções.

Duplicidade em transação de cadastro na base local
- Cadastro IDN 1 e biometrias 1, no qual o cadastro é finalizado na base local.
- Cadastro IDN 2 e biometrias 1
  - Situação: Nesse cenário, será gerada uma exceção de cadastro.
  - Status notificado para AC: status de ENROLL_ANOMALY, acompanhado de mensagem de “Enroll resulted in exception | tcn: <tcn> | idn: <idn> | Same biometrics found in local PSBio | elapsed time: <elapsed_time> s”.
    - Cadastro apresentou uma exceção biométrica e está aguardando tratamento na aplicação GBS Apps.
- Possíveis tratamentos:
  - Mesmas biometrias: quando as biometrias dos dois cadastros forem as mesmas, indicando uma suspeita de fraude. ATENÇÃO: as biometrias de ambos os perfis serão enviadas para a lista negra (blacklist).
    Status notificado para AC:
    
    Para o TCN 1 é notificado o status de PERSON_FRAUD, acompanhado da mensagem “Enroll transaction marked as fraud | tcn: <tcn>| idn: <idn> | elapsed time: <elapsed_time> s”
    
    Para o TCN 2 é notificado o status de FRAUD.
  - Biometrias diferentes: quando as biometrias dos dois cadastros não forem as mesmas; Isto é, o sistema informou similaridade, mas as biometrias não são da mesma pessoa.
  - Recoleta: quando se quer recusar as biometrias do segundo cadastro. O segundo perfil será ignorado e não continuará com o cadastro.
  - Enroll incorreto: quando se quer ignorar as biometrias do primeiro cadastro. As biometrias do primeiro perfil serão excluídas e o segundo perfil será cadastrado.
Falha na atualização em transação de atualização na base local
- Cadastro IDN 1 e biometrias 1, no qual o cadastro é finalizado na base local.
- Atualização IDN 1 e biometrias 2
  - Situação: Nesse cenário, será gerada uma exceção em uma transação de atualização.
  - Status notificado para AC: status de UPDATE_ANOMALY.
    - Cadastro apresentou uma exceção biométrica e está aguardando tratamento na aplicação GBS Apps.
  - Possíveis tratamentos:
    - Mesmas biometrias: quando as biometrias do cadastro e da atualização pertencerem à mesma pessoa. Isso permitirá que que a atualização seja processada.
      - Status notificado para a AC: Para o TCN 2 é notificado o status UPDATE_OK.
    - Biometrias diferentes: quando as biometrias do cadastro e da atualização não forem as mesmas. Se o original foi o perfil válido, selecione a opção considera original válido; Se a transação que gerou a exceção foi válida, selecione considera exceção válida. Importante: As biometrias rejeitadas serão enviadas para a lista negra (blacklist).
      - Considera Original Válido:
        
        Status notificado para AC:
        
        Para o TCN 2 é notificado o status de FRAUD.
      - Considera Exceção Válida: Após tratado, TCN 1 é notificado como FRAUD e é montada uma transação de IDE, a qual é encaminhada para ser pesquisada pelos demais PSBios. Ao concluir a busca, a AC é notificada que a transação do TCN 2 foi concluída com sucesso.
        
        Status notificado para AC:
        
        Para o TCN 1 é notificado o status de FRAUD.
        
        Para o TCN 2 é notificado o status de UPDATE_OK.
    - Recoleta: quando se quer recusar as biometrias da atualização. O segundo perfil será ignorado e não continuará com o cadastro.
    - Enroll incorreto: quando se quer ignorar as biometrias do cadastro. As biometrias do primeiro perfil serão excluídas e as da atualização serão cadastradas.
Transação de cadastro com duplicidade encontrada no cache
- Outro PSBio cadastrou o IDN 1 e biometrias 1 em sua base local.
- PSBio de origem realiza cadastro do IDN 2 com biometrias 1.
- Situação: ao realizar a busca biométrica do IDN 2, as mesmas biometrias serão encontradas no cache do PSBio de origem. Em seguida, o PSBio de origem encaminha o pacote IDE para os demais PSBios da rede e gera uma exceção a ser tratada no GBS Apps.
- Status notificado para AC: ENROLL_ANOMALY em conjunto com mensagem “ENROLL resulted in exception | tcn: <tcn> | idn: <idn> | Same biometrics found in PSBio <PSBio> | elapsed time: <elapsed_time> s”
  - Em seguida, o PSBio de origem encaminha o pacote de IDE para os demais PSBios da rede.
- Possíveis tratamentos:
  - Mesmas biometrias:
    - Ao realizar tal tratamento, o GBS Apps acusará que tal tratamento não está disponível para essa situação, visto que tal transação deve ser tratada por outro PSBio, apresentado a mensagem: “Unable to treat exception. idn is registered in biometric cache”.
  - Biometrias diferentes:
    - Ao escolher a opção de “biometrias diferentes”, a exceção será tratada localmente e aguardará a resposta dos demais PSBios para notificar o módulo AC.
    - Caso o PSBio de origem receba todos os pacotes VRE com campo SRF: “X” (Resultado negativo para as biometrias enviadas do PSBio), o PSBio de origem notificará o status ENROLL_OK para o Módulo AC.
    - Caso o PSBio de origem receba pelo menos 1 pacote VRE com campo SRF: “M” (Resultado positivo para as biometrias enviadas do PSBio), o PSBio de origem notificará o status ENROLL_ANOMALY em conjunto com a mensagem “Mesma(s) biometria(s) encontrada(s) no PSBio <NOME_PSBIO>.”
  - Recoleta:
    - Ao escolher a opção de “recoleta”, a exceção será descartada para que uma nova coleta possa ser feita. A transação de cadastro não será afetada.
  - Enroll incorreto:
    - Ao realizar tal tratamento, o GBS Apps acusará que tal tratamento não está disponível para essa situação, visto que tal transação pertence a outro PSBio, apresentado a mensagem: “Unable to treat exception. idn is registered in biometric cache”
Transação de atualização com duplicidade encontrada em outro PSBio

Outro PSBio cadastrou o IDN 1 e biometrias 1 em sua base local.

PSBio de origem realiza cadastro do IDN 1 com biometrias 2.

Situação:

Ao receber a transação de atualização, o PSBio de origem encaminhará o arquivo de UPR para o PSBio que possui o IDN 1 em sua base local e aguardará o resultado desta transação.

Status notificado para AC:

Não sendo possível realizar o match biométrico em outro PSBio, será notificado o status (para o Módulo AC) de UPDATE_ANOMALY acompanhado da mensagem “Update resulted in exception | tcn: <tcn> | idn: <idn> | Different biometrics from registration | elapsed time: <elapsed_time> s”

3. Toolkits¶

3.1. Exportação das Biometrias do Módulo AC¶

É possível realizar a exportação das biometrias coletadas e armazenadas no Módulo AC através do script get-biometrics. Os parâmetros de entrada do script são o diretório de destino, a data de início e data de fim, determinando que as biometrias cadastradas/atualizadas entre essas duas datas serão exportadas para a pasta desejada. As datas devem ser informadas no formato DD/MM/AAAA.

As biometrias ficarão configuradas em diretórios com a seguinte organização:

output-dir
    |
    |
    +---aaaa-mm-dd
    |     |
    |     +---id-value
    |     |      |
    |     |      +---value_index_aaaammdd.wsq
    |     |      |
    |     |      +---value_aaaammdd.jpg
    |     |
    |     +---id-value
    |            |
    |            +---value_index_aaaammdd.wsq
    |            |
    |            +---value_aaaammdd.jpg
    |
    +---tguids.txt

Nesta estrutura de diretório a base é o diretório informado na invocação do script. No segundo nível existem os diretórios representados pela data de realização das transações. Dentro desse último há um ou mais diretórios representados pelo id, nome do documento informado no cadastro dessa pessoa (pguid se não houver documento), e valor deste para uma pessoa. Esse diretório por sua vez contem a biometrias da pessoa em questão. Os arquivos de digital estarão em formato WSQ com o nome do arquivo sendo o valor do identificador da pessoa, o indíce da digital e a data. Os arquivos de face estarão em formato JPEG com o nome do arquivo composto pelo identificador da pessoa e data. Dentro do diretório base há ainda o arquivo tguids.txt com a identificação (tguid), de todas as transações realizadas no período.

A chamada para utilização deste script deve ser realizada através de:

python get-biometrics.py --out-dir OUTPUTDIR --ini-date INIDATE --end-date ENDDATE

3.2. SPID H2 Dump¶

Requisitos:

O Java que for executar a ferramenta deve ter instalado o pacote Java Cryptography Extension (JCE) Unlimited Strength.

O script deve ser executado do nível onde se encontra a pasta conf, que contem as chaves de encriptação e desencriptação do banco.

Exemplo: Caso a pasta seja extraída em C:\Users\usr39a\Desktop\gbs-spid-h2dump , a execução deve ser realizada a partir dessa pasta.

O script possui três modos de execução, indicados pelo parâmetro -mode:

dump: Exporta as biometrias presentes nos bancos de dados para uma pasta específica.
report: Realiza a consulta do resultado das coletas pendentes e gera três arquivos com os status das coletas nos bancos: um para os status finais, outro para os resultados com erro e o terceiro para os resultados ainda pendentes.
resend: Reenvia as coletas que não estão com status finais para o servidor.

Parâmetros adicionais do script:

-dbDir

Pasta contendo os arquivos de banco de dados a serem analisados (somente arquivos com a extensão .mv.db são analisados).

-dbFile

Indica um arquivo específico de banco de dado a ser analisado (deve conter a extensão .mv.db). É obrigatório em todos os modos que este ou o parâmetro anterior (-dbDir) estejam presentes. Se ambos estiverem, apenas o -dbFile terá efeito.

-url

Caminho do serviço do servidor. A URL é a mesma utilizada pela aplicação SPID Client. Obrigatório para os modos report e resend.

-output (opcional)

Diretório onde serão salvas as biometrias únicas (somente a primeira coleta de cada identificador de cliente) exportadas. Somente tem efeito no modo dump.

-outputUpdates (opcional)

Diretório onde serão salvas as biometrias duplicadas (caso já exista uma coleta exportada no diretório anterior com um dado identificador de cliente) exportadas. Tem efeito apenas no modo dump.

-operatorID (opcional)

Filtro que considera apenas as coletas com um determinado identificador de operador (o identificador deve estar sem pontuação). Exemplo: 12345678909.

-clientID (opcional)

Filtro que considera apenas as coletas com um determinado identificador de cliente (o identificador deve estar sem pontuação).

-interval (opcional)

Intervalo em segundos de envio entre cada uma das coletas no modo resend. Observação: Deve-se utilizar valores de 10 segundos ou mais.

Exemplos de execução:

java -jar gbs-spid-h2dump.jar -mode report -dbDir J:/data/ -url http://192.168.0.140:8082/gbs-spid-server/service/cluster/

java -jar gbs-spid-h2dump.jar -mode resend -dbDir J:/data/ -url http://192.168.0.140:8082/gbs-spid-server/service/cluster/ -interval 10

java -jar gbs-spid-h2dump.jar -mode dump -dbFile J:/data/spid.mv.db -clientID 12345678909 -output coletas

4. Procedimentos¶

4.1. Inserção de Perfis na Blacklist do PSBio¶

Para realizar a inserção das imagens na blacklist deve-se realizar uma operação de trusted-Enroll, diretamente no GBDS, para cada perfil biométrico de fraude, através da URL:

http://<ip>:8085/gbds/v2/people/trusted

Caso o perfil contenha dedos e face, todas as biometrias devem ser enviadas no mesmo pacote JSON, análogo ao pacote utilizado para operações de enroll.

Esta chamada é um POST contendo um JSON:

{
  "meta": {
    "timeout": -1
  },
  "data": {
    "keys": [
      {"id": "blacklist", "value": "BBBBBBBB-BBBB-4B07-CCCC-67B6E09F64C8" }
    ],
    "biometric": [
      {
        "index": (0/10),
        "content":"<base64>",
        "source": "ORIGINAL",
        "type": "(FINGERPRINT/FACE)",
        "format": "(WSQ/JPEG)",
        "properties": {
          "width": <largura>,
          "height": <altura>>,
          "resolution": <resolução>
        }
      }
    ],
    "labels": ["BLACKLIST"]
  }
}

Deve-se gerar um UUID aleatório para o campo “value”. Os índices utilizados nessa chamada de cadastro na blacklist são os da tabela abaixo:

Índice	Biometria
0	Dedo mínimo esquerdo
1	Dedo anelar esquerdo
2	Dedo médio esquerdo
3	Dedo indicador esquerdo
4	Polegar esquerdo
5	Polegar direito
6	Dedo indicador direito
7	Dedo médio direito
8	Dedo anelar direito
9	Dedo mínimo direito
10	Face

4.2. Obter TCNs de Transações Encaminhadas entre PSBios¶

4.2.1. Transações Enviadas¶

Para obter as transações enviadas para determinado PSBio, use o seguinte comando:

hbase shell

scan 'psbio_transactions',{FILTER => "SingleColumnValueFilter('f','dest', =, 'substring:GRIAULE') AND SingleColumnValueFilter('i','metadata', =, 'substring:originaryTCN')", MAXLENGTH => 300}

Neste exemplo, o resultado será a lista de todas as transações enviadas para o PSBio GRIAULE.

4.2.2. Transações Recebidas¶

Para obter as transações recebidos de determinado PSBio, use o seguinte comando:

hbase shell

scan 'psbio_transactions',{FILTER => "SingleColumnValueFilter('f','dest', =, 'substring:GRIAULE') AND SingleColumnValueFilter('i','metadata', !=, 'substring:originaryTCN')", MAXLENGTH => 300}

Neste exemplo, o resultado será a lista de todas as transações recebidas do PSBio GRIAULE.

4.2.3. Lista de Transações Pendentes em Outros PSBios¶

A query abaixo permite obter a lista de transações de IDE pendentes que outros PSBios devem processar para o PSBio de origem:

hbase shell << EOF > pending_1n_ORGANIZATION.out
scan 'psbio_orderPending',{MAXLENGTH => 300, FILTER => "SingleColumnValueFilter('i','dest',=,'binary:ORGANIZATION',true,true) AND SingleColumnValueFilter('i','status',=,'binary:PENDING',true,true)"}
EOF

Importante: Substitua ORGANIZATION em ...'dest',=,'binary:ORGANIZATION',true... pelo nome do PSBio do qual deseja obter as pendências.

A lista gerada informa os TCNs que outro PSBio está devendo o processamento para o PSBio de origem.

No exemplo acima, o arquivo de saída será pending_1n_ORGANIZATION.out.

4.2.4. Obter TCNs e Status das Transações Geradas pelo Módulo AC no PSBio¶

hbase shell << EOF > arquivoSaida.out
scan 'psbio_transactions',{MAXLENGTH => 300, TIMERANGE => [1517529600000,1518739199000], FILTER => "SingleColumnValueFilter('i','type',=,'substring:ENROLL',true,true)", COLUMNS => ['i:ac_sr','f:status','i:type']}
EOF

Os campos numéricos no TIMERANGE acima indicam o timestamp em milissegundos de início e fim, respectivamente, das transações que se deseja obter os TCNs e resultados.

4.3. Configuração do Apontamento entre Módulo AC e Módulo PSBio¶

Para averiguar qual ambiente o Módulo PSBio e qual o Módulo AC estão instalados, basta acessar a pasta /var/lib/griaule:

No caso do Módulo PSBio, haverá uma pasta chamada psbio.
No caso do Módulo AC, haverá uma pasta chamada spid.

Para apontar o Módulo AC para o Módulo PSBio, o passo-a-passo abaixo deve ser seguido:

4.3.1. Servidor com Módulo AC¶

Edite o arquivo /etc/griaule/spid/properties/config.properties e substitua <hostname> pelo hostname da instância em que o módulo PSBio está rodando:
# nome do PSBio com o qual o Proxy vai se comunicar,
# deve ser idêntico ao nome configurado no
# arquivo config.properties do PSBio
psbio.name=server-psbio
psbio.api.url=https://<hostname>/gbs-psbio-server/service/ac-api
psbio.hub.url=https://<hostname>/gbs-psbio-server/service/hub
psbio.directory.url=https://<hostname>/gbs-psbio-server/service/directory
Anote a informação em ac.name.

4.3.2. Servidor com Módulo PSBio¶

Edite o arquivo /etc/griaule/psbio/conf/ac-info.json, para que coincida com o valor configurado no config.properties do módulo AC:
[
  {
    "ACId": "ac1.griaulebiometrics.com",
    "ACName": "ac1.griaulebiometrics.com",
    "ACEndpoint": "https://ac1.griaulebiometrics.com:8444/gbs-spid-server/service/notify"
  },
]
Note

As informações do documentos config.properties do Módulo PSBio e Módulo AC precisam ser coerentes. Os nomes devem estar de acordo, assim como os certificados. Além disso, os dois ambientes precisam ser capazes de se comunicar pelas portas configuradas (em ambos os sentidos).

4.3.3. Confirmação de driver, broker e API do GBS Cluster¶

Uma vez que as configurações acima foram feitas, é preciso confirmar que o driver, o broker e a API do GBS Cluster estão no ar para os dois ambientes. Isso pode ser feito através da API SC.

Acesse http://<hostname>:8081/gbscluster-api/rest/services/sc.

Ao acessar essa URL, serão listados o driver e os brokers para o GBS Cluster.

4.3.4. Reiniciando o Módulo AC e PSBio¶

Este passo deve ser feito nos dois ambientes como root.
service psbio start
service spid start
service spid-cp start

4.3.5. Configuração do SPID Client¶

Uma vez que os serviços do GBS Cluster e o Módulo AC/PSBio estejam no ar, é preciso configurar o SPID Client para apontar para o Módulo AC.

Para isso, edite o arquivo C:\Griaule\SPID\conf\GBSSpid2.properties e altere server.url conforme exemplo abaixo:
server.url=http://<hostname>:8082/gbs-spid-server/service/cluster/
Substitua <hostname> pelo hostname do Módulo AC. O PC precisa conseguir acessar o Módulo AC através da porta 8082.

4.3.6. Acompanhamento de Logs¶

A realização dos cadastros pode ser acompanhada nos diretórios /var/log/griaule/spid e /var/log/griaule/psbio.

4.4. Configuração da URL do Serviço de Geração de IDN¶

É possível configurar para qual URL de serviço de geração de IDN o Módulo AC deve apontar. Isso pode ser feito através da alteração da propriedade idn: serviceUrl no arquivo /etc/griaule/psbio/properties/spid.yaml.

4.5. Configuração dos Certificados para Autenticação HTTPS Módulo AC-PSBio¶

4.5.1. Instalação do Keystore¶

Obtenha o arquivo .keystore, que é o certificado privado que deve estar no formato JKS. Basicamente é um keystore do Java com as chaves privada e pública do cliente e também os certificados públicos da cadeia que o assina.

Coloque o arquivo .keystore na pasta /etc/griaule/psbio/keystore.

4.5.2. Configuração do PSBio¶

Edite o arquivo /etc/griaule/psbio/conf/config.properties e atualize os campos nos campos de caminho e senha. O campo ac.name também deve ser alterado para o Common Name do certificado do módulo AC. Exemplo:

server.ssl.key-store=/etc/griaule/psbio/keystore/certificado.keystore
server.ssl.key-store-password=senha
psbio.name=
ac.name=

Edite o arquivo /etc/griaule/psbio/conf/psbio-info.json e altere a propriedade PSBioId para o Common Name do certificado do módulo AC sendo executado no endereço associado.

4.5.3. Importação do Certificado Público da AC¶

Para o módulo PSBio reconhecer o certificado da AC e de outros PSBios, é necessário que o certificado público da AC ou PSBio e sua respectiva cadeia sejam importados. Os arquivos em formato .cer ou .pem devem ser importados na lista de certificados aceitos, que é armazenada no arquivo /etc/griaule/psbio/keystore/cacerts. A importação pode ser realizada com o comando abaixo:

keytool  -import -trustcacerts -alias server-psbio10-w -file server-psbio10.cer -keystore /etc/griaule/psbio/keystore/cacerts -storepass changeit

O parâmetro -alias indica o nome do certificado a ser importado, e -file indica o arquivo do certificado.

4.5.4. Importação do Certificado Público do PSBio¶

Para o módulo AC reconhecer o certificado do PSBio (autenticação HTTPS mútua), é necessário que o certificado público do PSBio e sua respectiva cadeia sejam inseridos. Para isso, os arquivos em formato .cer ou .pem devem ser importados na lista de certificados aceitos, que é aramzenada no arquivo /etc/griaule/spid/keystore/cacerts. A importação pode ser realizada com o comando abaixo:

keytool  -import -trustcacerts -alias server-psbio10-w -file server-psbio10.cer -keystore /etc/griaule/spid/keystore/cacerts -storepass changeit

O parâmetro -alias indica o nome do certificado a ser importado, e -file indica o arquivo do certificado.

4.6. Configuração de Certificados para Autenticação HTTPS entre Módulo AC e Serviço de Geração de IDN¶

Para que ocorra a autenticação mútua entre os servidores do Módulo AC e o servidor do serviço de Geração de IDN, é necessário o certificado público do Módulo AC seja adicionado no Gerador de IDN e vice-e-versa.

A importação do certificado público do Módulo AC no Gerador de IDN não está descrita nesse manual, pois a implementação do serviço de geração de IDN pode variar para cada ambiente.

Já a importação do certificado público do Gerador de IDN deve ser realizada de forma similar à descrita na seção Importação do Certificado Público da AC.

4.7. Mudança da Versão do Java a Executar a Aplicação¶

Para especificar uma determinada versão do Java para execução da aplicação, edite o arquivo initialize-psbio.sh, que se encontra em /var/lib/griaule/psbio/scripts. Altere a primeira linha que contem /etc/griaule/psbio/jdk1.8.0_101/bin/java.

Warning

Esta modificação não é recomendada.

4.8. Limpeza do Banco de Dados¶

Para realizar limpeza da base, é necessário seguir passos abaixo e executar o script truncate_hbase.sh.

Warning

Este script excluirá todos os dados presentes no banco de dados. A execução deve ser realizada apenas em casos de total aceite e entendimento das implicações e impactos de sua execução.

Note

O script deve ser executado como usuário griaule.

1. Pare os serviços Módulo AC e PSBio

service spid stop
service spid-cp stop

2. Execute o script

truncate_hbase.sh

3. Reinicie os serviços

Aguarde alguns minutos e reinicie os serviços dos Módulos AC e PSBio:
service spid start
service spid-cp start

4.9. Configuração de funcionamento do Módulo AC e Módulo PSBio¶

O Módulo AC pode funcionar acoplado ou não com o Módulo PSBio. Em caso de acoplamento, todos os cadastros de clientes serão enviados e deduplicados unicamente pelo PSBio. Em caso de não acoplamento, todos os cadastro de clientes serão deduplicados no próprio Módulo AC.

Para realizar a configuração, o seguinte procedimento pode ser realizado:

Edite o arquivo config.properties do Módulo AC.
Para ativar acoplamento com PSBio, marque a varíavel operation.mode=psbio
Para desativar acoplamento com PSBio, marque a varíavel operation.mode=gbds

4.10. Configuração do Módulo AC para atualização automatizada do SPID¶

A partir da versão 1.4.0 do SPID, foram implementadas duas novas chamadas para o módulo AC (check-version e update-version). Nelas, durante a inicialização do SPID Client, ou do SPID Services, o programa verifica a última versão disponível do aplicativo, e pode perguntar ou não ao usuário se ele deseja atualizar a versão no seu computador.

Para subir uma nova atualização no servidor, os seguintes procedimentos devem ser seguidos:

No Módulo AC, na pasta /etc/griaule/spid/client/exe , suba a versão mais nova disponível com o seguinte nome: **%NOME-DA-EMPRESA%-spid-client-vX-X-X.exe*, onde X-X-X representa a versão X.X.X. Por exemplo, para a versão 1.4.12 do SPID, o *arquivo deve ser: */etc/griaule/spid/client/exe/griaule-spid-client-v4-1-12.exe**
Na pasta acima (/etc/griaule/spid/client) deve existir um arquivo chamado version. Nele, apenas uma linha de texto deve existir, com o número da última versão disponível. Esse número deve coincidir com o de algum executável presente na pasta /etc/griaule/spid/client/exe.
Duas opções são possíveis na versão presente no arquivo version. A primeira é salvar o número da versão mais nova sem um asterisco no final (formato X.X.X). Dessa maneira, o usuário do SPID será questionado se gostaria ou não de atualizar sua versão.
A outra opção é salvar o número da versão mais nova disponível com um asterisco no final (formato X.X.X*). Dessa maneira, a atualização do SPID será compulsória para todos os usuários conectados nesse servidor, e a nova versão será instalada sem a escolha do usuário.

4.11. Configurar Modulo AC para utilizar geração de IDN Local¶

Para apontar o Módulo AC para o gerador de IDN local, o seguinte procedimento deve ser realizados:

Editar no arquivo /etc/griaule/spid/properties/config.properties a propriedade idn.service.url para http://localhost:8082/gbs-spid-server/service/idn

4.12. Replicação dos Serviços de PSBio em outro Site¶

Em casos de disaster recovery é possível realizar a continuação dos serviços do PSBio através da importação das informações do site principal em outro site de backup que possua o GBS Cluster instalado.

Para isso, deve-se manter uma rotina de exportação dos dados do banco de dados através de metodologia detalhada na documentação do GBS Cluster.

5. Logs¶

5.1. Módulo AC¶

Nos servidores que constituem o módulo AC, o monitoramento e acompanhamento de logs pode ser realizado através dos arquivos abaixo:

/var/log/griaule/spid/ac.log
/var/log/griaule/spid/stderr.out
/var/log/griaule/spid/stdout.out

5.2. Módulo PSBio¶

Nos servidores que constituem um módulo PSBio, o monitoramento e acompanhamento de logs pode ser realizado através dos arquivos abaixo:

/var/log/griaule/psbio/psbio.log
/var/log/griaule/psbio/stderr.out
/var/log/griaule/psbio/stdout.out

5.3. Monitoramento¶

Para mais informações sobre o monitoramento do GBS PSBio, consulte os manuais de monitoramento do GBS Cluster.

6. Instalação¶

6.1. Instalação PSBio¶

Requisitos mínimos:

Memória disponível: 2 GB
Espaço em disco disponível: 2 GB
GBS Cluster instalado

Pacotes necessários:

gbs-psbio-server.tar.gz

6.1.1. Instalação¶

Extraia o conteúdo de gbs-psbio-server.tar.gz e mova o arquvo gbs-psbio-server.jar para o diretório /var/lib/griaule:

tar -xf gbs-psbio-server.tar.gz .
mv gbs-psbio-server.jar /var/lib/griaule/

Mova o arquivo config.properties no diretório /etc/griaule/psbio/properties:

mv config.properties /etc/griaule/properties/

Mova os arquivos psbio-info.json e ac-info.json no diretório /etc/griaule/psbio/conf:

mv *.json /etc/griaule/conf/

Mova o arquivo initialize-psbio.sh no diretório /var/lib/griaule/psbio/scripts e ajuste suas permissões:

mv initialize-psbio.sh /var/lib/griaule/psbio/scripts/
chmod 755 /var/lib/griaule/psbio/scripts/initialize-psbio.sh

Mova o arquivo psbio para a pasta /etc/init.d e ajuste suas permissões:

mv psbio /etc/init.d/
chmod 755 /etc/init.d/psbio

6.2. Automatização de instalação¶

Há um RPM de instalação / atualização do PSBio. Os seguintes passos são executados no momento da instalação: Cria uma pasta /root/configs/ e copia os arquivos de configuração nela (config.sh ac-info.json config.properties initialize-psbio.sh psbio psbio-info.json) Extrai gbs-psbio-server.jar para /var/lib/griaule/psbio/ Portanto, é necessário copiar e modificar manualmente os arquivos psbio-info.json e ac-info.json.

Ao executar o script config.sh em /root/config.sh, para cada caso o usuário pode escolher entre fazer nada ou: Sobreescrever o serviço de inicialização do psbio em /etc/init.d/ Sobreescrever initialize-psbio.sh em /var/lib/griaule/psbio/scripts/ Sobreescrever ou fazer merge do config.properties Caso for merge, o script fará append das configurações do novo arquivo não presentes no arquivo antigo. É necessário alterar os valores de acordo com o ambiente.

rpm -ivh gbspsbioserver-RELEASE.x86_64.rpm
/root/configs/config.sh

6.2.1. Configuração¶

config.properties

Edite o arquivo /etc/griaule/psbio/properties/config.properties conforme necessário:

#
# GBS PSBio Server properties
# Copyright 2020 Griaule Biometrics
#

# Path to Zookeeper
zookeeper.path=localhost:2181

# GBDS Connection
gbds.host=gbds
gbds.port=8085

# GBDS Authentication
gbds.authentication.enabled=false
gbds.authentication.expiration.interval=600000
gbds.username=admin
gbds.password=admin

# Timeout of any connection in seconds
connection.timeout=30

# Path to data decryption private key
decryption.key.path=/etc/griaule/spid/conf/data_private.key

# Mode of operation
operation.mode=gbds

# Type of document used as key
document.id=documentID

# PSBio Connection
psbio.name=psbio.griaule.com
psbio.api.url=https://psbio.griaule.com:8444/gbs-psbio-server/service/ac-api
psbio.hub.url=https://psbio.griaule.com:8444/gbs-psbio-server/service/hub
psbio.dir.url=https://psbio.griaule.com:8444/gbs-psbio-server/service/directory

# ID of this AC
ac.name=ac1.griaulebiometrics.com

# IDN Service Connection
idn.service.url=http://localhost:8082/gbs-spid-server/service/idn

# Require Operator Validation
operator.validate=false

# Deduplicate Operator
operator.deduplicate=true

# Evidences
evidence.generate=true
evidence.path=/etc/griaule/spid/coletas
evidence.format=griaule

# Port configuration
server.port=8444
server.http.port=8082

# SSL
server.ssl.key-store=/etc/griaule/spid/keystore/ac1.griaulebiometrics.com.pfx
server.ssl.key-store-password=password
server.ssl.trust-store=/etc/griaule/spid/keystore/cacerts
server.ssl.trust-store-password=changeit

# Timestamp of version upgrade
resend-transaction.timeout=0

# External Bases Verification
external-bases.path=/etc/griaule/psbio/conf/external-bases.json

psbio-info.json

Edite o arquivo psbio-info.json localizado em /etc/griaule/psbio/conf:
vim /etc/griaule/psbio/conf/psbio-info.json
O documento apresentará entradas similares à entrada abaixo, para cada PSBio. Elas devem ser configuradas no padrão apresentado a seguir:
[
   {
     "PSBioId": "server-psbioX",
     "PSBioName": "<hostname>",
     "nist_endpoint": "https://localhost/gbs-psbio-server/service/hub",
     "directory_endpoint": "https://localhost/gbs-psbio-server/service/directory"
   },
]
O campo PSBioId é o nome dado ao ITI para cada PSBio. O campo PSBioName deve ser completado com o CommonName do respectivo certificado do PSBio. As duas URLs referenciam o próprio cluster do PSBio.

ac-info.json

Edite o arquivo ac-info.json localizado em /etc/griaule/psbio/conf:
vim /etc/griaule/psbio/conf/ac-info.json
O documento apresentará entradas similares à entrada abaixo, para cada AC. Elas devem ser configuradas no padrão apresentado a seguir:
[
   {
     "ACId": "acX.griaulebiometrics.com",
     "ACName": "acX.griaulebiometrics.com",
     "ACEndpoint": "https://ac1.griaulebiometrics.com:8444/gbs-spid-server/service/notify",
   },
]
Os campos ACId e ACName devem ser completados com o CommonName do respectivo certificado da AC. A URL referencia o endpoint de notificação da AC.

Utilize os seguintes comandos para ligar, desligar, reiniciar ou verificar o status do PSBio:

service psbio start
service psbio stop
service psbio restart
service psbio status

external-bases.json

Edite o arquivo external-bases.json localizado em /etc/griaule/psbio/conf/ conforme necessário:

[
    {
        "id": "DATAVALID",
        "host": "host",
        "port": 443
    }
]

6.3. Instalação do Módulo AC¶

Requisitos mínimos:

Memória disponível: 2 GB
Espaço em disco disponível: 2 GB
GBS Cluster instalado

Pacotes necessários:

spid.tar.gz
spid_etc.tar.gz
spid
spid-cp
gbs-spid-server_<versão>.zip

6.3.1. Instalação¶

Extraia o conteúdo de spid.tar.gz no diretório /var/lib/griaule:

tar -zxvf spid.tar.gz -C /var/lib/griaule/

Extraia o conteúdo de spid_etc.tar.gz no diretório /etc/griaule:

tar -zxvf spid_etc.tar.gz -C /etc/griaule/

Mova os arquivos spid e spid-cp para a pasta /etc/init.d e ajuste suas permissões:

mv spid /etc/init.d
mv spid-cp /etc/init.d
chmod 755 /etc/init.d/spid*

Extraia os arquivos do pacote gbs-spid-server e mova-os para os locais indicados:

unzip gbs-spid-server_<versão>.zip
mv gbs-spid-server.jar /var/lib/griaule/spid
mv gbs-spid-controlpanel.jar /var/lib/griaule/spid
mv config.properties /etc/griaule/spid/properties
mv controlpanel.properties /etc/griaule/spid/properties

6.3.2. Configuração¶

spid.yaml

Edite o arquivo /etc/griaule/spid/properties/spid.yaml conforme necessário. Um exemplo de como o arquivo pode ser configurado:

# SPID Server Configuration
spid:
  authenticationEnabled: false
  caName: acdev1.griaule.com
  documentId: documentID
  decryptionKeyPath: /etc/griaule/spid/conf/data_private.key
  operator:
    deduplicate: false

hadoop:
  zookeeperPath: localhost:2181

idn:
  serviceUrl: http://localhost:8081/gbs-spid-server/service/idn

evidence:
  generate: true
  path: /etc/griaule/spid/coletas
  format: griaule

gbds:
  host: localhost
  port: 8085
  useSSL: false
  authenticationEnabled: false
  authenticationExpiration: 600000
  username: admin
  password: admin

psbio:
  active: true
  name: psbiodev.griaule.com
  apiUrl: https://localhost:8444/gbs-psbio-server/service/ac-api
  hubUrl: https://localhost:8444/gbs-psbio-server/service/hub
  dirUrl: https://localhost:8444/gbs-psbio-server/service/directory

spidx:
  organizationName: acdev1
  organizationCallback: callback
  organizationHostname: acdev1
  host: spidx
  port: 8090
  qualityThreshold: 50

# Additional Spring Configurations
server:
  port: 8082
  ssl:
    protocol: TLS
    client-auth: want
    key-store: /etc/griaule/spid/keystore/ac1.griaulebiometrics.com.pfx
    key-store-password: password
    trust-store: /etc/griaule/spid/keystore/cacerts
    trust-store-password: changeit

security:
  require-ssl: false

# Legacy Configuration
legacy:
  http-port: 8081

controlpanel.properties

Edite o arquivo /etc/griaule/spid/properties/controlpanel.properties conforme necessário:

#
# GBS SPID Control Panel properties
# Copyright 2020 Griaule Biometrics
#

# SPID Control Panel port
server.port=58086

# SPID Server Connection
server.http.host=localhost
server.http.port=8082

Utilize os seguintes comandos para ligar, desligar, reiniciar ou verificar o status do módulo AC e do Painel de Controle:

service spid start
service spid stop
service spid restart
service spid status

service spid-cp start
service spid-cp stop
service spid-cp restart
service spid-cp status

6.3.3. Configuração de Backup¶

Copie os arquivos backup-spid-server.sh e restore-spid-server.sh para o diretório /var/lib/griaule/gbscluster/scripts/.

Adicione o job de backup do cron como usuário griaule. Execute o comando crontab -e e adicione a seguinte linha à configuração:

0 23 * * * griaule /var/lib/griaule/gbscluster/scripts/backup-spid-server.sh

O script fará um backup das tabelas do Módulo AC no diretório /home/griaule/backup/modulo-ac e manterá os últimos 5 dias de backup. Cabe ao cliente copiar estes arquivos para uma mídia externa.

Para realizar a restauração, descompacte o conteúdo do arquivo tgz criado pelo backup para o diretório /home/griaule/backup/modulo-ac e execute o script restore-spid-server.sh como usuário griaule.

Conteúdo do script backup-spid-server.sh:

#!/bin/sh
### ====================================================================== ###
##                                                                          ##
##  Griaule Biometric PSBio data backup script                              ##
##                                                                          ##
### ====================================================================== ###

HDFS_BACKUP_DIR=griaule/backup/modulo-ac

hdfs dfs -test -d $HDFS_BACKUP_DIR
if [ $? == 0 ]; then
  echo "Clearing previous backup:"
  hdfs dfs -rm -R $HDFS_BACKUP_DIR
fi;

hbase org.apache.hadoop.hbase.mapreduce.Export 'proxy_operators' $HDFS_BACKUP_DIR/proxy_operators
hbase org.apache.hadoop.hbase.mapreduce.Export 'proxy_order' $HDFS_BACKUP_DIR/proxy_order
hbase org.apache.hadoop.hbase.mapreduce.Export 'proxy_people' $HDFS_BACKUP_DIR/proxy_people
hbase org.apache.hadoop.hbase.mapreduce.Export 'proxy_transactions' $HDFS_BACKUP_DIR/proxy_transactions

hdfs dfs -get griaule/backup/modulo-ac /home/griaule/backup/modulo-ac
tar -czvf /home/griaule/backup/modulo-ac.tgz /home/griaule/backup/modulo-ac
mv /home/griaule/backup/modulo-ac.tgz /home/griaule/backup/modulo-ac_`date +%d-%m-%Y`.tgz
rm -rf /home/griaule/backup/modulo-ac
find /home/griaule/backup/* -mtime +5 -exec rm {} \;

Conteúdo do script restore-spid-server.sh:

#!/bin/sh
### ====================================================================== ###
##                                                                          ##
##  Griaule Biometric PSBio data restore script       ##
##                                                                          ##
### ====================================================================== ###

HDFS_BACKUP_DIR=griaule/backup/modulo-ac

hdfs dfs -test -d $HDFS_BACKUP_DIR
if [ $? != 0 ]; then
  echo "HDFS Backup path not found:"
  echo $HDFS_BACKUP_DIR
  exit 1;
fi;

hdfs dfs -put /home/griaule/backup/modulo-ac griaule/backup/modulo-ac

hbase org.apache.hadoop.hbase.mapreduce.Import 'proxy_operators' $HDFS_BACKUP_DIR/proxy_operators
hbase org.apache.hadoop.hbase.mapreduce.Import 'proxy_order' $HDFS_BACKUP_DIR/proxy_order
hbase org.apache.hadoop.hbase.mapreduce.Import 'proxy_people' $HDFS_BACKUP_DIR/proxy_people
hbase org.apache.hadoop.hbase.mapreduce.Import 'proxy_transactions' $HDFS_BACKUP_DIR/proxy_transactions

6.3.4. Setup da Facelib¶

Execute o script facelib_setup.sh.

Conteúdo do script facelib_setup.sh:

#!/bin/bash

EXE_TIME=$(date +'%Y-%m-%d-%H%M%S')
LOG_PATH=$PWD/logs
LOG_FILE=$LOG_PATH/facelib_setup-${EXE_TIME}.log
function logger(){
    # FUNCTION PARAMETERS
    # logger functionName status [INFO, WARN, ERROR] logMessage
    # exemple: logger "hello_world" "INFO" "Hello World" first_log

    if [ ! -d $LOG_PATH ];then
        mkdir $LOG_PATH
    fi

    CURRENT_TIME=$(date +'%Y-%m-%d %H:%M:%S')
    FUNCTION=$1
    STATUS=$2
    LOG_MESSAGE=$3

    LOG_FORMAT="$CURRENT_TIME  -  $FUNCTION  -  $STATUS  -  $LOG_MESSAGE"

    # commit log message
    echo $LOG_FORMAT | tee -a $LOG_FILE

}

function install_pre_reqs(){
    # parameter
    PACKAGE=$1

    # installing package

    logger "environment_checker" "INFO" "Checking $PACKAGE installation"
    yum -y install $PACKAGE &>/dev/null
    OUTPUT_CODE=$?
    CHK_INSTALLATION=$(rpm -qa | grep $PACKAGE)

    # Checking if was installed

    if [ $OUTPUT_CODE -eq 0 ];then
        logger "environment_checker" "INFO" "$PACKAGE installation OK"
    else
        logger "environment_checker" "WARN" "$PACKAGE installation finalized with errors or warnings"
        if [ -z $CHK_INSTALLATION ];then
            logger "environment_checker" "ERROR" "$PACKAGE not installed due some error!!"
            logger "environment_checker" "INFO" "Please run \"yum -y install $PACKAGE\" and try again!!"
            exit 1
        fi
    fi
}

function environment_checker(){
    # This function is used only to check some requirements
    # of facelib
    logger "environment_checker" "INFO" "Staring environment check"

    # variables
    OS=$(head -1 /etc/os-release | awk -F '"' '{print $2}')
    OS_VERSION=$(head -2 /etc/os-release | tail -1 | awk -F '"' '{print $2}')
    OS_ID=$(head -3 /etc/os-release | tail -1 | awk -F '"' '{print $2}') # rhel or centos
    SPID_LIB_FOLDER="/var/lib/griaule/spid"
    USR_NAME=$(whoami)

    logger "environment_checker" "INFO" "OS: $OS $OS_VERSION"

    # Need run with root user

    if [[ ! $USR_NAME == "root" ]];then
        logger "environment_checker" "ERROR" "You're running script as $whoami!! Please run script as root."
        exit 1
    fi

    # Installing all pre recs with the function install_pre_reqs

    #TODO fill this list with all pre-reqs
    if [[ $OS_ID == "centos" ]];then
        PACKAGES_TO_INSTALL="wget curl OpenEXR-libs libraw1394-devel libusbx"
    elif [[ $OS_ID == "rhel" ]];then
        PACKAGES_TO_INSTALL="wget curl OpenEXR-libs libraw1394 libusbx"
    else
        logger "environment_checker" "ERROR" "your operating system has not been approved"
    fi
    for PACKAGE in $PACKAGES_TO_INSTALL;do
        install_pre_reqs $PACKAGE
    done

    # checking /var/lib/griaule/spid folder

    if [ ! -d $SPID_LIB_FOLDER ];then
        logger "environment_checker" "ERROR" "SPID not installed!!"
        exit 1
    fi

    # create griaule user

    logger "environment_checker" "INFO" "Checking griaule user"
    useradd griaule &>/dev/null
    OUTPUT_CODE=$?
    CHK_USR=$(grep griaule /etc/passwd)
    if [ $OUTPUT_CODE -eq 0 ] || [ ! -z $CHK_USR ];then
        logger "environment_checker" "INFO" "griaule user: OK"
    else
      logger "environment_checker" "ERROR" "Error creating griaule user"
      exit 1
    fi

    # Setting griaule user as owner

    logger "environment_checker" "INFO" "Changing SPID folders ownership to griaule"
    chown griaule: -R {/var/lib/griaule,/etc/griaule}

    logger "environment_checker" "INFO" "Environment check run successfully"

}

function facelib_setup(){
    logger "facelib_setup" "INFO" "Starting facelib setup"
    logger "facelib_setup" "INFO" "Downloading facelib from griaule repo"

    # download facelib from griauel repo
    if [ ! -e $PWD/bin.facelib-java.tar.gz ];then
        wget -q http://repo.griaule.com/griaule/services/spid/bin.facelib-java.tar.gz
    fi

    OUTPUT_CODE=$?
    GET_PUB_IP=$(curl ifconfig.me 2>/dev/null)

    # Verify connetion with repo
    if [ ! $OUTPUT_CODE -eq 0 ];then
        logger "facelib_setup" "ERROR" "Downloading facelib from griaule repo"
        if [ -z $GET_PUB_IP ];then
            logger "facelib_setup" "ERROR" "Maybe you're not connected with the internet. Please check your connection and try again!!"
            exit 1
        else
            logger "facelib_setup" "INFO" "Maybe you're not authorized in the Griaule repo. Please send your public ip $GET_PUB_IP to Griaule support requesting authorization"
            exit 1
        fi
    fi

    # Extracting tar.gz

    logger "facelib_setup" "INFO" "Starting facelib extraction"

    tar -xvzf bin.facelib-java.tar.gz -C /var/lib/griaule/spid/ &>/dev/null
    OUTPUT_CODE=$?
    if [ ! $OUTPUT_CODE -eq 0 ];then
  logger "facelib_setup" "ERROR" "extracting facelib to /var/lib/griaule/spid/"
        exit 1
    fi

    logger "facelib_setup" "INFO" "Facelib extracted successfully"

    # update spid script

    logger "facelib_setup" "INFO" "Update initialize spid scirpt"
    mv /var/lib/griaule/spid/scripts/initialize-spid.sh /var/lib/griaule/spid/scripts/initialize-spid.sh.bkp
    mv /var/lib/griaule/spid/bin.facelib-java/initialize-spid.sh /var/lib/griaule/spid/scripts/initialize-spid.sh
    chmod +x /var/lib/griaule/spid/scripts/initialize-spid.sh
    logger "facelib_setup" "INFO" "Initialize spid scirpt updated"

    logger "facelib_setup" "INFO" "Facelib setup run successfully"
}


# MAIN

environment_checker
facelib_setup

7. Atualização¶

7.1. Atualização do PSBio¶

7.1.1. Atualização da Versão 4¶

Descompacte os arquivos atualizados em um diretório temporário: gbs-psbio-server<versão>.tar.gz

Pare o Módulo PSBio:

service psbio stop

Renomeie a versão anterior do módulo PSBio, mantendo-o até que a atualização seja finalizada com sucesso:

mv /var/lib/griaule/psbio/gbs-psbio-server.jar /var/lib/griaule/psbio/gbs-psbio-server.jar.old

Se estiver migrando de uma versão anterior à 5.0 para uma versão 5.0 ou mais recente, é necessário realizar a migração da base local usando a ferramenta fornecida, o PSBio Database Migration Tool. Sua execução é realizada com o comando abaixo:

java -Dconfig.path={path}/pdbm.properties -jar {path}/psbio-database-migration-1.0.2-exec.jar >>{path}/log.out 2>> {path}/log.err

Se necessário, consulte a seção Migração de Base para Versão 5.0 abaixo para maiores detalhes sobre esta ferramenta.

Instale a nova API do Módulo PSBio:

tar -xf gbs-psbio-server_<versão>.tar.gz
mv gbs-psbio-server.jar /var/lib/griaule/psbio

Note

Confira o arquivo config.properties com o modelo enviado para a última atualização.

Inicie o Módulo PSBio:

service psbio start

7.1.2. Migração de Base para Versão 5.0¶

Ao atualizar o PSBio de uma versão anterior à 5.0 para a versão 5.0 ou mais recente será necessário realizar a migração da base local. A Griaule fornece um ferramenta para realizar esta operação, o PSBio Database Migration Tool.

Descompacte o pacote em um diretório temporário do servidor. O pacote tem dois arquivos, o executável .jar e o arquivo de configuração pdbm.properties.

Os campos do arquivo de configuração são os seguintes:

debug

(booleano) Se habilitado, loga todas as ações realizadas. Padrão: false.

zookeeper.path

(string) Caminho do zookeper.

migration.batch-size

(inteiro) Número de transações trazidas em cada iteração. Padrão: 10000.

migration.transactions

(booleano) Habilita migração da tabela psbio_transactions. Padrão: true.

migration.transactions.include-finalized

(booleano) Habilita migração de transações finalizadas. Padrão: false.

Configure o arquivo pdbm.properties com os valores adequados e execute a ferramenta com o comando:

java -Dconfig.path={path}/pdbm.properties -jar {path}/psbio-database-migration-1.0.2-exec.jar >>{path}/log.out 2>> {path}/log.err

7.2. Procedimento de Rollback do Módulo PSBio¶

Caso a versão anterior ainda exista, /var/lib/griaule/psbio/gbs-psbio-server.jar.old:

Pare o Módulo PSBio:

service psbio stop

Remova a nova versão e renomeie a versão anterior do módulo PSBio:

rm -f /var/lib/griaule/psbio/gbs-psbio-server.jar
mv /var/lib/griaule/psbio/gbs-psbio-server.jar.old /var/lib/griaule/psbio/gbs-psbio-server.jar

Note

Confira o arquivo config.properties com o modelo anterior.

Inicie o Módulo PSBio:

service psbio start

Caso a versão anterior não esteja mais disponível, siga o procedimento de atualização usando o pacote da versão anterior.

7.3. Atualização do Módulo AC¶

7.3.1. Atualização da Versão 2¶

Descompacte o conteúdo da atualização gbs-spid-server<versão>.zip em um diretório temporário.

Pare o Módulo AC:

service spid stop
service spid-cp stop

Renomeie a versão anterior do módulo AC e Control Panel, mantendo-os até que a atualização seja finalizada com sucesso:

mv /var/lib/griaule/spid/gbs-spid-server.jar /var/lib/griaule/psbio/gbs-spid-server.jar.old
mv /var/lib/griaule/spid/gbs-spid-controlpanel.jar /var/lib/griaule/spid/gbs-spid-controlpanel.jar.old

Instale a nova versão do Módulo AC e Painel de Controle:

unzip gbs-spid-server_<versão>.zip
mv gbs-spid-server.jar /var/lib/griaule/spid
mv gbs-spid-controlpanel.jar /var/lib/griaule/spid

Note

Conferir os arquivos config.properties e controlpanel.properties com os modelos enviados para a última atualização.

Inicie o Módulo AC:

service spid start
service spid-cp start

7.4. Procedimento de Rollback do Módulo AC¶

Caso a versão anterior ainda exista, /var/lib/griaule/psbio/gbs-spid-server.jar.old e /var/lib/griaule/spid/gbs-spid-controlpanel.jar.old:

Pare o Módulo AC:

service spid stop
service spid-cp stop

Remova a nova versão e renomeie a versão anterior do módulo AC:

rm -f /var/lib/griaule/spid/gbs-spid-server.jar
rm -f /var/lib/griaule/spid/gbs-spid-controlpanel.jar
mv /var/lib/griaule/spid/gbs-spid-server.jar.old /var/lib/griaule/spid/gbs-spid-server.jar
mv /var/lib/griaule/spid/gbs-spid-controlpanel.jar.old /var/lib/griaule/spid/gbs-spid-controlpanel.jar

Note

Confira os arquivos config.properties e controlpanel.properties com o modelo anterior.

Inicie o Módulo AC:

service spid start
service spid-cp start

Caso a versão anterior não esteja mais disponível, siga o mesmo procedimento de atualização com os pacotes da versão anterior.