network.h File Reference

The AERN network functions. More...

#include "aerncommon.h"
#include "topology.h"
#include "collection.h"
#include "sha3.h"
#include "socket.h"

Go to the source code of this file.

Data Structures
struct	aern_network_announce_request_state
	The certificate announce request function state. More...
struct	aern_network_announce_response_state
	The certificate announce response function state. More...
struct	aern_network_converge_request_state
	The certificate converge request function state. More...
struct	aern_network_converge_response_state
	The certificate converge response function state. More...
struct	aern_network_converge_response_verify_state
	The certificate converge verify function state. More...
struct	aern_network_converge_update_verify_state
	The certificate converge update verify function state. More...
struct	aern_network_fkey_request_state
	The fkey request function state. More...
struct	aern_network_fkey_response_state
	The fkey response function state. More...
struct	aern_network_incremental_update_request_state
	The incremental update request function state. More...
struct	aern_network_incremental_update_response_state
	The incremental update response function state. More...
struct	aern_network_register_request_state
	The network join request function state. More...
struct	aern_network_register_response_state
	The network join response function state. More...
struct	aern_network_register_update_request_state
	The network join request function state. More...
struct	aern_network_register_update_response_state
	The network join update response function state. More...
struct	aern_network_mfk_request_state
	The mfk request function state. More...
struct	aern_network_mfk_response_state
	The mfk response function state. More...
struct	aern_network_remote_signing_request_state
	The certificate remote signing request function state. More...
struct	aern_network_remote_signing_response_state
	The certificate remote signing response function state. More...
struct	aern_network_resign_request_state
	The certificate resign request function state. More...
struct	aern_network_resign_response_state
	The certificate resign request function state. More...
struct	aern_network_revoke_request_state
	The certificate revoke request function state. More...
struct	aern_network_revoke_response_state
	The certificate revoke response function state. More...
struct	aern_network_topological_query_request_state
	The topological query request function state. More...
struct	aern_network_topological_query_response_state
struct	aern_network_topological_status_request_state
	The topological status request function state. More...
struct	aern_network_topological_status_response_state
	The topological status response function state. More...
struct	aern_network_fragment_collection_request_state
	The fkey collection request function state. More...
struct	aern_network_fragment_collection_response_state
	The fkey collection response function state. More...
struct	aern_network_fragment_query_request_state
	The fkey query request function state. More...
struct	aern_network_fragment_query_response_state
	The fkey query response function state. More...
struct	aern_network_key_exchange_request_state
	The key exchange request function state. More...
struct	aern_network_key_exchange_response_state
	The key exchange response function state. More...

Typedefs
typedef AERN_EXPORT_API struct aern_network_announce_request_state	aern_network_announce_request_state
typedef AERN_EXPORT_API struct aern_network_announce_response_state	aern_network_announce_response_state
typedef AERN_EXPORT_API struct aern_network_converge_request_state	aern_network_converge_request_state
typedef AERN_EXPORT_API struct aern_network_converge_response_state	aern_network_converge_response_state
typedef AERN_EXPORT_API struct aern_network_converge_response_verify_state	aern_network_converge_response_verify_state
typedef AERN_EXPORT_API struct aern_network_converge_update_verify_state	aern_network_converge_update_verify_state
typedef AERN_EXPORT_API struct aern_network_fkey_request_state	aern_network_fkey_request_state
typedef AERN_EXPORT_API struct aern_network_fkey_response_state	aern_network_fkey_response_state
typedef AERN_EXPORT_API struct aern_network_incremental_update_request_state	aern_network_incremental_update_request_state
typedef AERN_EXPORT_API struct aern_network_incremental_update_response_state	aern_network_incremental_update_response_state
typedef AERN_EXPORT_API struct aern_network_register_request_state	aern_network_register_request_state
typedef AERN_EXPORT_API struct aern_network_register_response_state	aern_network_register_response_state
typedef AERN_EXPORT_API struct aern_network_register_update_request_state	aern_network_register_update_request_state
typedef AERN_EXPORT_API struct aern_network_register_update_response_state	aern_network_register_update_response_state
typedef AERN_EXPORT_API struct aern_network_mfk_request_state	aern_network_mfk_request_state
typedef AERN_EXPORT_API struct aern_network_mfk_response_state	aern_network_mfk_response_state
typedef AERN_EXPORT_API struct aern_network_remote_signing_request_state	aern_network_remote_signing_request_state
typedef AERN_EXPORT_API struct aern_network_remote_signing_response_state	aern_network_remote_signing_response_state
typedef AERN_EXPORT_API struct aern_network_resign_request_state	aern_network_resign_request_state
typedef AERN_EXPORT_API struct aern_network_resign_response_state	aern_network_resign_response_state
typedef AERN_EXPORT_API struct aern_network_revoke_request_state	aern_network_revoke_request_state
typedef AERN_EXPORT_API struct aern_network_revoke_response_state	aern_network_revoke_response_state
typedef AERN_EXPORT_API struct aern_network_topological_query_request_state	aern_network_topological_query_request_state
typedef AERN_EXPORT_API struct aern_network_topological_query_response_state	aern_network_topological_query_response_state
typedef AERN_EXPORT_API struct aern_network_topological_status_request_state	aern_network_topological_status_request_state
typedef AERN_EXPORT_API struct aern_network_topological_status_response_state	aern_network_topological_status_response_state
typedef AERN_EXPORT_API struct aern_network_fragment_collection_request_state	aern_network_fragment_collection_request_state
typedef AERN_EXPORT_API struct aern_network_fragment_collection_response_state	aern_network_fragment_collection_response_state
typedef AERN_EXPORT_API struct aern_network_fragment_query_request_state	aern_network_fragment_query_request_state
typedef AERN_EXPORT_API struct aern_network_fragment_query_response_state	aern_network_fragment_query_response_state
typedef AERN_EXPORT_API struct aern_network_key_exchange_request_state	aern_network_key_exchange_request_state
typedef AERN_EXPORT_API struct aern_network_key_exchange_response_state	aern_network_key_exchange_response_state

