SDK para C

  • 8 minuto(s) lido(s)
Prev Next

Este documento fornece uma visão geral de como utilizar o Segura® SDK para C, com base nos trechos de documentação fornecidos. O SDK simplifica o acesso a serviços Segura® como PAM (Gerenciamento de Acesso Privilegiado) e DSM (Gerenciamento de Segredos DevOps) em suas aplicações C.

Conceitos Principais

O SDK facilita a construção de aplicações robustas ao fornecer interfaces para gerenciar credenciais, dispositivos e segredos de aplicações. Um recurso importante é o uso de um cache local para reduzir o tempo de resposta das requisições. Todos os dados armazenados neste cache são criptografados para garantir a segurança.

Um objeto fundamental utilizado em todo o SDK é o objeto mapa. Este objeto serve como um contêiner de pares chave/valor, armazenando todas as informações necessárias ao chamar funções da API.

Usar o objeto mapa

O objeto mapa é essencial para passar parâmetros para a maioria das funções do SDK.

  • Criando um objeto mapa: para começar, você deve criar um novo objeto mapa usando a função segura_map_new(). Esta função retorna um ponteiro para o novo objeto mapa em caso de sucesso ou NULL em caso de erro. Se falhar, você pode verificar o motivo exato usando segura_last_error().
Segura_map *map = Segura_map_new();
if (map == NULL) {
    // Trate o erro usando Segura_last_error()
}
  • Adicionar itens ao mapa: use segura_map_add() para adicionar um novo par chave/valor a um objeto mapa existente. A função recebe o objeto mapa, a chave (const char*) e o valor (void*) como argumentos. Retorna 0 em caso de sucesso ou -1 em caso de erro, com detalhes do erro disponíveis via Segura_last_error().
Segura_map_add(map, "key_name", value_pointer);

Os exemplos demonstram como adicionar valores de string como URLs, client IDs, client secrets, hostnames, usernames, endereços IP, nomes de site, modelos, fabricantes e tipos.

  • Recuperar informações de um mapa: para obter o valor associado a uma chave específica de um mapa, use Segura_map_get(). Esta função recebe o objeto mapa e a chave (const char*) como entrada. Retorna o valor (void*) em caso de sucesso ou NULL em caso de falha.
void *value = Segura_map_get(map, "key_name");
  • Limpar um mapa: a função Segura_map_clear() remove todos os pares chave/valor de um objeto mapa. Isso é útil quando você precisa reutilizar um objeto mapa para diferentes parâmetros.
Segura_map_clear(map);
  • Liberar um objeto mapa: quando terminar de usar um objeto mapa, libere a memória alocada usando Segura_map_free(). Note que ela recebe um ponteiro para o ponteiro do mapa (Segura_map **).
Segura_map_free(&map);

Usar serviços PAM

O Segura® SDK para C permite gerenciar dispositivos e credenciais via serviços PAM.

Gerenciar Dispositivos

O objeto dispositivo fornece métodos para consultar e registrar dispositivos.

  • Criar um objeto cliente de dispositivo: semelhante ao objeto mapa, você precisa criar um objeto de acesso à API de dispositivos usando Segura_pam_device_new(). Esta função normalmente requer um objeto mapa contendo detalhes de conexão como url, client_id e client_secret.
Segura_map *map = Segura_map_new();
Segura_pam_device *dev = Segura_pam_device_new(map);
  • Criar ou atualizar um dispositivo: a função Segura_pam_device_save() é usada para criar um novo dispositivo ou atualizar um existente. Ela recebe o objeto de acesso ao dispositivo e um mapa contendo os parâmetros do dispositivo. Se um dispositivo correspondente for encontrado, ele é atualizado; caso contrário, um novo é criado. Os parâmetros obrigatórios para o mapa de entrada são hostname, ip, site, model, vendor e type. A função retorna 0 em caso de sucesso ou -1 em caso de erro.
Segura_map *params = Segura_map_new();
Segura_map_add(params, "hostname", "mydevice02");
Segura_map_add(params, "ip", "22.13.50.71");
int status = Segura_pam_device_save(dev, params);
  • Buscar um dispositivo registrado: para consultar um único dispositivo, use Segura_pam_device_get(). Esta função requer o objeto de acesso ao dispositivo e um mapa contendo os dados de identificação do dispositivo. O identificador necessário é normalmente o hostname ou o device id. Retorna um Segura_pam_device* em caso de sucesso ou -1 em caso de erro.
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "localhost");
Segura_pam_device *found_dev = Segura_pam_device_get(dev, identifier);
  • Listar dispositivos: a função Segura_pam_device_fetch() busca uma lista de dispositivos. Ela aceita o objeto de acesso ao dispositivo e um mapa de filtro opcional. O mapa de filtro pode incluir parâmetros como hostname, ip, type, vendor, model ou site para refinar os resultados. Um mapa de filtro vazio listará todos os dispositivos. A função retorna um mapa contendo a lista de dispositivos em caso de sucesso ou NULL em caso de erro.
