Cedarling C API
Loading...
Searching...
No Matches
Data Structures | Typedefs | Enumerations | Functions
cedarling_c.h File Reference
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
Include dependency graph for cedarling_c.h:

Go to the source code of this file.

Data Structures

struct  CedarlingInstanceResult
 
struct  CedarlingResult
 
struct  CedarlingStringArray
 

Typedefs

typedef enum CedarlingErrorCode CedarlingErrorCode
 
typedef struct CedarlingInstanceResult CedarlingInstanceResult
 
typedef struct CedarlingResult CedarlingResult
 
typedef struct CedarlingStringArray CedarlingStringArray
 

Enumerations

enum  CedarlingErrorCode {
  SUCCESS = 0 , INVALID_ARGUMENT = 1 , INSTANCE_NOT_FOUND = 2 , JSON_ERROR = 3 ,
  AUTHORIZATION_ERROR = 4 , CONFIGURATION_ERROR = 5 , INTERNAL = 6 , KEY_NOT_FOUND = 7
}
 

Functions

int cedarling_init (void)
 
int cedarling_new (const char *config_json, struct CedarlingInstanceResult *result)
 
int cedarling_new_with_env (const char *config_json, struct CedarlingInstanceResult *result)
 
int cedarling_drop (uint64_t instance_id)
 
int cedarling_authorize_unsigned (uint64_t instance_id, const char *request_json, struct CedarlingResult *result)
 
int cedarling_authorize_multi_issuer (uint64_t instance_id, const char *request_json, struct CedarlingResult *result)
 
int cedarling_authorize_unsigned_batch (uint64_t instance_id, const char *request_json, struct CedarlingResult *result)
 
int cedarling_authorize_multi_issuer_batch (uint64_t instance_id, const char *request_json, struct CedarlingResult *result)
 
int cedarling_context_push (uint64_t instance_id, const char *key, const char *value_json, int64_t ttl_secs, struct CedarlingResult *result)
 
int cedarling_context_get (uint64_t instance_id, const char *key, struct CedarlingResult *result)
 
int cedarling_context_get_entry (uint64_t instance_id, const char *key, struct CedarlingResult *result)
 
int cedarling_context_remove (uint64_t instance_id, const char *key, struct CedarlingResult *result)
 
int cedarling_context_clear (uint64_t instance_id, struct CedarlingResult *result)
 
int cedarling_context_list (uint64_t instance_id, struct CedarlingResult *result)
 
int cedarling_context_stats (uint64_t instance_id, struct CedarlingResult *result)
 
int cedarling_pop_logs (uint64_t instance_id, struct CedarlingStringArray *result)
 
int cedarling_get_log_by_id (uint64_t instance_id, const char *log_id, struct CedarlingResult *result)
 
int cedarling_get_log_ids (uint64_t instance_id, struct CedarlingStringArray *result)
 
int cedarling_get_logs_by_tag (uint64_t instance_id, const char *tag, struct CedarlingStringArray *result)
 
int cedarling_get_logs_by_request_id (uint64_t instance_id, const char *request_id, struct CedarlingStringArray *result)
 
int cedarling_get_logs_by_request_id_and_tag (uint64_t instance_id, const char *request_id, const char *tag, struct CedarlingStringArray *result)
 
int cedarling_is_trusted_issuer_loaded_by_name (uint64_t instance_id, const char *issuer_id, bool *out_result)
 
int cedarling_is_trusted_issuer_loaded_by_iss (uint64_t instance_id, const char *iss_claim, bool *out_result)
 
int cedarling_total_issuers (uint64_t instance_id, uintptr_t *out_count)
 
int cedarling_get_policy_store_id (uint64_t instance_id, char **out_id)
 
int cedarling_loaded_trusted_issuers_count (uint64_t instance_id, uintptr_t *out_count)
 
int cedarling_loaded_trusted_issuer_ids (uint64_t instance_id, struct CedarlingStringArray *result)
 
int cedarling_failed_trusted_issuer_ids (uint64_t instance_id, struct CedarlingStringArray *result)
 
int cedarling_shutdown (uint64_t instance_id)
 
void cedarling_free_string (char *str_ptr)
 
void cedarling_free_string_array (struct CedarlingStringArray *array)
 
void cedarling_free_result (struct CedarlingResult *result)
 
void cedarling_free_instance_result (struct CedarlingInstanceResult *result)
 
