aranya-client.h File Reference

External header file containing C function definitions for the Aranya client library. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <sys/socket.h>

Go to the source code of this file.

Data Structures
struct	AranyaExtError
struct	AranyaClient
	A handle to an Aranya Client. More...
struct	AranyaClientConfig
	Configuration info for Aranya. More...
struct	AranyaId
	Cryptographically secure Aranya ID. More...
struct	AranyaDeviceId
	Device ID. More...
struct	AranyaClientConfigBuilder
	Configuration info builder for an Aranya client config `AranyaClientConfig`. More...
struct	AranyaAqcConfigBuilder
	Configuration info builder for Aranya QUIC Channels config `AranyaAqcConfig`. More...
struct	AranyaAqcConfig
	Configuration info for Aranya QUIC Channels. More...
struct	AranyaAddTeamQuicSyncConfigBuilder
	A builder for initializing an `AranyaAddTeamQuicSyncConfig`. More...
struct	AranyaCreateTeamQuicSyncConfigBuilder
	A builder for initializing a `AranyaCreateTeamQuicSyncConfig`. More...
struct	AranyaSeedIkm
	Raw PSK seed IKM for QUIC syncer. More...
struct	AranyaCreateTeamQuicSyncConfig
	QUIC syncer configuration. More...
struct	AranyaAddTeamQuicSyncConfig
	QUIC syncer configuration. More...
struct	AranyaAddTeamConfigBuilder
	A builder for initializing an `AranyaAddTeamConfig`. More...
struct	AranyaCreateTeamConfigBuilder
	A builder for initializing a `AranyaCreateTeamConfig`. More...
struct	AranyaTeamId
	Team ID. More...
struct	AranyaAddTeamConfig
	Team configuration used when joining a team. More...
struct	AranyaCreateTeamConfig
	Team configuration used when creating a team. More...
struct	AranyaSyncPeerConfigBuilder
	Builder for a Sync Peer config `AranyaSyncPeerConfig`. More...
struct	AranyaSyncPeerConfig
	Sync Peer config. More...
struct	AranyaLabelId
	Label ID. More...
struct	AranyaAqcPeerChannel
	A type containing the AQC channel variant. More...
struct	AranyaAqcBidiChannel
	An AQC Bidirectional Channel Object. More...
struct	AranyaAqcSendChannel
	An AQC Sender Channel Object. More...
struct	AranyaAqcReceiveChannel
	An AQC Receiver Channel Object. More...
struct	AranyaAqcBidiStream
	An AQC Bidirectional Stream Object. More...
struct	AranyaAqcSendStream
	An AQC Sender Stream Object. More...
struct	AranyaAqcReceiveStream
	An AQC Receiver Stream Object. More...

Macros
#define	__has_attribute(x)   0
#define	ARANYA_NO_RETURN
#define	ARANYA_NON_NULL
#define	ARANYA_PACKED
#define	ARANYA_DURATION_SECONDS   (1000 * ARANYA_DURATION_MILLISECONDS)
#define	ARANYA_DURATION_MILLISECONDS   (1000 * ARANYA_DURATION_MICROSECONDS)
#define	ARANYA_DURATION_MICROSECONDS   (1000 * ARANYA_DURATION_NANOSECONDS)
#define	ARANYA_DURATION_NANOSECONDS   1
#define	ARANYA_ID_LEN   32
	The size in bytes of an ID.
#define	ARANYA_SEED_IKM_LEN   32
	The size in bytes of a PSK seed IKM.
#define	ARANYA_ID_STR_LEN   (((ARANYA_ID_LEN * 1375) / 1000) + 1)
	The size in bytes of an ID converted to a human-readable base58 string.

Typedefs
typedef uint8_t	AranyaAqcChannelType
typedef uint8_t	AranyaChanOp
typedef uint32_t	AranyaError
typedef uint8_t	AranyaRole
typedef struct AranyaExtError	AranyaExtError
typedef struct AranyaClient	AranyaClient
	A handle to an Aranya Client.
typedef struct AranyaClientConfig	AranyaClientConfig
	Configuration info for Aranya.
typedef struct AranyaId	AranyaId
	Cryptographically secure Aranya ID.
typedef struct AranyaDeviceId	AranyaDeviceId
	Device ID.
typedef struct AranyaClientConfigBuilder	AranyaClientConfigBuilder
	Configuration info builder for an Aranya client config `AranyaClientConfig`.