Segura_map *filter = Segura_map_new();
Segura_map_add(filter, "type", "Server"); // Filtro opcional
Segura_map *found_devices = Segura_pam_device_fetch(dev, filter);
  • Desativar um dispositivo: para desabilitar um dispositivo, use Segura_pam_device_disable(). Esta função recebe o objeto de acesso ao dispositivo e um mapa contendo os dados de identificação do dispositivo. O identificador necessário é o hostname ou o device id. Retorna 0 em caso de sucesso ou -1 em caso de erro.
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "localhost");
int status = Segura_pam_device_disable(dev, identifier);

Gerenciar Credenciais

O objeto credencial fornece métodos para consultar e registrar credenciais.

  • Criar um objeto cliente de credencial: crie um objeto de acesso à API de credenciais usando Segura_pam_credential_new(). Esta função requer um objeto mapa com detalhes de conexão (url, client_id, client_secret), semelhante à criação de um objeto cliente de dispositivo.
Segura_map *map = Segura_map_new();
Segura_pam_credential *cred = Segura_pam_credential_new(map);
  • Criar ou atualizar uma credencial: use Segura_pam_credential_save() para criar ou atualizar uma credencial. Ela requer o objeto de acesso à credencial e um mapa contendo os parâmetros da credencial. Os parâmetros obrigatórios para o mapa de entrada são hostname, ip, identifier e username. Se uma credencial com esses parâmetros for encontrada, ela é alterada; caso contrário, uma nova é criada. A função retorna 0 em caso de sucesso ou -1 em caso de erro (detalhes do erro via Segura_last_error()).
Segura_map *params = Segura_map_new();
Segura_map_add(params, "hostname", "johns.Segura.com");
Segura_map_add(params, "ip", "22.13.50.71");
Segura_map_add(params, "username", "credential05");
int status = Segura_pam_credential_save(cred, params);
  • Buscar uma credencial registrada: a função Segura_pam_credential_get() busca uma única credencial. Ela recebe o objeto de acesso à credencial e um mapa contendo as informações de identificação da credencial. Os parâmetros para o mapa de identificação podem incluir hostname, ip ou username. A função retorna um Segura_pam_credential* em caso de sucesso ou NULL em caso de erro (detalhes do erro via Segura_last_error()).
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "mycredential02");
Segura_map_add(identifier, "username", "credential05");
Segura_pam_credential *found_cred = Segura_pam_credential_get(cred, identifier);
  • Listar credenciais: para buscar uma lista de credenciais, use Segura_pam_credential_fetch(). Ela recebe o objeto de acesso à credencial e um mapa opcional para filtrar os resultados. Os filtros podem incluir hostname, ip, username ou all (para pesquisar em todos esses campos). Em caso de sucesso, retorna um objeto mapa que contém a lista de credenciais; em caso de erro, retorna NULL e fornece detalhes do erro via Segura_last_error().
Segura_map *filters = Segura_map_new();
Segura_map_add(filters, "hostname", "mycredential02"); // Filtro opcional
Segura_map *found_creds = Segura_pam_credential_fetch(cred, filters);
  • Desativar uma credencial: a função Segura_pam_credential_disable() desabilita uma única credencial. Ela requer o objeto de acesso à credencial e um mapa com as informações de identificação da credencial. Os parâmetros podem incluir hostname, ip ou username. Retorna 0 em caso de sucesso ou -1 em caso de erro (detalhes do erro via Segura_last_error()).
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "mycredential02");
Segura_map_add(identifier, "username", "credential05");
int status = Segura_pam_credential_disable(cred, identifier);
  • Liberar o objeto credencial: o exemplo mostra a liberação do objeto credencial usando Segura_pam_credential_free(), que também limpa os dados da memória de forma segura. Note que ela recebe um ponteiro para o ponteiro da credencial (Segura_pam_credential **).
Segura_pam_credential_free(&cred);

Usar serviços do DSM

