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 orNULL
on error. If it fails, you can check the exact reason usingSegura_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 (aconst char*
), and the value (avoid*
) as arguments. It returns0
on success or-1
on error, with error details available viaSegura_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 thevoid*
value on success orNULL
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 theurl
,client_id
, andclient_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 arehostname
,ip
,site
,model
,vendor
, andtype
. The function returns0
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 thehostname
ordevice id
. It returns aSegura_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 likehostname
,ip
,type
,vendor
,model
, orsite
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 orNULL
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 thehostname
ordevice id
. It returns0
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 arehostname
,ip
,identifier
, andusername
. If a credential with those parameters is found, it is changed; otherwise, a new one is created. The function returns0
on success or-1
on error (error details viaSegura_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 includehostname
,ip
, orusername
. The function returns aSegura_pam_credential*
on success orNULL
on error (error details viaSegura_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 includehostname
,ip
,username
, orall
(to search across those fields). On success, it returns a map object that contains the list of credentials; on error, it returnsNULL
and provides error details viaSegura_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 includehostname
,ip
, orusername
. It returns0
on success or-1
on error (error details viaSegura_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 likeclient_id
andclient_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 areapplication
,system
, andenvironment
. An optional parameter isunique_key
. If an application with the combination ofapplication
,system
, andenvironment
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 returns0
on success or-1
on error (error details viaSegura_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 aSegura_dsm_application*
on success or-1
on error (error details viaSegura_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 issecret_type
, which can beaccess_key
,key_value
,credential
,certificate
, orssh_key
. Depending on thesecret_type
, other parameters are required:access_keys
foraccess_key
,key_value
forkey_value
,credentials
forcredential
,certificate
forcertificate
, andssh_key
forssh_key
. The example shows registering akey_value
secret, which itself contains a map of key/value pairs. The function returns0
on success or-1
on error (error details viaSegura_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 areenv
,helm
, andmap
. The example shows adding The variables are directly assigned to the map that is passed to the function. The function returns0
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 returns0
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.