typedef struct AranyaAqcConfigBuilder	AranyaAqcConfigBuilder
	Configuration info builder for Aranya QUIC Channels config `AranyaAqcConfig`.
typedef struct AranyaAqcConfig	AranyaAqcConfig
	Configuration info for Aranya QUIC Channels.
typedef struct AranyaAddTeamQuicSyncConfigBuilder	AranyaAddTeamQuicSyncConfigBuilder
	A builder for initializing an `AranyaAddTeamQuicSyncConfig`.
typedef struct AranyaCreateTeamQuicSyncConfigBuilder	AranyaCreateTeamQuicSyncConfigBuilder
	A builder for initializing a `AranyaCreateTeamQuicSyncConfig`.
typedef struct AranyaSeedIkm	AranyaSeedIkm
	Raw PSK seed IKM for QUIC syncer.
typedef struct AranyaCreateTeamQuicSyncConfig	AranyaCreateTeamQuicSyncConfig
	QUIC syncer configuration.
typedef struct AranyaAddTeamQuicSyncConfig	AranyaAddTeamQuicSyncConfig
	QUIC syncer configuration.
typedef struct AranyaAddTeamConfigBuilder	AranyaAddTeamConfigBuilder
	A builder for initializing an `AranyaAddTeamConfig`.
typedef struct AranyaCreateTeamConfigBuilder	AranyaCreateTeamConfigBuilder
	A builder for initializing a `AranyaCreateTeamConfig`.
typedef struct AranyaTeamId	AranyaTeamId
	Team ID.
typedef struct AranyaAddTeamConfig	AranyaAddTeamConfig
	Team configuration used when joining a team.
typedef struct AranyaCreateTeamConfig	AranyaCreateTeamConfig
	Team configuration used when creating a team.
typedef struct AranyaSyncPeerConfigBuilder	AranyaSyncPeerConfigBuilder
	Builder for a Sync Peer config `AranyaSyncPeerConfig`.
typedef struct AranyaSyncPeerConfig	AranyaSyncPeerConfig
	Sync Peer config.
typedef uint64_t	AranyaDuration
	A type to represent a span of time in nanoseconds.
typedef const char *	AranyaLabelName
	An AQC label name.
typedef struct AranyaLabelId	AranyaLabelId
	Label ID.
typedef const char *	AranyaAddr
	A network socket address for an Aranya client.
typedef const char *	AranyaNetIdentifier
	A network identifier for an Aranya client.
typedef struct AranyaAqcPeerChannel	AranyaAqcPeerChannel
	A type containing the AQC channel variant.
typedef struct AranyaAqcBidiChannel	AranyaAqcBidiChannel
	An AQC Bidirectional Channel Object.
typedef struct AranyaAqcSendChannel	AranyaAqcSendChannel
	An AQC Sender Channel Object.
typedef struct AranyaAqcReceiveChannel	AranyaAqcReceiveChannel
	An AQC Receiver Channel Object.
typedef struct AranyaAqcBidiStream	AranyaAqcBidiStream
	An AQC Bidirectional Stream Object.
typedef struct AranyaAqcSendStream	AranyaAqcSendStream
	An AQC Sender Stream Object.
typedef struct AranyaAqcReceiveStream	AranyaAqcReceiveStream
	An AQC Receiver Stream Object.

Enumerations
enum	AranyaAqcChannelType { ARANYA_AQC_CHANNEL_TYPE_BIDIRECTIONAL , ARANYA_AQC_CHANNEL_TYPE_RECEIVER }
	An enum containing all `AranyaAqcPeerChannel` variants.
enum	AranyaChanOp { ARANYA_CHAN_OP_RECV_ONLY , ARANYA_CHAN_OP_SEND_ONLY , ARANYA_CHAN_OP_SEND_RECV }
	Valid channel operations for a label assignment. More...
enum	AranyaError {   ARANYA_ERROR_SUCCESS , ARANYA_ERROR_BUG , ARANYA_ERROR_TIMEOUT , ARANYA_ERROR_INVALID_ARGUMENT ,   ARANYA_ERROR_BUFFER_TOO_SMALL , ARANYA_ERROR_INVALID_UTF8 , ARANYA_ERROR_INVALID_ADDR , ARANYA_ERROR_IPC ,   ARANYA_ERROR_ARANYA , ARANYA_ERROR_AQC , ARANYA_ERROR_WOULD_BLOCK , ARANYA_ERROR_CLOSED ,   ARANYA_ERROR_CONFIG , ARANYA_ERROR_SERIALIZATION , ARANYA_ERROR_OTHER }
	An error code. More...