Functions
AERN_EXPORT_API aern_protocol_errors	aern_network_announce_broadcast (aern_network_announce_request_state *state)
	Announce a certificate using the ads, and broadcast it to the network.
AERN_EXPORT_API aern_protocol_errors	aern_network_announce_response (aern_network_announce_response_state *state, const aern_network_packet *packetin)
	Process a announce response message.
AERN_EXPORT_API uint16_t	aern_network_application_to_port (aern_network_designations tnode)
	Gets the network designation from a port number.
AERN_EXPORT_API void	aern_network_broadcast_message (const aern_topology_list_state *list, const uint8_t *message, size_t msglen, aern_network_designations tnode)
	Broadcast a message to a node type on the network.
AERN_EXPORT_API qsc_socket_exceptions	aern_network_connect_to_device (qsc_socket *csock, const char *address, aern_network_designations designation)
	Connect a socket to a remote address.
AERN_EXPORT_API aern_protocol_errors	aern_network_converge_request (const aern_network_converge_request_state *state)
	The ADC sends out a convergence request, and broadcast it to the network.
AERN_EXPORT_API aern_protocol_errors	aern_network_converge_response (const aern_network_converge_response_state *state, const aern_network_packet *packetin)
	Respond to a ads network converge request.
AERN_EXPORT_API qsc_socket_exceptions	aern_network_connect_to_address (qsc_socket *csock, const char *address, uint16_t port)
	Connect a socket to a remote address and port.
AERN_EXPORT_API aern_protocol_errors	aern_network_fkey_request (aern_network_fkey_request_state *state)
	Request and execute a key exchange for a fragmentation key.
AERN_EXPORT_API aern_protocol_errors	aern_network_fkey_response (aern_network_fkey_response_state *state, const aern_network_packet *packetin)
	Respond and execute a key exchange for a fragmentation key.
AERN_EXPORT_API bool	aern_network_get_local_address (char address[AERN_CERTIFICATE_ADDRESS_SIZE])
	Get the local IP address.
AERN_EXPORT_API aern_protocol_errors	aern_network_send_error (const qsc_socket *csock, aern_protocol_errors error)
	Send an error message.
AERN_EXPORT_API void	aern_network_socket_dispose (qsc_socket *csock)
	Shut down and dispose of a socket instance.
AERN_EXPORT_API aern_protocol_errors	aern_network_incremental_update_request (const aern_network_incremental_update_request_state *state)
	Send an incremental update request.
AERN_EXPORT_API aern_protocol_errors	aern_network_incremental_update_response (const aern_network_incremental_update_response_state *state, const aern_network_packet *packetin)
	Send a copy of a certificate to a remote host.
AERN_EXPORT_API aern_protocol_errors	aern_network_register_request (aern_network_register_request_state *state)
	Send an APS join request to the ADC.
AERN_EXPORT_API aern_protocol_errors	aern_network_register_update_request (aern_network_register_update_request_state *state)
	Send a MAS or Client join update request to the ADC.
AERN_EXPORT_API aern_protocol_errors	aern_network_register_response (aern_network_register_response_state *state, const aern_network_packet *packetin)
	Send a join response to the aps.
