Configurações de Rede

Alterar as configurações de rede local e, além disso, se conectar a outras redes com OpenVPN.

Alterar configurações de rede

Altera as configurações de rede do equipamento. O método HTTP usado é o POST.

POST /set_system_network.fcgi

Parâmetros

  • ip (string) : Texto representando o endereço IP que o equipamento deve assumir. Exemplo: "192.168.0.33".
  • netmask (string) : Texto representando a máscara de rede que o equipamento deve assumir. Exemplo: "255.255.255.0".
  • gateway (string) : Endereço IP do gateway da rede. Exemplo: "192.168.0.1".
  • custom_hostname_enabled (bool) : Habilita configuração para criar um hostname customizado para o dispositivo. Valores: "true" para habilitar e "false" para desabilitar.
  • device_hostname (string) : Quando custom_hostname_enabled está habilitado, este parâmetro deve receber o hostname customizado pelo usuário. Exemplo: "ControlID". Quando custom_hostname_enabled está desabilitado, o hostname padrão do dispositivo será : "CID-" + serial do dispositivo. Exemplo: "CID-0M0200-C0FF33".
  • web_server_port (int) : Número da porta de comunicação do Acesso. Exemplo: 80.
  • ssl_enabled (bool) : Habilita a certificação por SSL do servidor web. Valores: "true" para habilitar e "false" para desabilitar.
  • self_signed_certificate (bool) : Habilita a configuração parar usar certificado auto-assinado. Valores: "true" para habilitar certificado auto-assinado e "false" habilitar SSL com certificado de terceiro.
  • dns_primary (string): Representa o DNS primário do dispositivo. Padrão: "8.8.8.8".
  • dns_secondary (string): Representa o DNS secundário do dispositivo. Padrão: "8.8.4.4".

Resposta

  • Esta chamada não possui retorno.

Exemplo de requisição

Alterar o endereço IP, a máscara de rede, gateway e porta do equipamento:

$.ajax({
    url: "/set_system_network.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        ip: "192.168.0.33",
        netmask: "255.255.255.0",
        gateway: "192.168.0.1",
        custom_hostname_enabled: true,
        device_hostname: "ControlID",
        web_server_port: 80,
        ssl_enabled: false,
        self_signed_certificate: true,
        dns_primary: "1.1.1.1",
        dns_secondary: "1.1.4.4"
    })
});

SSL

SSL (Secure Sockets Layer) é um tipo de protocolo de segurança que estabelece uma conexão criptografada entre um servidor web e um navegador, garantindo que as informações transmitidas pela internet permaneçam privadas e seguras. A seguir, demonstra-se o processo de geração de certificados SSL e adição desses aos equipamentos da linha de controle de acesso da Control iD. Ao fim, apresenta-se a requisição HTTP POST que permite a realização desse mesmo processo.

Configuração de certificado SSL

  1. Faça o download da versão Light do OpenSSL (opção “Win64 OpenSSL v1.1.1t Light“, para Windows 64 bits, ou “Win32 OpenSSL v1.1.1t Light“, para Windows 32 bits);
  2. Execute o instalador, deixando o diretório padrão para finalização da instalação desta biblioteca;
  3. Abra o "Prompt de Comando" como "administrador" e vá para o diretório padrão onde o OpenSSL foi instalado;
    Exemplo (linha de comando): cd C:\Program Files\OpenSSL-Win64\bin
  4. Execute o comando a seguir e preencha as informações solicitadas, conforme orientações passadas a seguir;
    Exemplo (linha de comando): openssl req -x509 -newkey rsa:1024 -nodes -keyout domain.key -out domain.pem Preenchimento dos campos:
    • Insira uma sigla referente ao seu país no campo "Country Name", conforme apresentado no link a seguir (para Brasil, digite BR): SSL Certificate Country Codes
    • Insira uma sigla referente ao seu estado/província no campo "State or Province Name" (para São Paulo, digite SP);
    • Insira o nome da sua localidade/cidade no campo "Locality name/City";
    • Insira o nome da sua empresa no campo "Organization Name";
    • Insira o nome único da sua organização no campo "Organizational Unit Name";
    • Insira o IP do seu equipamento no campo "Common Name";
    • Insira um endereço de e-mail no campo "Email Address".
  5. No final, os dois arquivos (um .pem e um .key) gerados terão de ser combinados. Para isto, execute o comando a seguir;
    Exemplo (linha de comando): type domain.key,domain.pem > final.pem (para ambiente Linux: cat domain.key domain.pem > final.pem)
  6. Após isso, feche o "Prompt de Comando", acesse o diretório padrão do OpenSSL e abra a pasta bin (C:\Program Files\OpenSSL-Win64\bin);
  7. Colete o arquivo chamado final.pem;
  8. Com isso, acesse a interface Web do equipamento digitando o IP dele no seu browser;
  9. Quando acessa-lá, selecione a opção "Configurações", presente no menu à esquerda;
  10. Procure pela opção "Rede", selecione-a e habilite a opção "SSL". No campo "Certificado", selecione o arquivo final.pem apresentado no passo 7, confirme e salve as configurações;
  11. Depois de realizar os passos anteriores, basta recarregar a página e acessar o equipamento colocando o protocolo "https" na URL.