char * cedarling_get_last_error (void)
 
void cedarling_clear_last_error (void)
 
const char * cedarling_version (void)
 
void cedarling_cleanup (void)
 

Typedef Documentation

◆ CedarlingErrorCode

Error codes returned by cedarling functions.

◆ CedarlingInstanceResult

Structure for instance creation results

◆ CedarlingResult

Result structure for operations that return data

◆ CedarlingStringArray

Structure for returning arrays of strings

Enumeration Type Documentation

◆ CedarlingErrorCode

Error codes returned by cedarling functions.

Enumerator
SUCCESS 

Success - no error

INVALID_ARGUMENT 

Invalid argument provided

INSTANCE_NOT_FOUND 

Instance not found

JSON_ERROR 

JSON parsing error

AUTHORIZATION_ERROR 

Authorization error

CONFIGURATION_ERROR 

Configuration error

INTERNAL 

Internal error

KEY_NOT_FOUND 

Requested key or id does not exist (e.g. unknown log id)

Function Documentation

◆ cedarling_authorize_multi_issuer()

int cedarling_authorize_multi_issuer ( uint64_t  instance_id,
const char *  request_json,
struct CedarlingResult *  result 
)

Authorize a multi-issuer request (JSON body).

Safety

  • request_json must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].
Examples
authorize_multi_issuer.c.

◆ cedarling_authorize_multi_issuer_batch()

int cedarling_authorize_multi_issuer_batch ( uint64_t  instance_id,
const char *  request_json,
struct CedarlingResult *  result 
)

Authorize a batch of multi-issuer requests (JSON body).

The request body is a JSON object of the shape { "tokens": [...], "items": [...] }. Response semantics mirror [cedarling_authorize_unsigned_batch]: shared batch_id + per-item results, batch-level errors fail the whole call, per-item failures are returned as Err (BatchItemError) entries that callers must inspect.

Safety

  • request_json must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_authorize_unsigned()

int cedarling_authorize_unsigned ( uint64_t  instance_id,
const char *  request_json,
struct CedarlingResult *  result 
)

Authorize an unsigned request from JSON.

Safety

  • request_json must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].
Examples
authorize_unsigned.c, and basic_example.c.

◆ cedarling_authorize_unsigned_batch()

int cedarling_authorize_unsigned_batch ( uint64_t  instance_id,
const char *  request_json,
struct CedarlingResult *  result 
)

Authorize a batch of unsigned requests (JSON body).

The request body is a JSON object of the shape { "principal": {...} | null, "items": [ { "resource": {...}, "action": "...", "context": {...} }, ... ] }. The response body carries batch_id (UUIDv7 string) alongside results — one AuthorizeResult per input item, in input order. Batch-level failures (validation, principal parse) return an error; per-item failures are returned as Err (BatchItemError) entries that callers must inspect without failing the whole call.

Safety

  • request_json must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_cleanup()

void cedarling_cleanup ( void  )

Shut down and remove all Cedarling instances held by the library, then clear this thread's auxiliary last-error string ([cedarling_get_last_error]).

Safe to call from any thread; repeated calls are effectively idempotent after the first full teardown. No pointer parameters.

After a successful teardown, no instances remain registered and this thread's [cedarling_get_last_error] returns null until a new auxiliary error is stored.

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_clear_last_error()

void cedarling_clear_last_error ( void  )

Clears the thread-local string read by [cedarling_get_last_error].

◆ cedarling_context_clear()

int cedarling_context_clear ( uint64_t  instance_id,
struct CedarlingResult *  result 
)

Clear all context data for the instance.

Safety

  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_get()

int cedarling_context_get ( uint64_t  instance_id,
const char *  key,
struct CedarlingResult *  result 
)

Get context data (JSON value only) by key.

On success, data is the JSON text for the value, or the JSON literal null when the key is absent or when the stored value is JSON null—those two cases are not distinguished here. Use [cedarling_context_get_entry] to tell them apart (missing keys yield no entry object).

Safety

  • key must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_get_entry()

int cedarling_context_get_entry ( uint64_t  instance_id,
const char *  key,
struct CedarlingResult *  result 
)

Get one context data entry (value plus metadata: key, data_type, timestamps, access_count) as JSON.

Safety

  • key must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_list()

int cedarling_context_list ( uint64_t  instance_id,
struct CedarlingResult *  result 
)

List all context entries (JSON array of entries with metadata).

