SDK for C

  • 8 minute(s) read
Prev Next

The Segura® SDK for PHP makes it easy for developers to access Segura® services in their C applications.

Core Concepts

The SDK facilitates building robust applications by providing interfaces to manage credentials, devices, and application secrets. A key feature is the use of a local cache to reduce request response times. All data stored in this cache is encrypted for security.

A fundamental object used throughout the SDK is the map object. This object serves as a container for key/value pairs, holding all the necessary information required when calling API functions.

Using the Map Object

The map object is essential for passing parameters to most SDK functions.

  • Creating a map object: to begin, you must create a new map object using the Segura_map_new() function. This function returns a pointer to the new map object on success or NULL on error. If it fails, you can check the exact reason using Segura_last_error().
Segura_map *map = Segura_map_new();
if (map == NULL) {
    // Handle error using Segura_last_error()
}
  • Adding items to a map: use segura_map_add() to add a new key/value pair to an existing map object. The function takes the map object, the key (a const char*), and the value (a void*) as arguments. It returns 0 on success or -1 on error, with error details available via Segura_last_error().
Segura_map_add(map, "key_name", value_pointer);

The examples demonstrate how to add string values such as URLs, client IDs, client secrets, hostnames, usernames, IP addresses, site names, models, vendors, and types.

  • Retrieving item information from a map: to get the value associated with a specific key from a map, use Segura_map_get(). This function takes the map object and the key (const char*) as input. It returns the void* value on success or NULL on failure.
void *value = Segura_map_get(map, "key_name");
  • Clearing a map: the Segura_map_clear() function removes all key/value pairs from a map object. This is useful when you need to reuse a map object for different parameters.
Segura_map_clear(map);
  • Freeing a map object: when you are finished with a map object, you should free the allocated memory using Segura_map_free(). Note that it takes a pointer to the map pointer (Segura_map **).
Segura_map_free(&map);

Using PAM Services

The Segura® SDK for C for managing devices and credentials via PAM services.

Managing Devices

The device object provides methods to query and register devices.

  • Creating a device client object: similar to the map object, you first need to create a device API access object using Segura_pam_device_new(). This function typically requires a map object containing connection details like the url, client_id, and client_secret.
Segura_map *map = Segura_map_new();
Segura_pam_device *dev = Segura_pam_device_new(map);
  • Creating or updating a device: the Segura_pam_device_save() function is used to either create a new device or update an existing one. It takes the device access object and a map containing device parameters as arguments. If a device matching the parameters is found, it's updated; otherwise, a new one is created. The required parameters for the input map are hostname, ip, site, model, vendor, and type. The function returns 0 on success or -1 on error.
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);
  • Searching for a registered device: To query a single device, use Segura_pam_device_get(). This function requires the device access object and a map containing the device identification data. The required identifier is typically the hostname or device id. It returns a Segura_pam_device* on success or -1 on error.
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "localhost");
Segura_pam_device *found_dev = Segura_pam_device_get(dev, identifier);
  • Listing devices: the Segura_pam_device_fetch() function fetches a list of devices. It accepts the device access object and an optional filter map. The filter map can include parameters like hostname, ip, type, vendor, model, or site to narrow down the results. An empty filter map will list all devices. The function returns a map containing the list of devices on success or NULL on error.
Segura_map *filter = Segura_map_new();
Segura_map_add(filter, "type", "Server"); // Optional filter
Segura_map *found_devices = Segura_pam_device_fetch(dev, filter);
  • Deactivating a device: to disable a device, use Segura_pam_device_disable(). This function takes the device access object and a map containing the device identification data. The required identifier is the hostname or device id. It returns 0 on success or -1 on error.
Segura_map *identifier = Segura_map_new();
Segura_map_add(identifier, "hostname", "localhost");
int status = Segura_pam_device_disable(dev, identifier);

Managing Credentials

The credential object provides methods to query and register credentials.

  • Creating a credential client object: create a credential API access object using Segura_pam_credential_new(). This function requires a map object with connection details (url, client_id, client_secret), similar to creating a device client object.