AERN_EXPORT_API aern_protocol_errors	aern_network_register_update_response (aern_network_register_update_response_state *state, const aern_network_packet *packetin)
	Send a join update response to the server or client.
AERN_EXPORT_API aern_protocol_errors	aern_network_remote_signing_request (aern_network_remote_signing_request_state *state)
	Send a certificate signing request from the ADC to the ARS.
AERN_EXPORT_API aern_protocol_errors	aern_network_remote_signing_response (aern_network_remote_signing_response_state *state, const aern_network_packet *packetin)
	Send a signed certificate response from the ARS to the ADC.
AERN_EXPORT_API aern_protocol_errors	aern_network_mfk_exchange_request (aern_network_mfk_request_state *state)
	Request and execute a key exchange request for a master fragmentation key.
AERN_EXPORT_API aern_protocol_errors	aern_network_mfk_exchange_response (aern_network_mfk_response_state *state, const aern_network_packet *packetin)
	Request and execute a key exchange response for a master fragmentation key.
AERN_EXPORT_API aern_network_designations	aern_network_port_to_application (uint16_t port)
	Gets the network designation from a port number.
AERN_EXPORT_API aern_protocol_errors	aern_network_certificate_verify (const aern_child_certificate *ccert, const aern_root_certificate *root)
	Verify a certificates format and root signature.
AERN_EXPORT_API aern_protocol_errors	aern_network_resign_request (const aern_network_resign_request_state *state)
	Send a resign request to the ads.
AERN_EXPORT_API aern_protocol_errors	aern_network_resign_response (aern_network_resign_response_state *state, const aern_network_packet *packetin)
	Send a resign response to the aps or server.
AERN_EXPORT_API aern_protocol_errors	aern_network_revoke_broadcast (aern_network_revoke_request_state *state)
	Send a revocation request from the ADC.
AERN_EXPORT_API aern_protocol_errors	aern_network_revoke_response (aern_network_revoke_response_state *state, const aern_network_packet *packetin)
	Verify a revocation request sent from the ADC.
AERN_EXPORT_API aern_protocol_errors	aern_network_topological_query_request (const aern_network_topological_query_request_state *state)
	Query a device for its topological information.
AERN_EXPORT_API aern_protocol_errors	aern_network_topological_query_response (const aern_network_topological_query_response_state *state, const aern_network_packet *packetin)
	Respond to a topological query request.
AERN_EXPORT_API aern_protocol_errors	aern_network_topological_status_request (const aern_network_topological_status_request_state *state)
	Send a status request from the ADC to a client device.
AERN_EXPORT_API aern_protocol_errors	aern_network_topological_status_response (const aern_network_topological_status_response_state *state, const aern_network_packet *packetin)
	Process the status response from the client device and send a response.

Detailed Description

The AERN network functions.

This header defines the public network functions and data types used by AERN to perform secure network operations. These operations include certificate announcement, network convergence, registration and update of network nodes, key exchange, remote signing, revocation, and topological queries.

Each network message is encapsulated in a packet that includes a header (with a time-stamp, sequence number, and flag), a payload, and a digital signature that covers the payload and header. This ensures integrity, authenticity, and protection against replay attacks.

Note

This header declares only the public API. Many internal functions (such as those for constructing and validating packet headers, hashing, signing, etc.) are defined as static in the implementation file.

Example:

aern_network_announce_request_state req_state;
req_state.list   = &global_topology_list;
req_state.rnode  = &remote_node;
req_state.sigkey = local_signing_key;
 
aern_protocol_errors err = aern_network_announce_broadcast(&req_state);
if (err != aern_protocol_error_none)
{
    // Handle error.
}

Function Documentation

aern_network_announce_broadcast()

AERN_EXPORT_API aern_protocol_errors aern_network_announce_broadcast

(

aern_network_announce_request_state *

state

)

Announce a certificate using the ads, and broadcast it to the network.

Parameters

state

The announce state structure

Returns

Returns the error code

aern_network_announce_response()

AERN_EXPORT_API aern_protocol_errors aern_network_announce_response	(	aern_network_announce_response_state *	state,
		const aern_network_packet *	packetin )

Process a announce response message.

Parameters

state	The announce response state structure
packetin	[const] The input packet containing the announce request

Returns

Returns the error code

aern_network_application_to_port()

AERN_EXPORT_API uint16_t aern_network_application_to_port

(

aern_network_designations

tnode

)

Gets the network designation from a port number.

Parameters

tnode

The target network designation type

Returns

Returns the port number, or zero if the node type is invalid

aern_network_broadcast_message()