enum	AranyaRole { ARANYA_ROLE_OWNER , ARANYA_ROLE_ADMIN , ARANYA_ROLE_OPERATOR , ARANYA_ROLE_MEMBER }
	An enum containing team roles defined in the Aranya policy. More...

Functions
AranyaError	aranya_init_logging (void)
	Initializes logging.
AranyaError	aranya_init_logging_ext (struct AranyaExtError *__ext_err)
	Initializes logging.
AranyaError	aranya_rand (const struct AranyaClient *client, uint8_t *buf, size_t buf_len)
	Return random bytes from Aranya's CSPRNG.
AranyaError	aranya_rand_ext (const struct AranyaClient *client, uint8_t *buf, size_t buf_len, struct AranyaExtError *__ext_err)
	Return random bytes from Aranya's CSPRNG.

Detailed Description

External header file containing C function definitions for the Aranya client library.

Typedef Documentation

AranyaAddr

typedef const char* AranyaAddr

A network socket address for an Aranya client.

E.g. "localhost:8080", "127.0.0.1:8080"

AranyaAddTeamConfig

typedef struct AranyaAddTeamConfig AranyaAddTeamConfig

Team configuration used when joining a team.

Use an `AranyaAddTeamConfigBuilder` to construct this object.

AranyaAddTeamQuicSyncConfig

typedef struct AranyaAddTeamQuicSyncConfig AranyaAddTeamQuicSyncConfig

QUIC syncer configuration.

Use an `AranyaAddTeamQuicSyncConfigBuilder` to construct this object.

AranyaAddTeamQuicSyncConfigBuilder

typedef struct AranyaAddTeamQuicSyncConfigBuilder AranyaAddTeamQuicSyncConfigBuilder

A builder for initializing an `AranyaAddTeamQuicSyncConfig`.

The `AranyaAddTeamQuicSyncConfig` is an optional part of initializing an `AranyaAddTeamConfig`.

AranyaAqcConfig

typedef struct AranyaAqcConfig AranyaAqcConfig

Configuration info for Aranya QUIC Channels.

Use a `AranyaAqcConfigBuilder` to construct this object.

AranyaAqcPeerChannel

typedef struct AranyaAqcPeerChannel AranyaAqcPeerChannel

A type containing the AQC channel variant.

Note that this data is only valid after a successful call to try_receive_channel, and is invalidated after calling get_bidi_channel/get_receive_channel.

AranyaClientConfig

typedef struct AranyaClientConfig AranyaClientConfig

Configuration info for Aranya.

Use a `AranyaClientConfigBuilder` to construct this object.

AranyaCreateTeamConfig

typedef struct AranyaCreateTeamConfig AranyaCreateTeamConfig

Team configuration used when creating a team.

Use a `AranyaCreateTeamConfigBuilder` to construct this object.

AranyaCreateTeamQuicSyncConfig

typedef struct AranyaCreateTeamQuicSyncConfig AranyaCreateTeamQuicSyncConfig

QUIC syncer configuration.

Use a `AranyaCreateTeamQuicSyncConfigBuilder` to construct this object.

AranyaCreateTeamQuicSyncConfigBuilder

typedef struct AranyaCreateTeamQuicSyncConfigBuilder AranyaCreateTeamQuicSyncConfigBuilder

A builder for initializing a `AranyaCreateTeamQuicSyncConfig`.

The `AranyaCreateTeamQuicSyncConfig` is an optional part of initializing a `AranyaCreateTeamConfig`.

AranyaExtError

typedef struct AranyaExtError AranyaExtError

• ─────────────────────── Extended‐error (_ext) Variants ───────────────────────
• Functions suffixed with _ext accept an extra
• struct AranyaExtError *ext_err parameter for extended error information.
• - ext_err must be a valid, non-NULL pointer.
• - If the call returns anything other than ARANYA_ERROR_SUCCESS,
• *ext_err is populated with additional error details.
• - On success, the content of ext_err is unchanged.
• - To extract a human-readable message:
• AranyaError aranya_ext_error_msg( * const struct AranyaExtError *err, * char *msg, * size_t *msg_len * );
• Example:
• struct AranyaExtError ext_err;
• AranyaError rc = aranya_get_device_id_ext(client, &id, &ext_err);
• if (rc != ARANYA_ERROR_SUCCESS) {
• size_t len = 0;
• aranya_ext_error_msg(&ext_err, NULL, &len);
• char *buf = malloc(len);
• aranya_ext_error_msg(&ext_err, buf, &len);
• // buf now holds the detailed error message
• }
• ────────────────────────────────────────────────────────────────────────────── Extended error information.