Safety

  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_push()

int cedarling_context_push ( uint64_t  instance_id,
const char *  key,
const char *  value_json,
int64_t  ttl_secs,
struct CedarlingResult *  result 
)

Push context data (JSON value) under key with optional TTL in seconds.

Safety

  • key and value_json must be valid NUL-terminated UTF-8 C strings.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_remove()

int cedarling_context_remove ( uint64_t  instance_id,
const char *  key,
struct CedarlingResult *  result 
)

Remove context data by key.

Safety

  • key must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_context_stats()

int cedarling_context_stats ( uint64_t  instance_id,
struct CedarlingResult *  result 
)

Get context store statistics as JSON.

Safety

  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_drop()

int cedarling_drop ( uint64_t  instance_id)

Remove an instance from the runtime registry (no graceful shutdown).

Safety

No raw pointers are passed. instance_id is validated by the library; unknown IDs return an error.

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_failed_trusted_issuer_ids()

int cedarling_failed_trusted_issuer_ids ( uint64_t  instance_id,
struct CedarlingStringArray *  result 
)

List issuer IDs that failed to load.

Safety

  • result must point to writable [CedarlingStringArray] storage.
  • On success, free with [cedarling_free_string_array].

◆ cedarling_free_instance_result()

void cedarling_free_instance_result ( struct CedarlingInstanceResult *  result)

Release error_message inside a [CedarlingInstanceResult] filled by this library.

Safety

  • result may be null (no-op).
  • If non-null, error_message must either be null or a pointer produced by this library; do not double-free.
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_free_result()

void cedarling_free_result ( struct CedarlingResult *  result)

Release data and error_message inside a [CedarlingResult] filled by this library.

Safety

  • result may be null (no-op).
  • If non-null, result must point to a [CedarlingResult] whose pointer fields were produced by this library (or are null), and this function must not run twice on the same populated struct without reinitialization.
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_free_string()

void cedarling_free_string ( char *  str_ptr)

Free a heap-allocated C string returned by this library (for example from [cedarling_get_last_error]).

Safety

  • str_ptr may be null (no-op).
  • If non-null, str_ptr must be a pointer previously returned by this library as an owned string, and must not be freed twice.
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_free_string_array()

void cedarling_free_string_array ( struct CedarlingStringArray *  array)

Free a [CedarlingStringArray] produced on the success path of log or issuer-ID functions.

Safety

  • array may be null (no-op).
  • If non-null, array must point to a struct exactly as filled by this library (including items/count), and must not be freed twice.
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_get_last_error()

char * cedarling_get_last_error ( void  )

Returns a thread-local auxiliary error string for failures that are not already described in an out-parameter (for example [CedarlingResult] / [CedarlingInstanceResult] carry their own error_message).

The return value is null if no such message is stored. If non-null, it must be released with [cedarling_free_string].

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_get_log_by_id()

int cedarling_get_log_by_id ( uint64_t  instance_id,
const char *  log_id,
struct CedarlingResult *  result 
)

Get a single log entry by ID (JSON in the result's data field).

Safety

  • log_id must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingResult] storage; release with [cedarling_free_result].

◆ cedarling_get_log_ids()

int cedarling_get_log_ids ( uint64_t  instance_id,
struct CedarlingStringArray *  result 
)

Get all log IDs as a string array.

Safety

  • result must point to writable [CedarlingStringArray] storage.
  • On success, free with [cedarling_free_string_array].
Examples
basic_example.c.

◆ cedarling_get_logs_by_request_id()

int cedarling_get_logs_by_request_id ( uint64_t  instance_id,
const char *  request_id,
struct CedarlingStringArray *  result 
)

Get logs for a request ID as a string array of JSON lines.

Safety

  • request_id must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingStringArray] storage; on success free with [cedarling_free_string_array].

◆ cedarling_get_logs_by_request_id_and_tag()

int cedarling_get_logs_by_request_id_and_tag ( uint64_t  instance_id,
const char *  request_id,
const char *  tag,
struct CedarlingStringArray *  result 
)

Get logs for a request ID and tag as a string array of JSON lines.

Safety

  • request_id and tag must be valid NUL-terminated UTF-8 C strings.
  • result must point to writable [CedarlingStringArray] storage; on success free with [cedarling_free_string_array].

◆ cedarling_get_logs_by_tag()

