Autenticação Mútua¶
Um papel da segurança é de garantir que somente usuários legítimos tenham o acesso aos recursos e informações necessárias para realizar suas funções. A autenticação faz parte deste controle de acessos, ao validar a identidade de entidades. Ao mesmo tempo, outro papel da segurança é garantir que uma entidade acesse os recursos e informações legítimas, evitando assim situações como o envio de informações a servidores fraudulentos, por exemplo.
Autenticação Mútua é o processo no qual duas entidades fazem a autenticação uma da outra. Numa comunicação cliente-servidor, o cliente deve provar sua identidade ao servidor e o servidor deve provar sua identidade ao cliente. Dessa forma, cada entidade pode garantir que está se comunicando com um interlocutor legítimo.
A autenticação mútua protege o acesso aos dados que a aplicação acessa na dojot e, por consequência, protege o acesso ao dados dos usuários dessa aplicação. Ela faz isso garantindo que somente as próprias aplicações registradas possam acessar os dados e funcionalidades da plataforma. Adicionalmente, ela assegura que a plataforma que a aplicação esteja acessando é legítima, ou seja, que nenhum atacante possa se passar pela plataforma e obter dados da aplicação e de seus usuários.
A dojot oferece um serviço de autenticação mútua através de uma imagem Docker. Esse serviço é executado na plataforma e pode ser acessado usando as interfaces adequadas.
Table of Contents
Usando a Autenticação Mútua¶
Aplicações podem acessar as funcionalidades da dojot para interagir com seus componentes e com os dispositivos conectados. Para que uma aplicação possa garantir que está se comunicando com uma plataforma legítima (e vice-versa), ela deve fazer o uso da funcionalidade de autenticação mútua que a dojot fornece. Esse é um processo simples e seu uso requer apenas 3 passos a serem seguidos:
Registro da aplicação. Quando uma aplicação é registrada na dojot, ela recebe um identificador e uma chave que deve ser mantida em segredo. Essa chave é usada para autenticar a aplicação na plataforma.
Autenticação. No início da comunicação entre a aplicação e a dojot, a aplicação inicia um processo de handshake no qual as duas entidades irão trocar informações de forma a garantir que são legítimas.
Uso da plataforma. Ao acessar as interfaces da dojot, a plataforma informa o identificador da sessão que obteve no momento da autenticação. Com isso, a plataforma pode verificar que a aplicação realizou o processo de autenticação mútua
Registro de aplicação¶
Uma aplicação que se registra na dojot irá receber um identificador e uma chave que deve ser mantida em segredo. O registro indica que uma aplicação irá se comunicar e utilizar funcionalidades da plataforma.
Atualmente, o método utilizado para fazer o registro de uma aplicação é o uso de uma interface REST. Após fazer a requisição para o registro, a aplicação receberá um identificador único e uma chave. A API é descrita abaixo.
REGISTER COMPONENT - Registro de nova aplicação
POST /kerberos/registerComponent
Response 200
Headers
Content-Type: application/json
Body
{
"AppId": "0001020304050607",
"AppKey": "000102030405060708090a0b0c0d0e0f000102030405060708090a0b0c0d0e0f"
}
O identificador e a chave recebidos serão usados no momento da autenticação com a dojot. Para isso, uma biblioteca cliente é fornecida para realizar o processo de autenticação (disponível em github.com/dojot/ma-client-libs) e, portanto, a biblioteca deverá ter conhecimento sobre os valores do identificador e chave. O arquivo https://github.com/dojot/ma-client-libs/kerberos/src/protocol/unique.h é utilizado para armazenar esses valores e será usado pela biblioteca no momento da autenticação.
Authenticação¶
Ao se comunicar com a dojot, a aplicação deve realizar a autenticação mútua. Esse processo é feito através da biblioteca fornecida em github.com/dojot/ma-client-libs. Ao utilizar a biblioteca, 3 passos devem ser seguidos:
Inicializar a biblioteca com os endereços do servidor
Registrar a função de callback
Chamar a função de autenticação mútua
Inicialização da Biblioteca¶
A inicialização informa à biblioteca as URLs que serão usadas ao realizar a autenticação mútua. A função a ser utilizada é descrita abaixo:
Initialize Kerberos
errno_t initializeKerberos(uint8_t* host, uint8_t hostLength, uint8_t* uriRequestAS, uint8_t requestASLength, uint8_t* uriRequestAP, uint8_t requestAPLength)
Os argumentos utilizados na função são descritos a seguir.
host - URL principal da plataforma
hostLength - Tamanho da string de host
uriRequestAS - Endpoint de acesso de requestAS
requestASLength - Tamanho da string de requestAS
uriRequestAP - Endpoint de acesso de requestAP
requestAPLength - Tamanho da string de requestAP
O trecho de código a seguir mostra um exemplo de como a função pode ser utilizada.
char* host = "http://localhost:8000/"; // dojot URL
char* reqAS = "kerberos/requestAS";
char* reqAP = "kerberos/requestAP";
errno_t ret = initializeKerberos(host, strlen(host), reqAS, strlen(reqAS), reqAP, strlen(reqAP));
Registro de Callback¶
No processo de autenticação mútua, a biblioteca se comunica com o servidor e verifica os dados recebidos. Se algum erro ocorrer durante esse processo, a biblioteca vai chamar uma função de callback.
Essa função de callback é implementada pelo usuário da biblioteca e deve ser registrada antes do processo de autenticação. A função de callback pode conter código para tratamento de erro ou logs, por exemplo.
Set Callback
errno_t setCallback(void (*callback)(int))
O código a seguir mostra um exemplo de como a função de callback pode ser criada e registrada.
void errorCallback(int err){
// Error handling and logging code
}
errno_t ret = setCallback(&errorCallback);
Chamar a função de autenticação mútua¶
Depois de inicializar a biblioteca com os endereços da plataforma e registrar a função de callback, a biblioteca está pronta para realizar o processo de autenticação mútua. A função que é usada para realizar o processo é mostrada abaixo.
errno_t executeKerberosHandshake()
O código abaixo mostra um exemplo de como a função pode ser usada
errno_t ret = executeKerberosHandshake();
Acessando as API da plataforma dojot¶
Após o processo de autenticação mútua ser concluído, a aplicação poderá enviar um dado adicional nas chamadas às interfaces da plataforma. Esse dado é o identificador de sessão de autenticação mútua e é enviado por meio de um header HTTP.
A seguir é apresentado um exemplo de uma chamada para uma API da dojot onde o identificador de sessão da autenticação mútua também é enviado.
GET /device HTTP/1.1
Host: localhost:8000
ma-session-id: a4cdad05441940c5c07ee9f55b8fafbdc0eba14afce449c9c9ec052bb20f50f4