AranyaLabelName

typedef const char* AranyaLabelName

An AQC label name.

E.g. "TELEMETRY_LABEL"

AranyaNetIdentifier

typedef const char* AranyaNetIdentifier

A network identifier for an Aranya client.

E.g. "localhost:8080", "127.0.0.1:8080"

AranyaSyncPeerConfig

typedef struct AranyaSyncPeerConfig AranyaSyncPeerConfig

Sync Peer config.

Use a `AranyaSyncPeerConfigBuilder` to construct this object.

Enumeration Type Documentation

AranyaChanOp

enum AranyaChanOp

Valid channel operations for a label assignment.

Enumerator
ARANYA_CHAN_OP_RECV_ONLY	The device can only receive data in channels with this label.
ARANYA_CHAN_OP_SEND_ONLY	The device can only send data in channels with this label.
ARANYA_CHAN_OP_SEND_RECV	The device can send and receive data in channels with this label.

AranyaError

enum AranyaError

An error code.

For extended error information, see `AranyaExtError`.

Enumerator
ARANYA_ERROR_SUCCESS	Success.
ARANYA_ERROR_BUG	Internal bug discovered.
ARANYA_ERROR_TIMEOUT	Timed out.
ARANYA_ERROR_INVALID_ARGUMENT	Invalid argument.
ARANYA_ERROR_BUFFER_TOO_SMALL	Buffer is too small.
ARANYA_ERROR_INVALID_UTF8	Invalid UTF-8.
ARANYA_ERROR_INVALID_ADDR	Invalid Address.
ARANYA_ERROR_IPC	Could not send request to daemon.
ARANYA_ERROR_ARANYA	An Aranya error.
ARANYA_ERROR_AQC	AQC library error.
ARANYA_ERROR_WOULD_BLOCK	Tried to poll an endpoint but nothing received yet.
ARANYA_ERROR_CLOSED	A connection got unexpectedly closed.
ARANYA_ERROR_CONFIG	Unable to create configuration info.
ARANYA_ERROR_SERIALIZATION	Serialization error.
ARANYA_ERROR_OTHER	Some other error occurred.

AranyaRole

enum AranyaRole

An enum containing team roles defined in the Aranya policy.

Enumerator
ARANYA_ROLE_OWNER	Owner role.
ARANYA_ROLE_ADMIN	Admin role.
ARANYA_ROLE_OPERATOR	Operator role.
ARANYA_ROLE_MEMBER	Member role.

Function Documentation

aranya_init_logging()

AranyaError aranya_init_logging

(

void

)

Initializes logging.

Assumes the ARANYA_CAPI environment variable has been set to the desired tracing log level. E.g. ARANYA_CAPI=debug.

aranya_init_logging_ext()

AranyaError aranya_init_logging_ext

(

struct AranyaExtError *

__ext_err

)

Initializes logging.

Assumes the ARANYA_CAPI environment variable has been set to the desired tracing log level. E.g. ARANYA_CAPI=debug.

aranya_rand()

AranyaError aranya_rand	(	const struct AranyaClient *	client,
		uint8_t *	buf,
		size_t	buf_len
	)

Return random bytes from Aranya's CSPRNG.

This method can be used to generate a PSK seed IKM for the QUIC syncer.

Parameters

[in]	client	the Aranya Client `AranyaClient`.
[out]	buf	buffer where random bytes are written to.
[in]	buf_len	the size of the buffer.

aranya_rand_ext()

AranyaError aranya_rand_ext	(	const struct AranyaClient *	client,
		uint8_t *	buf,
		size_t	buf_len,
		struct AranyaExtError *	__ext_err
	)

Return random bytes from Aranya's CSPRNG.

This method can be used to generate a PSK seed IKM for the QUIC syncer.

Parameters

[in]	client	the Aranya Client `AranyaClient`.
[out]	buf	buffer where random bytes are written to.
[in]	buf_len	the size of the buffer.