O Segura® SDK para C fornece interfaces para registrar aplicações e gerenciar seus segredos e variáveis via DevOps Secret Management.

Gerenciar Aplicações

O objeto DSM permite gerenciar aplicações, segredos e variáveis.

  • Criar um objeto cliente DSM: crie um objeto de acesso à API de aplicações DSM usando Segura_dsm_application_new(). Esta função requer um objeto mapa contendo detalhes de conexão como client_id e client_secret.
Segura_map *map = Segura_map_new();
Segura_dsm_application *app = Segura_dsm_application_new(map);
  • Criar ou atualizar uma aplicação: a função Segura_dsm_application_save() atualiza ou cria uma nova aplicação. Ela recebe o objeto de acesso à aplicação DSM e um mapa contendo os parâmetros da aplicação. Os parâmetros obrigatórios para o mapa de entrada são application, system e environment. Um parâmetro opcional é unique_key. Se uma aplicação com a combinação de application, system e environment existir para o cliente, ela será alterada; caso contrário, uma nova aplicação ou autorização será criada. Quando a aplicação ativa o provisionamento dinâmico, o destino recebe automaticamente um segredo. A função retorna 0 em caso de sucesso ou -1 em caso de erro (detalhes do erro via Segura_last_error()).
Segura_map *params = Segura_map_new();
Segura_map_add(params, "application", "checkout");
Segura_map_add(params, "system", "ecommerce");
Segura_map_add(params, "environment", "production");
int status = Segura_dsm_application_save(app, params);
  • Obter informações e segredos da aplicação cliente: use Segura_dsm_application_get() para buscar as informações da aplicação cliente, incluindo seus segredos. Ela recebe o objeto de acesso à aplicação DSM. Retorna um Segura_dsm_application* em caso de sucesso ou -1 em caso de erro (detalhes do erro via Segura_last_error()). O objeto retornado contém as informações da aplicação e os segredos.
Segura_dsm_application *app_info = Segura_dsm_application_get(app);
  • Registrar segredos da aplicação: a função Segura_dsm_application_register_secret() registra um segredo de aplicação. Ela recebe o objeto de acesso à aplicação DSM e um mapa contendo as informações do segredo. Um parâmetro obrigatório é secret_type, que pode ser access_key, key_value, credential, certificate ou ssh_key. Dependendo do secret_type, outros parâmetros são obrigatórios: access_keys para access_key, key_value para key_value, credentials para credential, certificate para certificate e ssh_key para ssh_key. O exemplo mostra o registro de um segredo key_value, que contém um mapa de pares chave/valor. A função retorna 0 em caso de sucesso ou -1 em caso de erro (detalhes do erro via Segura_last_error()).
Segura_map *secret_info = Segura_map_new();
Segura_map_add(secret_info, "secret_type", "key_value");
Segura_map *kv_data = Segura_map_new();
Segura_map_add(kv_data, "key1", "val1");
Segura_map_add(kv_data, "key2", "val2");
Segura_map_add(kv_data, "key3", "val3");
Segura_map_add(secret_info, "key_value", kv_data); // Adiciona o mapa aninhado
int status = Segura_dsm_application_register_secret(app, secret_info);
  • Registrar variáveis da aplicação: use Segura_dsm_application_register_variables() para registrar variáveis da aplicação. Ela recebe o objeto de acesso à aplicação DSM e um mapa contendo as informações das variáveis. Os parâmetros obrigatórios são env, helm e map. O exemplo mostra a adição das variáveis diretamente ao mapa passado para a função. A função retorna 0 em caso de sucesso ou -1 em caso de erro.
Segura_map *variables = Segura_map_new();
Segura_map_add(variables, "env", "production");
Segura_map_add(variables, "helm", "myapp-helm");
Segura_map *var_map_data = Segura_map_new();
Segura_map_add(var_map_data, "variable1", "test1");
Segura_map_add(var_map_data, "variable2", "test");
Segura_map_add(variables, "map", var_map_data);
int status = Segura_dsm_application_register_variables(app, variables);
  • Excluir autorização da aplicação: para excluir a autorização da aplicação, use Segura_dsm_application_delete(). Ela recebe o objeto de acesso à aplicação DSM. Se o provisionamento dinâmico estiver habilitado para a aplicação, todos os segredos serão automaticamente desprovisionados. A função retorna 0 em caso de sucesso ou -1 em caso de erro.
int status = Segura_dsm_application_delete(app);

Lembre-se de tratar possíveis erros verificando os valores de retorno e utilizando Segura_last_error() quando indicado.