Segura_map *map = Segura_map_new();
Segura_pam_credential *cred = Segura_pam_credential_new(map);
  • Creating or updating a credential: use Segura_pam_credential_save() to create or update a credential. It requires the credential access object and a map containing the credential parameters. Required parameters for the input map are hostname, ip, identifier, and username. If a credential with those parameters is found, it is changed; otherwise, a new one is created. The function returns 0 on success or -1 on error (error details 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);
  • Searching for a registered credential: the Segura_pam_credential_get() function fetches a single credential. It takes the credential access object and a map containing credential identification information. Parameters for the identification map can include hostname, ip, or username. The function returns a Segura_pam_credential* on success or NULL on error (error details 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);
  • Listing credentials: To fetch a list of credentials, use Segura_pam_credential_fetch(). It takes the credential access object and an optional map for filtering results. Filters can include hostname, ip, username, or all (to search across those fields). On success, it returns a map object that contains the list of credentials; on error, it returns NULL and provides error details via Segura_last_error().
Segura_map *filters = Segura_map_new();
Segura_map_add(filters, "hostname", "mycredential02"); // Optional filter
Segura_map *found_creds = Segura_pam_credential_fetch(cred, filters);
  • Deactivating a credential: the Segura_pam_credential_disable() function disables a single credential. It requires the credential access object and a map with credential identification information. Parameters can include hostname, ip, or username. It returns 0 on success or -1 on error (error details 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);
  • Freeing credential object: the example usage shows freeing the credential object using Segura_pam_credential_free(), which also securely clears data from memory. Note it takes a pointer to the credential pointer (Segura_pam_credential **).
Segura_pam_credential_free(&cred);

Using DSM Services

The Segura® SDK for C provides interfaces to register applications and manage their secrets and variables via DevOps Secret Management.

Managing Applications

The DSM object allows managing applications, secrets, and variables.

  • Creating a DSM client object: create a DSM application API access object using Segura_dsm_application_new(). This function requires a map object containing connection details like client_id and client_secret.
Segura_map *map = Segura_map_new();
Segura_dsm_application *app = Segura_dsm_application_new(map);
  • Creating or updating an application: the Segura_dsm_application_save() function updates or creates a new application. It takes the DSM application access object and a map containing the application parameters. Required parameters for the input map are application, system, and environment. An optional parameter is unique_key. If an application with the combination of application, system, and environment exists for the client, it will be changed; otherwise, a new application or authorization will be created. When the application activates dynamic provisioning, the target automatically receives a secret. The function returns 0 on success or -1 on error (error details 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);
  • Getting client application information and secrets: use Segura_dsm_application_get() to fetch the client application information, including its secrets. It takes the DSM application access object. It returns a Segura_dsm_application* on success or -1 on error (error details via Segura_last_error()). The returned object contains the application information and secrets.
Segura_dsm_application *app_info = Segura_dsm_application_get(app);
  • Registering application secrets: the Segura_dsm_application_register_secret() function registers an application secret. It takes the DSM application access object and a map containing the secret information. A required parameter is secret_type, which can be access_key, key_value, credential, certificate, or ssh_key. Depending on the secret_type, other parameters are required: access_keys for access_key, key_value for key_value, credentials for credential, certificate for certificate, and ssh_key for ssh_key. The example shows registering a key_value secret, which itself contains a map of key/value pairs. The function returns 0 on success or -1 on error (error details 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); // Add the nested map
int status = Segura_dsm_application_register_secret(app, secret_info);
  • Registering application variables: use Segura_dsm_application_register_variables() to register application variables. It takes the DSM application access object and a map containing the variables information. Required parameters are env, helm, and map. The example shows adding The variables are directly assigned to the map that is passed to the function. The function returns 0 on success or -1 on error.
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);
  • Deleting application authorization: to delete the application authorization, use Segura_dsm_application_delete(). It takes the DSM application access object. If dynamic provisioning is enabled for the application, all secrets will be automatically unprovisioned. The function returns 0 on success or -1 on error.
int status = Segura_dsm_application_delete(app);

This document provides a guide to using the primary functions and objects available in the Segura® C SDK, as described in the provided excerpts. Remember to handle potential errors by checking return values and using Segura_last_error() when indicated.