int cedarling_get_logs_by_tag ( uint64_t  instance_id,
const char *  tag,
struct CedarlingStringArray *  result 
)

Get logs matching tag as a string array of JSON lines.

Safety

  • tag must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable [CedarlingStringArray] storage; on success free with [cedarling_free_string_array].

◆ cedarling_get_policy_store_id()

int cedarling_get_policy_store_id ( uint64_t  instance_id,
char **  out_id 
)

Write the ID of the currently published policy store into *out_id.

On success *out_id is either an owned string or null when the store carries no ID. The value is opaque and source-dependent, and may change after a background refresh. On error *out_id is set to null.

Safety

  • out_id must point to writable char* storage.
  • A non-null *out_id must be freed once with [cedarling_free_string].

◆ cedarling_init()

int cedarling_init ( void  )

Initialize the Cedarling runtime.

Call before other library functions (per your process/thread model). This entry point has no pointer parameters and is safe to call from C.

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_is_trusted_issuer_loaded_by_iss()

int cedarling_is_trusted_issuer_loaded_by_iss ( uint64_t  instance_id,
const char *  iss_claim,
bool *  out_result 
)

Returns whether a trusted issuer was loaded for the given JWT iss claim value.

Safety

  • iss_claim must be a valid NUL-terminated UTF-8 C string.
  • out_result must point to writable bool storage.

◆ cedarling_is_trusted_issuer_loaded_by_name()

int cedarling_is_trusted_issuer_loaded_by_name ( uint64_t  instance_id,
const char *  issuer_id,
bool *  out_result 
)

Returns whether a trusted issuer was loaded, keyed by issuer identifier.

Safety

  • issuer_id must be a valid NUL-terminated UTF-8 C string.
  • out_result must point to writable bool storage.

◆ cedarling_loaded_trusted_issuer_ids()

int cedarling_loaded_trusted_issuer_ids ( uint64_t  instance_id,
struct CedarlingStringArray *  result 
)

List issuer IDs that loaded successfully.

Safety

  • result must point to writable [CedarlingStringArray] storage.
  • On success, free with [cedarling_free_string_array].

◆ cedarling_loaded_trusted_issuers_count()

int cedarling_loaded_trusted_issuers_count ( uint64_t  instance_id,
uintptr_t *  out_count 
)

Write the number of successfully loaded trusted issuers into *out_count.

Safety

  • out_count must point to writable usize storage.

◆ cedarling_new()

int cedarling_new ( const char *  config_json,
struct CedarlingInstanceResult *  result 
)

Create a new Cedarling instance from JSON bootstrap configuration.

Safety

  • config_json must be a valid pointer to a NUL-terminated UTF-8 C string.
  • result must point to writable, properly aligned memory for [CedarlingInstanceResult].
  • After reading the output, call [cedarling_free_instance_result] (including when error_message is set).
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_new_with_env()

int cedarling_new_with_env ( const char *  config_json,
struct CedarlingInstanceResult *  result 
)

Create a new Cedarling instance, merging JSON config with environment-variable overrides.

Safety

  • config_json may be null; if non-null, it must be a valid NUL-terminated UTF-8 C string.
  • result must point to writable, properly aligned memory for [CedarlingInstanceResult].
  • After reading the output, call [cedarling_free_instance_result].

◆ cedarling_pop_logs()

int cedarling_pop_logs ( uint64_t  instance_id,
struct CedarlingStringArray *  result 
)

Pop all logs from an instance into a string array.

Safety

  • result must point to writable [CedarlingStringArray] storage.
  • On success, free the array (and nested strings) once with [cedarling_free_string_array].
Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_shutdown()

int cedarling_shutdown ( uint64_t  instance_id)

Gracefully shut down an instance (flush resources, then remove from registry).

Safety

No raw pointers are passed. instance_id is validated by the library.

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.

◆ cedarling_total_issuers()

int cedarling_total_issuers ( uint64_t  instance_id,
uintptr_t *  out_count 
)

Write the total number of discovered trusted issuers into *out_count.

Safety

  • out_count must point to writable usize storage.

◆ cedarling_version()

const char * cedarling_version ( void  )

Returns the Cedarling library version as a NUL-terminated static string.

The returned pointer refers to read-only memory embedded in the library binary. It is valid for the lifetime of the process and must not be passed to cedarling_free_string or any other deallocation function.

Examples
authorize_multi_issuer.c, authorize_unsigned.c, and basic_example.c.