AERN_EXPORT_API void aern_network_broadcast_message	(	const aern_topology_list_state *	list,
		const uint8_t *	message,
		size_t	msglen,
		aern_network_designations	tnode )

Broadcast a message to a node type on the network.

Parameters

list	[const] A pointer to the topology list
message	The message to send
msglen	The length of the message
tnode	The target node-type designation

aern_network_certificate_verify()

AERN_EXPORT_API aern_protocol_errors aern_network_certificate_verify	(	const aern_child_certificate *	ccert,
		const aern_root_certificate *	root )

Verify a certificates format and root signature.

Parameters

ccert	[const] The child certificate
root	[const] The root certificate

Returns

Returns the error code

aern_network_connect_to_address()

AERN_EXPORT_API qsc_socket_exceptions aern_network_connect_to_address	(	qsc_socket *	csock,
		const char *	address,
		uint16_t	port )

Connect a socket to a remote address and port.

Parameters

csock	A pointer to the socket
address	[const] The remote hosts address
port	The application port number

Returns

Returns the socket error

aern_network_connect_to_device()

AERN_EXPORT_API qsc_socket_exceptions aern_network_connect_to_device	(	qsc_socket *	csock,
		const char *	address,
		aern_network_designations	designation )

Connect a socket to a remote address.

Parameters

csock	A pointer to the socket
address	[const] The remote hosts address
designation	The remote hosts designation

Returns

Returns the socket error

aern_network_converge_request()

AERN_EXPORT_API aern_protocol_errors aern_network_converge_request

(

const aern_network_converge_request_state *

state

)

The ADC sends out a convergence request, and broadcast it to the network.

Parameters

state

The converge request state structure

Returns

Returns the error code

aern_network_converge_response()

AERN_EXPORT_API aern_protocol_errors aern_network_converge_response	(	const aern_network_converge_response_state *	state,
		const aern_network_packet *	packetin )

Respond to a ads network converge request.

Parameters

state	The converge response state structure
packetin	[const] The input packet containing the verify response

Returns

Returns the error code

aern_network_fkey_request()

AERN_EXPORT_API aern_protocol_errors aern_network_fkey_request

(

aern_network_fkey_request_state *

state

)

Request and execute a key exchange for a fragmentation key.

Parameters

state

The fkey request state structure

Returns

Returns the error code

aern_network_fkey_response()

AERN_EXPORT_API aern_protocol_errors aern_network_fkey_response	(	aern_network_fkey_response_state *	state,
		const aern_network_packet *	packetin )

Respond and execute a key exchange for a fragmentation key.

Parameters

state	The fkey response state structure
packetin	[const] The input packet containing the request

Returns

Returns the error code

aern_network_get_local_address()

AERN_EXPORT_API bool aern_network_get_local_address

(

char

address[AERN_CERTIFICATE_ADDRESS_SIZE]

)

Get the local IP address.

Parameters

address

The output address byte array

Returns

Returns true if the address is retrieved

aern_network_incremental_update_request()

AERN_EXPORT_API aern_protocol_errors aern_network_incremental_update_request

(

const aern_network_incremental_update_request_state *

state

)

Send an incremental update request.

Parameters

state

The incremental update request function state

Returns

Returns the error code

aern_network_incremental_update_response()

AERN_EXPORT_API aern_protocol_errors aern_network_incremental_update_response	(	const aern_network_incremental_update_response_state *	state,
		const aern_network_packet *	packetin )

Send a copy of a certificate to a remote host.

Parameters

state

The update response function state

Returns

Returns the error code

aern_network_mfk_exchange_request()

AERN_EXPORT_API aern_protocol_errors aern_network_mfk_exchange_request

(

aern_network_mfk_request_state *

state

)

Request and execute a key exchange request for a master fragmentation key.

Parameters

state

The mfk request state structure

Returns

Returns the error code

aern_network_mfk_exchange_response()

AERN_EXPORT_API aern_protocol_errors aern_network_mfk_exchange_response	(	aern_network_mfk_response_state *	state,
		const aern_network_packet *	packetin )

Request and execute a key exchange response for a master fragmentation key.

Parameters

state	The mfk response state structure
packetin	[const] The input packet containing the request

Returns

Returns the error code

aern_network_port_to_application()

AERN_EXPORT_API aern_network_designations aern_network_port_to_application

(

uint16_t

port

)

Gets the network designation from a port number.

Parameters

port	The network application port

Returns

Returns the network designation type

aern_network_register_request()

AERN_EXPORT_API aern_protocol_errors aern_network_register_request

(

aern_network_register_request_state *

state

)

Send an APS join request to the ADC.

