Especificações técnicas

Requisitos mínimos

Componente	Requisito
SO	Linux x86_64 (Ubuntu 20.04+)
CPU	4 núcleos
Memória	4 GB RAM
Disco	1 GB de espaço livre

Recomendado para produção

Componente	Recomendação
SO	Ubuntu 24.04 LTS
CPU	8+ núcleos
Memória	8 GB+ RAM
Rede	Conexão de baixa latência
Armazenamento	SSD para logs

Requisitos de rede

Conectividade de saída

O serviço deve conseguir alcançar:

• Os servidores de licença da Facephi (para a validação da licença)

Acesso ao servidor de licenças

IPs e portas requeridos:

IP	Porta	Protocolo
52.223.22.71	443	TCP/IP
35.71.188.31	443	TCP/IP
75.2.113.112	443	TCP/IP
99.83.149.57	443	TCP/IP

URLs requeridas:

• https://api.cryptlex.com:443

• https://api.eu.cryptlex.com:443

Configure as regras do firewall para permitir o tráfego HTTPS de saída para estes endpoints.

Arquitetura de implantação

IAD Service opera como uma API REST sem estado que avalia payloads de captura e retorna um contrato público de Facephi:

Cliente → IAD Service (Port 6982)

• Podem ser executadas várias instâncias do serviço atrás de um balanceador de carga

• Cada instância mantém os recursos internos necessários para o processamento de capturas

• O serviço não armazena estado de sessão

Compatibilidade da API pública

Aviso de mudança incompatível (2.0.0) A API REST pública exposta pela versão 2.0.0 quebra a compatibilidade com a série 1.x.x. Isso afeta o contrato de comunicação, não apenas a documentação. As integrações devem migrar as rotas dos endpoints, os nomes dos campos multipart e as regras de análise das respostas corretas.

Área de Integração	1.x.x	2.0.0
Endpoint de Liveness	/api/v1/iad/check-capture	/api/v1/iad/liveness/evaluate
Endpoint de extração	/api/v1/iad/extract-image	/api/v1/iad/extract
Campo da solicitação multipart	file	capture
Payload correto de Liveness	Campos privados herdados	Campos públicos de Facephi

Mitigação experimental de ataques de repetição (replay)

O serviço pode aplicar uma janela de vigência (freshness window) aos payloads de captura de entrada. Essa proteção experimental está desabilitada por padrão.

• Ative-a com FACEPHI_IAD_REPLAY_ATTACK_CHECKER_ENABLED=true

• Ajuste a janela de vigência com FACEPHI_IAD_REPLAY_ATTACK_TOLERANCE_TIME=<seconds>

• Janela de vigência padrão: 300 segundos

• Aplica-se aos endpoints de processamento de capturas como POST /api/v1/iad/liveness/evaluate e POST /api/v1/iad/extract

• Quando a janela de vigência é excedida, a API pública retorna HTTP 400 com message igual a Replay attack detected

Essa funcionalidade é configurada na inicialização por meio de variáveis de ambiente. Não faz parte de config.json nem é exposta por meio de GET|POST /api/v1/iad/config.

Autenticação JWT

A autenticação JWT pode ser habilitada na inicialização por meio de config.json ou por meio de variáveis de ambiente FACEPHI_IAD_REST_AUTH_*.

• Chaves de inicialização suportadas: auth_enabled, auth_jwt_secret, auth_accept_authorization_header, auth_accept_api_key_header, auth_api_key_header_name

• GET /api/v1/iad/config omite essas chaves da visualização pública de configuração

• POST /api/v1/iad/config rejeita essas chaves e não pode ser usado para rotacionar a configuração de autenticação JWT em tempo de execução

Características de desempenho

Métrica	Valor típico
Latência	< 100ms
Desempenho (throughput)	Depende do dimensionamento do serviço e da capacidade de processamento de capturas
Conexões simultâneas	Limitadas por number_of_threads e engine_pool_size
Tamanho máximo da solicitação	Configurável por meio de client_max_body_size

Considerações de segurança

• Implante por trás de um proxy reverso ou de um gateway de API (API gateway)

• Habilite SSL/TLS para todas as comunicações

• Priorize injetar auth_jwt_secret por meio de variáveis de ambiente ou de um gerenciador de segredos em vez de incluí-lo em arquivos

• Proteja o arquivo de licença com as permissões adequadas (chmod 644)

• Use regras de firewall para restringir as conexões de entrada

Mensagens de erro normalizadas por Facephi

Para POST /api/v1/iad/liveness/evaluate, as falhas de validação de captura são normalizadas para valores públicos de message, incluindo:

• NoneBecauseFaceTooClose

• NoneBecauseFaceNotFound

• NoneBecauseFaceCropped

• NoneBecauseFaceOccluded

• NoneBecauseTooManyFaces

• NoneBecauseAngleTooLarge

• NoneBecauseFaceTooSmall

• NoneBecauseFaceTooCloseToBorder

• NoneBecauseEyesClosed

• NoneBecauseImageDataError

• NoneBecauseLicenseError

• Replay attack detected

• ErrorProcessing

Para POST /api/v1/iad/extract, as falhas de análise e desencriptação do payload são retornadas como NoneBecauseImageDataError; as capturas expiradas rejeitadas pela proteção contra repetições retornam Replay attack detected; as falhas de extração não classificadas são retornadas como ErrorFacialImage.

As respostas corretas de Liveness são mapeadas para os campos públicos diagnostic, reason, probability, score, faceProbability opcional, sdkDuration e queueDuration. Os campos privados herdados e os payloads brutos do engine não são expostos.

Os valores possíveis para reason em POST /api/v1/iad/liveness/evaluate são:

• None

• Unknown

• UntrustedEnvironment

• SuspiciousActivity

• UntrustedDevice

• SdkIntegrityViolation

• UntrustedCorruptedPayload

• UntrustedContent

• UntrustedContentLowConfidence

O significado de cada valor público de reason é:

reason	Significado
None	A captura foi aceita como Live e não se aplica nenhum motivo de rejeição.
Unknown	O serviço não conseguiu atribuir a resposta a um motivo de rejeição público documentado.
UntrustedEnvironment	A captura foi rejeitada porque o ambiente de execução não é considerado confiável.
SuspiciousActivity	A captura foi rejeitada porque o dispositivo apresentou padrões de atividade associados a um ataque.
UntrustedDevice	A captura foi rejeitada porque não foi possível confiar que o dispositivo fosse o que afirma ser.
SdkIntegrityViolation	A captura foi rejeitada porque o SDK de captura ou suas bibliotecas parecem ter sido alterados.
UntrustedCorruptedPayload	A captura foi rejeitada porque o payload parece estar corrompido ou manipulado.
UntrustedContent	A captura foi rejeitada porque foi detectado um ataque de injeção.
UntrustedContentLowConfidence	A captura foi rejeitada porque o serviço detectou indícios de um ataque de injeção com menor confiança; ainda assim, deve ser tratada como uma rejeição.