POST /ssl_certificate_change.fcgi

Atenção: deve-se habilitar a criptografia por SSL pela requisição para o endpoint set_system_network.fcgi para que o certificado seja configurado. Além disso, o certificado deve estar no formato PEM e ser gerado conforme instruções acima.

Parâmetros

  • Certificado, em formato binário, que será adicionado ao servidor web.

Resposta

  • Esta chamada não possui retorno.

Exemplo de requisição

Adicionar certificado SSL ao servidor web do equipamento:

$.ajax({
    url: "/ssl_certificate_change.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/octet-stream',
    data: [bytes do certificado com extensão .pem]
});

OpenVPN

Altera as configurações de rede para utilização do utilitário da OpenVPN através do endpoint /set_vpn_information. Para o funcionamento correto, é necessário o carregamento de um arquivo de configuração, no endpoint /set_vpn_file, em formato .conf, contendo nele os certificados, chaves e/ou credenciais necessárias para o acesso. O arquivo também pode ser carregado junto de um arquivo em formato .zip, contendo os certificados (.crt), chaves (*.key) e/ou credenciais em arquivos distintos. Exemplos de parametrização do arquivo de configuração podem ser obtidos através do endpoint /get_vpn_file. Além disso, para controle de status e conexões exitem três endpoints: /get_vpn_information, que retorna as configurações de conexão; /get_vpn_status, que verifica o estado da conexão, e /has_vpn_file, que verifica se já existe algum arquivo de configuração presente.

Alterar configurações de OpenVPN

Altera as configurações de rede para utilização do utilitário da OpenVPN. O método HTTP usado é o POST.

POST /set_vpn_information.fcgi

Parâmetros

  • enabled (bool) : Representa se a VPN está habilitada. Padrão: "false".
  • login_enabled (bool) : Representa se a VPN é acessada a partir de login e senhas manuais. Padrão: "false".
  • login (string) : Representa o usuário do login utilizado caso login_enabled estiver ativado. Exemplo : "Admin".
  • password (string) : Representa a senha do login utilizado caso login_enabled estiver ativado. Exemplo : "Admin".

Resposta

  • Esta chamada não possui retorno.

Exemplo de requisição

Habilita o utilitário e permite atualizar usuário e senha manual:

$.ajax({
    url: "/set_vpn_information.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        "enabled": true,
        "login_enabled": true,
        "login": "Admin",
        "password": "Admin"
    })
});

Altera os arquivos de acesso a VPN

Altera os arquivos de carregamento do utilitário, podendo ser um arquivo em formato .conf ou um arquivo em formato .zip contendo todos os dados necessários. O método HTTP usado é o POST.

POST /set_vpn_file.fcgi

Parâmetros

  • file_type (string) : Identificador do tipo de arquivo enviado. Valores: "zip" para arquivos .zip e "config" para arquivos de configuração .conf. Esse parâmetro é passado na Query String.

Resposta

  • Esta chamada não possui retorno.

Exemplo de requisição

Esta requisição irá definir o arquivo de configuração utilizado na VPN.

$.ajax({
    url: "/set_vpn_file.fcgi?file_type=zip&session=" + session,
    type: 'POST',
    contentType: 'application/octet-stream',
    data: [bytes do arquivo VPN]
});

Receber os arquivos de exemplo

Recebe os arquivos de exemplo de parametrização do arquivo de configuração do utilitário. O método HTTP usado é o GET.

GET /get_vpn_file.fcgi

Parâmetros

  • Esta chamada não possui parâmetros.

Resposta

  • Arquivo em formato zip.

Exemplo de requisição