Parameters

state

The join request function state

Returns

Returns the error code

aern_network_register_response()

AERN_EXPORT_API aern_protocol_errors aern_network_register_response	(	aern_network_register_response_state *	state,
		const aern_network_packet *	packetin )

Send a join response to the aps.

Parameters

state	The join response function state
packetin	[const] The input packet containing the request

Returns

Returns a protocol error flag

aern_network_register_update_request()

AERN_EXPORT_API aern_protocol_errors aern_network_register_update_request

(

aern_network_register_update_request_state *

state

)

Send a MAS or Client join update request to the ADC.

Parameters

state

The join update request function state

Returns

Returns the error code

aern_network_register_update_response()

AERN_EXPORT_API aern_protocol_errors aern_network_register_update_response	(	aern_network_register_update_response_state *	state,
		const aern_network_packet *	packetin )

Send a join update response to the server or client.

Parameters

state	The join response function state
packetin	[const] The input packet containing the request

Returns

Returns a protocol error flag

aern_network_remote_signing_request()

AERN_EXPORT_API aern_protocol_errors aern_network_remote_signing_request

(

aern_network_remote_signing_request_state *

state

)

Send a certificate signing request from the ADC to the ARS.

Parameters

state

The remote signing request state

Returns

Returns a protocol error flag

aern_network_remote_signing_response()

AERN_EXPORT_API aern_protocol_errors aern_network_remote_signing_response	(	aern_network_remote_signing_response_state *	state,
		const aern_network_packet *	packetin )

Send a signed certificate response from the ARS to the ADC.

Parameters

state	The remote signing response state
packetin	[const] The input packet containing the request

Returns

Returns a protocol error flag

aern_network_resign_request()

AERN_EXPORT_API aern_protocol_errors aern_network_resign_request

(

const aern_network_resign_request_state *

state

)

Send a resign request to the ads.

Parameters

state

The resign request state structure

Returns

Returns the error code

aern_network_resign_response()

AERN_EXPORT_API aern_protocol_errors aern_network_resign_response	(	aern_network_resign_response_state *	state,
		const aern_network_packet *	packetin )

Send a resign response to the aps or server.

Parameters

state	The resign response state structure
packetin	[const] The input packet containing the request

Returns

Returns the error code

aern_network_revoke_broadcast()

AERN_EXPORT_API aern_protocol_errors aern_network_revoke_broadcast

(

aern_network_revoke_request_state *

state

)

Send a revocation request from the ADC.

Parameters

state

The revocation broadcast function state

Returns

Returns a protocol error flag

aern_network_revoke_response()

AERN_EXPORT_API aern_protocol_errors aern_network_revoke_response	(	aern_network_revoke_response_state *	state,
		const aern_network_packet *	packetin )

Verify a revocation request sent from the ADC.

Parameters

state	The revocation verify function state
packetin	[const] The input packet containing the request

Returns

Returns a protocol error flag

aern_network_send_error()

AERN_EXPORT_API aern_protocol_errors aern_network_send_error	(	const qsc_socket *	csock,
		aern_protocol_errors	error )

Send an error message.

Parameters

csock	A pointer to the socket
error	The error code

Returns

Returns the error code

aern_network_socket_dispose()

AERN_EXPORT_API void aern_network_socket_dispose

(

qsc_socket *

csock

)

Shut down and dispose of a socket instance.

Parameters

csock

A pointer to the socket

aern_network_topological_query_request()

AERN_EXPORT_API aern_protocol_errors aern_network_topological_query_request

(

const aern_network_topological_query_request_state *

state

)

Query a device for its topological information.

Parameters

state

The topological query request state

Returns

Returns the error code

aern_network_topological_query_response()

AERN_EXPORT_API aern_protocol_errors aern_network_topological_query_response	(	const aern_network_topological_query_response_state *	state,
		const aern_network_packet *	packetin )

Respond to a topological query request.

Parameters

state	topological query response state
packetin	The packet containing the topological query request

Returns

Returns the error code

aern_network_topological_status_request()

AERN_EXPORT_API aern_protocol_errors aern_network_topological_status_request

(

const aern_network_topological_status_request_state *

state

)

Send a status request from the ADC to a client device.

Parameters

state	The topological status request state
query	The device query string

Returns

Returns the error code

aern_network_topological_status_response()

AERN_EXPORT_API aern_protocol_errors aern_network_topological_status_response	(	const aern_network_topological_status_response_state *	state,
		const aern_network_packet *	packetin )

Process the status response from the client device and send a response.

Parameters

state	The topological status response state
packetin	The packet containing the topological status request

Returns

Returns the error code