Manual de Integração API SSL PAX

1. Objetivo

Este documento apresenta as funcionalidades de métodos da biblioteca de comunicação, GSurf RSA
SSL, proporcionando melhor compreensão da biblioteca.

1.1 Fluxo

Para melhor compreensão do funcionamento da biblioteca, é apresentado no capítulo 2 os fluxogramas
de funcionamento da biblioteca.

1.2 Uso dos métodos

Os métodos da biblioteca são divididos em 3 partes: Retorno, nome do método e parâmetros.
O retorno, se houver, indica se o método foi executado com sucesso ou se ocorreu algum erro em seu
processo interno, para saber mais sobre os retornos vá ao capítulo 4.

Método é a assinatura do mesmo, basta chamá-lo como descrito nesta documentação, para mais
detalhes vá ao capítulo 3.

Os parâmetros são os dados necessários para que a biblioteca funcione corretamente, para saber quais
os parâmetros necessários para cada método, vá ao capítulo 3.

1.3 Retorno de erros

Alguns métodos utilizados na biblioteca, retornam possíveis erros durante o processo de uso. Para
facilitar o uso da biblioteca, foi criada uma tabela de Enum’s 1 com o código de cada erro. Esta tabela
está no capítulo 4.

2. Fluxograma

Para o perfeito funcionamento da biblioteca, é necessário seguir uma sequência de fluxos, que serão explicados abaixo.

2.1 Conexão/Desconexão

Para que a conexão seja efetuada, é necessário que a biblioteca tenha acesso livre os

IP:

18.231.194.64/26

Portas:

443/UDP
443/TCP
55844/TCP
55845/TCP

E consultas DNS na Internet.

Na figura 2.1 é apresentado o fluxo a ser seguido para efetuar uma conexão segura
com a lib GSurf TLS SSL.

Quando necessário efetuar uma conexão para transmitir dados de forma segura, siga a
seguinte sequência:
1. gsurf_connect_ssl.
2. gsurf_write_ssl e ou gsurf_read_ssl para escrita e leitura.
3. gsurf_disconnect.
4. caso a biblioteca não seja mais utilizada, chame a função gsurf_free_ssl, para liberar memória ram.

3. Métodos

A API SSL PAX Prolin possui no total 5 métodos disponíveis para uso, sendo que para o uso de alguns
métodos, é necessário que outros sejam inicializados anteriormente. Nas sessões a seguir serão
discutidos os métodos um a um, seguindo sua sequência de utilização.

3.1 Conexão

Este método efetua uma conexão SSL com o servidor da GSurf.

A assinatura do método é:

GSURF_ERRORSSL gsurf_connect_ssl(const char *serviceName, const char *host);

O método retorna um enum, como descrito no capítulo 4, e recebe por parâmetros os seguintes dados:

serviceName: O nome do serviço que se deseja conectar. Esta informação deve ser obtida com o
comercial da Gsurf.

host: O endereço IP do host, que possui duas possibilidades:

IP onde roda o Servidor GW Local GSurf (não se aplica a plataforma PAX Prolin).
NULL a biblioteca assume como padrão o serviço hospedado e passa pelo GW TLS Gsurf.

3.2 Timeout

É possível alterar as configurações de timeout de leitura de dados da
biblioteca. Por padrão o método gsurf_read_ssl aguarda 30 segundos, caso não
chegue dados, a função retorna que não houve erros NO_SSL_ERROR e 0 bytes no campo de retorno
de bytes.

Para fazer a alteração utilize o método gsurf_set_timeout. A assinatura do método é:

void gsurf_set_timeout(int timeout);

O método recebe por parâmetros o seguinte dado:

timeout: inteiro positivo em segundos.

3.3 Envio

Método de escrita de dados na conexão. Para que este método funcione é necessário que a conexão já
esteja estabelecida, como descrito na seção 3.1.

A assinatura do método é:

GSURF_ERRORSSL gsurf_write_ssl(void *buffer, int bufferLength, int *bytesProcessed);

O método retorna um enum, como descrito no capítulo 4, e recebe por parâmetros os seguintes dados:

buffer: Ponteiro para o início do buffer a ser enviado.

bufferLength: Tamanho do buffer a ser enviado, em bytes.

bytesProcessed: Ponteiro de saída para a quantidade de bytes enviados.

3.4 Recebimento

Método de leitura de dados da conexão. Para que este método funcione é necessário que a conexão já
esteja estabelecida, como descrito na seção 3.1.

A assinatura do método é:

GSURF_ERRORSSL gsurf_read_ssl(void *buffer, int bufferLength, int *bytesProcessed);

O método retorna um enum, como descrito no capítulo 4, e recebe por parâmetros os seguintes dados:

buffer: Ponteiro para o início do buffer de leitura.

bufferLength: Tamanho do buffer de leitura, em bytes.

bytesProcessed: Ponteiro de saída para a quantidade de bytes lidos.

3.5 Desconexão

Método responsável por terminar, de forma segura, a conexão com o servidor.
A assinatura do método é:

GSURF_ERRORSSL gsurf_disconnect_ssl();

O método retorna um enum, como descrito no capítulo 4.

3.6 Memória

No processo de conexão, leitura e gravação, alguns dados ficam persistentes na memória, afim de
melhorar a performance da conexão SSL. Caso a conexão não seja mais necessária por um longo
período, ou simplesmente o programa será finalizado, é altamente recomendável que esta função seja
chamada antes do término da aplicação, liberando assim de forma adequada os dados persistentes em
memória.

A assinatura do método é:

void gsurf_free_ssl();

3.7 Versão

É possível pegar a versão da biblioteca que está sendo utilizada.

A assinatura do método é:

const char *gsurf_get_version();

4. Tabela de retornos

Tabela de retorno para todas as funções.

Erro	Código	Descrição
NO_SSL_ERROR	0	Quando não ocorrem erros.
ERROR_OPEN_SSL	1	Quando ocorre erro ao iniciar socket UDP.
ERROR_ON_ADDR	2	Ocorre ao atribuir o IP ao socket UDP.
ERROR_WRITE_UDP	3	Ocorre quando o socket UDP é interrompido no envio dos dados.
ERROR_READ_UDP	4	Ocorre quando o limite de espera para a recepção de dados UDP é atingido. O erro ocorre possivelmente pela conexão ser muito ruim ou está desconectado.
ERROR_GET_SERVER_IP	5	Algum erro ocorreu na criptografia proprietária.
ERROR_MESSAGE	6	Algum erro ocorreu na criptografia proprietária.
ERROR_GET_SERVER_PORT	7	Algum erro ocorreu na criptografia proprietária.
ERROR_CREATE_SSL_CONTEXT	8	Erro ao criar o contexto SSL.
ERROR_CONFIG	9
ERROR_OPEN_FILE	10	Erro ao abrir o arquivo de certificado. Este erro normalmente ocorre quando o certificado não está gravado na unidade de armazenamento, ele também pode ocorrer na abertura do arquivo de tokens, pelo mesmo motivo.
ERROR_OPEN_CERTIFICATE	11	Erro ao abrir o arquivo de certificado. Este erro normalmente ocorre quando o certificado não está gravado na unidade de armazenamento, ele também pode ocorrer na abertura do arquivo de tokens, elo mesmo motivo.
ERROR_DECODE_CERTIFICADE	12	Este erro ocorre possivelmente por este certificado não ser deste dispositivo, ou por lteração de hardware que afetaram a geração de fingerprint.
ERROR_INVALID_CERTIFICADE	13	Erro ao verificar a chave privada do certificado.
ERROR_OPEN_TCP_SOCKET	14	Erro ao iniciar uma conexão TCP.
ERROR_TCP_CONNECTION	15	Erro ao estabelecer uma conexão TCP.
ERROR_HANDSHAKE_SSL	16	Erro ao estabelecer conexão SSL, favor verificar certificado e logs do servidor.
ERROR_CRITICAL_HANDSHAKE_SSL	17	Verificar com o desenvolvimento.
ERROR_SSL_WRITE	18	Falha na conexão SSL. Possivelmente desconectado no momento do envio dos dados.
ERROR_SSL_READ	19	Falha na conexão SSL. Possivelmente desconectado no momento do recebimento dos dados.
ERROR_SSL_SHUTDOWN	20	Verificar com o desenvolvimento.
ERROR_MEMORY_ALLOCATE	21	Erro ao alocar dados na memória RAM. Possível fim de memória RAM, ou a informação de amanho fornecida para aplicação é incorreta.
ERROR_SERVICE_CONNECT	22	Erro ao se conectar com o serviço. Favor verificar se o serviço está em execução.
ERROR_AES_ENCRYPTING	23	Verificar com o desenvolvimento.
ERROR_AES256	24	Erro ao usar o sistema de criptografia de arquivos. Possível problema nos tokens.
ARROR_AES_DECRYPT	25	Erro ao usar o sistema de criptografia de arquivos. Possível problema nos tokens na hora de decriptar.
ERROR_MALFORMED_IP	26	Erro ao passar os dados de conexão local, possível que IP informado esteja incorreto em seu tamanho.
ERROR_RFC1918	27	Erro ao passar os dados de conexão local, possível que o IP informado não esteja de acordo com a RFC 1918.
ERROR_NO_CERTIFICATE	28	Ocorre quando o certificado não está presente. Portanto, é necessário executar as instruções de instalação do certificado.
ERRO_NO_SSL_CONNECTION	29	Erro de conexão SSL. Ocorre por tentar enviar informações sem que a conexão esteja estabelecida.
ERROR_CONFIG_AUTH	30	Erro durante a autenticação (Windows).
ERROR_SAVE_CERTIFICATE	31	Não foi possível salvar o certificado no dispositivo.
ERROR_DNS	33	Erro ao resolver um endereço DNS.
ERROR_OPEN_UDP_SOCKET	34	Erro ao iniciar um socker UDP.
ERROR_SERVER_DEFINITION	35	Erro ao definir o endereço do servidor.
ERROR_AUTHENTICATION	36	Erro durante o processo de autenticação. Pode ser causado por token errado ou dessincronizado.
ERROS_UNKNOWN_ERROR	37	Erro desconhecido.
ERROE_EMPTY_MESSAGE	38	A mensagem recebida do servidor está vazia e deve ser descartada.
ERROR_MOUNT	39	Erro ao montar a partição do dispositivo.
ERROR_INVALID_OTP	41	Não aplicado na versão Linux x86/x64.

5. Versões

5.1 Versão do documento.

Versão	Autor	Descrição	Data
1.0	Thiago J. Silveira Mateus Fornari B. José B. Pereira	Versão de Apreciação.
1.1.5759	José B. Pereira Lays Rodrigues de D.	Revisão.
1.2	Thiago J. Silveira	Incluído método de configuração de TimeOut.
1.3	Thiago J Silveira	Adicionado documentação da função que retorna a versão da biblioteca.
1.4	Thiago J. Silveira	Revisão.	27/10/2016
1.5	Thiago J. Silveira Raphael Brito	Revisão.	19/11/2021

5.2 Versões PAX Prolin Testadas

Firmware	SDK
2.4.104.6194R, 2.4.85	2.8.13
2.4.164.8947R	2.8.13
2.4.179.9805R	2.8.13