|
Cedarling C API
|
#include <stdarg.h>#include <stdbool.h>#include <stdint.h>#include <stdlib.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 enum CedarlingErrorCode CedarlingErrorCode |
Error codes returned by cedarling functions.
| typedef struct CedarlingInstanceResult CedarlingInstanceResult |
Structure for instance creation results
| typedef struct CedarlingResult CedarlingResult |
Result structure for operations that return data
| typedef struct CedarlingStringArray CedarlingStringArray |
Structure for returning arrays of strings
| enum CedarlingErrorCode |
Error codes returned by cedarling functions.
| int cedarling_authorize_multi_issuer | ( | uint64_t | instance_id, |
| const char * | request_json, | ||
| struct CedarlingResult * | result | ||
| ) |
Authorize a multi-issuer request (JSON body).
request_json must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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.
request_json must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | int cedarling_authorize_unsigned | ( | uint64_t | instance_id, |
| const char * | request_json, | ||
| struct CedarlingResult * | result | ||
| ) |
Authorize an unsigned request from JSON.
request_json must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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.
request_json must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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.
| void cedarling_clear_last_error | ( | void | ) |
Clears the thread-local string read by [cedarling_get_last_error].
| int cedarling_context_clear | ( | uint64_t | instance_id, |
| struct CedarlingResult * | result | ||
| ) |
Clear all context data for the instance.
result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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).
key must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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.
key must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | int cedarling_context_list | ( | uint64_t | instance_id, |
| struct CedarlingResult * | result | ||
| ) |
List all context entries (JSON array of entries with metadata).
result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | 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.
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]. | int cedarling_context_remove | ( | uint64_t | instance_id, |
| const char * | key, | ||
| struct CedarlingResult * | result | ||
| ) |
Remove context data by key.
key must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | int cedarling_context_stats | ( | uint64_t | instance_id, |
| struct CedarlingResult * | result | ||
| ) |
Get context store statistics as JSON.
result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | int cedarling_drop | ( | uint64_t | instance_id | ) |
Remove an instance from the runtime registry (no graceful shutdown).
No raw pointers are passed. instance_id is validated by the library; unknown IDs return an error.
| int cedarling_failed_trusted_issuer_ids | ( | uint64_t | instance_id, |
| struct CedarlingStringArray * | result | ||
| ) |
List issuer IDs that failed to load.
result must point to writable [CedarlingStringArray] storage.cedarling_free_string_array]. | void cedarling_free_instance_result | ( | struct CedarlingInstanceResult * | result | ) |
Release error_message inside a [CedarlingInstanceResult] filled by this library.
result may be null (no-op).error_message must either be null or a pointer produced by this library; do not double-free. | void cedarling_free_result | ( | struct CedarlingResult * | result | ) |
Release data and error_message inside a [CedarlingResult] filled by this library.
result may be null (no-op).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. | void cedarling_free_string | ( | char * | str_ptr | ) |
Free a heap-allocated C string returned by this library (for example from [cedarling_get_last_error]).
str_ptr may be null (no-op).str_ptr must be a pointer previously returned by this library as an owned string, and must not be freed twice. | void cedarling_free_string_array | ( | struct CedarlingStringArray * | array | ) |
Free a [CedarlingStringArray] produced on the success path of log or issuer-ID functions.
array may be null (no-op).array must point to a struct exactly as filled by this library (including items/count), and must not be freed twice. | 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].
| 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).
log_id must be a valid NUL-terminated UTF-8 C string.result must point to writable [CedarlingResult] storage; release with [cedarling_free_result]. | int cedarling_get_log_ids | ( | uint64_t | instance_id, |
| struct CedarlingStringArray * | result | ||
| ) |
Get all log IDs as a string array.
result must point to writable [CedarlingStringArray] storage.cedarling_free_string_array]. | 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.
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]. | 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.
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]. | 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.
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]. | 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.
out_id must point to writable char* storage.*out_id must be freed once with [cedarling_free_string]. | 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.
| int cedarling_is_trusted_issuer_loaded_by_iss | ( | uint64_t | instance_id, |
| const char * | iss_claim, | ||
| bool * | out_result | ||
| ) |
| int cedarling_is_trusted_issuer_loaded_by_name | ( | uint64_t | instance_id, |
| const char * | issuer_id, | ||
| bool * | out_result | ||
| ) |
| int cedarling_loaded_trusted_issuer_ids | ( | uint64_t | instance_id, |
| struct CedarlingStringArray * | result | ||
| ) |
List issuer IDs that loaded successfully.
result must point to writable [CedarlingStringArray] storage.cedarling_free_string_array]. | int cedarling_loaded_trusted_issuers_count | ( | uint64_t | instance_id, |
| uintptr_t * | out_count | ||
| ) |
| int cedarling_new | ( | const char * | config_json, |
| struct CedarlingInstanceResult * | result | ||
| ) |
Create a new Cedarling instance from JSON bootstrap configuration.
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].cedarling_free_instance_result] (including when error_message is set). | int cedarling_new_with_env | ( | const char * | config_json, |
| struct CedarlingInstanceResult * | result | ||
| ) |
Create a new Cedarling instance, merging JSON config with environment-variable overrides.
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].cedarling_free_instance_result]. | int cedarling_pop_logs | ( | uint64_t | instance_id, |
| struct CedarlingStringArray * | result | ||
| ) |
Pop all logs from an instance into a string array.
result must point to writable [CedarlingStringArray] storage.cedarling_free_string_array]. | int cedarling_shutdown | ( | uint64_t | instance_id | ) |
Gracefully shut down an instance (flush resources, then remove from registry).
No raw pointers are passed. instance_id is validated by the library.
| int cedarling_total_issuers | ( | uint64_t | instance_id, |
| uintptr_t * | out_count | ||
| ) |
| 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.