Esta requisição retorna o arquivo de configuração utilizado na VPN.

$.ajax({
    url: "/get_vpn_file.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/octet-stream'
});

Receber configurações de OpenVPN

Recebe as configurações de rede do utilitário da OpenVPN. O método HTTP usado é o GET.

GET /get_vpn_information.fcgi

Parâmetros

  • Esta chamada não possui parâmetros.

Resposta

  • enabled (bool) : Representa se a VPN está habilitada. Padrão: "false".
  • login_enabled (bool) : Representa se a VPN é acessada a partir de Login e senhas manuais. Padrão: "false".
  • login (string) : Representa o usuário do login utilizado caso login_enabled estiver ativado. Exemplo : "Admin".
  • password (bool) : Representa se há senha de login configurada caso login_enabled estiver ativado. Exemplo : "true"

Exemplo de requisição

Esta requisição retorna as configurações utilizadas na OpenVPN.

$.ajax({
    url: "/get_vpn_information.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json'
});

Exemplo de resposta

{
    "enabled": true,
    "login_enabled": false,
    "login": "Admin",
    "password": true
}

Receber Status da conexão OpenVPN

Recebe os status de rede do utilitário da OpenVPN. O método HTTP usado é o GET.

GET /get_vpn_status.fcgi

Parâmetros

  • Esta chamada não possui parâmetros.

Resposta

  • status (int) : Representa um dos estados abaixo do OpenVPN.
    • 0 (connected) : Representa que o OpenVPN está conectado.
    • 1 (auth_failed) : Representa que o servidor OpenVPN está rejeitando a conexão durante o estágio de autenticação.
    • 2 (ca_missing) : Representa que está faltando a unidade certificadora para aprovação do OpenVPN.
    • 3 (ca_failed) : Representa que o servidor OpenVPN não conseguiu verificar unidade certificadora.
    • 4 (crt_key_missing) : Representa que pode estar faltando o certificado público, a chave privada ou ambos.
    • 5 (crt_failed) : Representa que a chave certificadora pública não foi aprovada pelo servidor do OpenVPN
    • 6 (key_failed) : Representa uma falha na autenticação pelo servidor OpenVPN utilizando a chave privada.
    • 7 (tls_failed) : Representa falha no protocolo de segurança TLS.
    • 8 (disconnected) : Representa que o OpenVPN está desabilitada.
    • 9 (trying_to_connect) : Representa que o OpenVPN está ativo porém ainda não atingiu nenhum dos status mapeados.
    • 10 (no connection) : Representa que a rede está desconectada.

Exemplo de requisição

Esta requisição retorna o status da conexão OpenVPN.

$.ajax({
    url: "/get_vpn_status.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json'
});

Exemplo de resposta

{
    "status": "0"
}

Confirmar a existência do arquivo de configuração

Recebe a confirmação da existência do arquivo de configuração no dispositivo para o utilitário da OpenVPN. O método HTTP usado é o GET.

GET /has_vpn_file.fcgi

Parâmetros

  • Esta chamada não possui parâmetros.

Resposta

  • has_file (bool) : Representa se já existe um arquivo de configuração OpenVPN no dispositivo.

Exemplo de requisição

Esta requisição retorna o status do arquivo OpenVPN.

$.ajax({
    url: "/has_vpn_file.fcgi?&session=" + session,
    type: 'GET',
    contentType: 'application/json'
});

Exemplo de resposta

{
    "has_file": true
}

Habilitar 802.1X

É possível configurar o equipamento como suplicante e habilitar o protocolo 802.1X de autenticação de sua porta de rede. O método utilizado é o PEAP.

POST /configure_802_1X.fcgi

Parâmetros

  • enabled (bool): Determina se a autenticação por 802.1X está ativada ou não;
  • login (string): Credencial de nome de usuário;
  • password (string): Credencial de senha de usuário;
  • inner_auth (int): Autenticação interna. 0: MS-CHAPv2. 1: MD5. 2: GTC.

Resposta

  • Esta chamada não possui retorno.

Exemplo de requisição

Habilitar 802.1X com credenciais de login "testing" e senha "password", e autenticação interna por MS-CHAPv2:

$.ajax({
    url: "/configure_802_1X.fcgi?session=" + session,
    type: 'POST',
    contentType: 'application/json',
    data: JSON.stringify({
        enabled: true,
        login: "testing",
        password: "password",
        inner_auth: 0
    })
});