A class for sending encrypted UDP datagrams. More...

#include <AsyncEncryptedUdpSocket.h>

Inheritance diagram for Async::EncryptedUdpSocket:

Public Types
using	Cipher = EVP_CIPHER

Public Member Functions
	EncryptedUdpSocket (uint16_t local_port=0, const IpAddress &bind_ip=IpAddress())
	Constructor.

	~EncryptedUdpSocket (void) override
	Disallow copy construction.

bool	initOk (void) const override
	Check if the initialization was ok.

bool	setCipher (const std::string &type)
	Set which cipher algorithm type to use.

bool	setCipher (const Cipher *cipher)
	Set which cipher algorithm type to use.

bool	setCipherIV (std::vector< uint8_t > iv)
	Set the initialization vector to use with the cipher.

const std::vector< uint8_t >	cipherIV (void) const
	Get a previously set initialization vector (IV)

bool	setCipherKey (std::vector< uint8_t > key)
	Set the cipher key to use.

bool	setCipherKey (void)
	Set a random cipher key to use.

const std::vector< uint8_t >	cipherKey (void) const
	Get the currently set cipher key.

void	setTagLength (int taglen)
	Set the length of the AEAD tag.

int	tagLength (void) const
	Get the currently set up tag length.

void	setCipherAADLength (int aadlen)
	Set the length of the associated data for AEAD ciphers.

size_t	cipherAADLength (void) const
	The currently set up length of the additional associated data.

bool	write (const IpAddress &remote_ip, int remote_port, const void *buf, int count) override
	Write data to the remote host.

bool	write (const IpAddress &remote_ip, int remote_port, const void aad, int aadlen, const void buf, int cnt)
	Write data to the remote host.

Public Member Functions inherited from Async::UdpSocket
	UdpSocket (uint16_t local_port=0, const IpAddress &bind_ip=IpAddress())
	Constructor.

virtual	~UdpSocket (void)
	Destructor.

Async::IpAddress	localAddr (void) const
	Get the local IP address associated with this connection.

uint16_t	localPort (void) const
	Get the local UDP port associated with this connection.

virtual int	fd (void) const
	Get the file descriptor for the UDP socket.

Static Public Member Functions
static const Cipher *	fetchCipher (const std::string &name)
	Fetch a named cipher object.

static void	freeCipher (Cipher *cipher)
	Free memory for a previously allocated cipher object.

static const std::string	cipherName (const Cipher *cipher)
	Get the name of a cipher from a cipher object.

static bool	randomBytes (std::vector< uint8_t > &bytes)
	Fill a vector with random bytes.

Public Attributes
sigc::signal< bool, const IpAddress &, uint16_t, void *, int >	cipherDataReceived
	A signal that is emitted when cipher data has been received.

sigc::signal< void, const IpAddress &, uint16_t, void , void , int >	dataReceived
	A signal that is emitted when cipher data has been decrypted.

Public Attributes inherited from Async::UdpSocket
sigc::signal< void, const IpAddress &, uint16_t, void *, int >	dataReceived
	A signal that is emitted when data has been received.

sigc::signal< void, bool >	sendBufferFull
	A signal that is emitted when the send buffer is full.

Protected Member Functions
void	onDataReceived (const IpAddress &ip, uint16_t port, void *buf, int count) override

Protected Member Functions inherited from Async::UdpSocket

Detailed Description

A class for sending encrypted UDP datagrams.

Author: Tobias Blomberg / SM0SVX

Date: 2023-07-23

Use this class to create a UDP socket that is used for sending and receiving encrypted UDP datagrams. The available ciphers are the block ciphers provided by the OpenSSL library, e.g. AES-128-GCM.

Definition at line 121 of file AsyncEncryptedUdpSocket.h.

Member Typedef Documentation

◆ Cipher

using Async::EncryptedUdpSocket::Cipher = EVP_CIPHER

Definition at line 124 of file AsyncEncryptedUdpSocket.h.

Constructor & Destructor Documentation

◆ EncryptedUdpSocket()

Async::EncryptedUdpSocket::EncryptedUdpSocket	(	uint16_t	local_port = 0,
		const IpAddress &	bind_ip = IpAddress() )

Constructor.

Parameters

local_port	The local UDP port to bind to, 0=ephemeral
bind_ip	The local interface (IP) to bind to

◆ ~EncryptedUdpSocket()

Async::EncryptedUdpSocket::~EncryptedUdpSocket ( void )

override

Disallow copy construction.

Disallow copy assignment

Destructor

Member Function Documentation

◆ cipherAADLength()

size_t Async::EncryptedUdpSocket::cipherAADLength ( void ) const

inline

The currently set up length of the additional associated data.

Returns: Returns the length of the associated data

Definition at line 302 of file AsyncEncryptedUdpSocket.h.

◆ cipherIV()

const std::vector< uint8_t > Async::EncryptedUdpSocket::cipherIV ( void ) const

Get a previously set initialization vector (IV)

Returns: Returns the IV or an empty vector if not set

◆ cipherKey()

const std::vector< uint8_t > Async::EncryptedUdpSocket::cipherKey ( void ) const

Get the currently set cipher key.

Returns: Returns the key or an empty vector if the key is not set

◆ cipherName()

static const std::string Async::EncryptedUdpSocket::cipherName ( const Cipher * cipher )

static

Get the name of a cipher from a cipher object.

Parameters

cipher The cipher object

Returns: Returns the name of the cipher

◆ fetchCipher()

static const Cipher * Async::EncryptedUdpSocket::fetchCipher ( const std::string & name )

static

Fetch a named cipher object.

Parameters

name	The name of the cipher

Returns: Return a pointer to a cipher object

Use this function to fetch a cipher object using its name, e.g. AES-128-GCM. The returned object must be freed using the freeCipher function if not used with the setCipher function. If the setCipher function has been used, the object does not have to be freed.

◆ freeCipher()

static void Async::EncryptedUdpSocket::freeCipher ( Cipher * cipher )

static

Free memory for a previously allocated cipher object.

Parameters

cipher The cipher object to free

◆ initOk()

bool Async::EncryptedUdpSocket::initOk ( void ) const

inlineoverridevirtual

Check if the initialization was ok.

Returns: Returns true if everything went fine during initialization or false if something went wrong

This function should always be called after constructing the object to see if everything went fine.

Reimplemented from Async::UdpSocket.

Definition at line 195 of file AsyncEncryptedUdpSocket.h.

References Async::UdpSocket::initOk().

◆ onDataReceived()

void Async::EncryptedUdpSocket::onDataReceived	(	const IpAddress &	ip,
		uint16_t	port,
		void *	buf,
		int	count )

overrideprotectedvirtual

Reimplemented from Async::UdpSocket.

◆ randomBytes()

static bool Async::EncryptedUdpSocket::randomBytes ( std::vector< uint8_t > & bytes )

static

Fill a vector with random bytes.

Parameters

bytes The vector to fill

Returns: Returns true on success

This function will fill the given vector with random bytes. Set the vector size to the number of bytes that should be generated. A zero length vector is valid and will always return true. A cryptographically secure pseudo random generator (CSPRNG) is used to generate the bytes.

◆ setCipher() [1/2]

bool Async::EncryptedUdpSocket::setCipher ( const Cipher * cipher )

Set which cipher algorithm type to use.

Parameters

cipher A pre-created cipher object

Returns: Return true on success

The setCipher function must be called before sending or receiving any datagrams. Use this function to set which block cipher algorithm to use.

◆ setCipher() [2/2]

bool Async::EncryptedUdpSocket::setCipher ( const std::string & type )

Set which cipher algorithm type to use.

Parameters

type	The algorithm type

Returns: Return true on success

This function must be called before sending or receiving any datagrams. Use this function to set which block cipher algorithm to use, e.g. AES-128-GCM, ChaCha20, NULL.

◆ setCipherAADLength()

void Async::EncryptedUdpSocket::setCipherAADLength ( int aadlen )

inline

Set the length of the associated data for AEAD ciphers.

Parameters

aadlen The length of the additional associated data

Some ciphers, like AES-128-GCM, support AEAD (Authenticated Encryption with Associated Data). A tag is then sent with the encrypted data to authenticate the sender of the data. Associated data, which is not encypted, can be sent along with the encrypted data. The associated data will be protected by the authentication present in AEAD ciphers if a tag is sent along with the encrypted data (

See also: setTagLength).

Definition at line 296 of file AsyncEncryptedUdpSocket.h.

◆ setCipherIV()

bool Async::EncryptedUdpSocket::setCipherIV ( std::vector< uint8_t > iv )

Set the initialization vector to use with the cipher.

Parameters

iv	The initialization vector

Returns: Returns true on success

This function will set the initialization vector (IV) to use with the selected cipher. Different ciphers require different IVs. Find and read the requirements for a specific cipher for constructing a safe IV. The setCipher function must be called before calling this function.

◆ setCipherKey() [1/2]

bool Async::EncryptedUdpSocket::setCipherKey ( std::vector< uint8_t > key )

Set the cipher key to use.

Parameters

key	The cipher key

Returns: Returns true on success

This function will set the key to use with the selected cipher. Different ciphers require different keys. Find and read the requirements for a specific cipher for constructing a key. The setCipher function must be called before calling this function.

◆ setCipherKey() [2/2]

bool Async::EncryptedUdpSocket::setCipherKey ( void )

Set a random cipher key to use.

Returns: Returns true on success

This function will set a random key to use with the selected cipher. A cryptographically secure pseudo random generator (CSPRNG) is used to generate the key. The setCipher function must be called before calling this function.

◆ setTagLength()

void Async::EncryptedUdpSocket::setTagLength ( int taglen )

inline

Set the length of the AEAD tag.

Parameters

taglen The length of the tag in bytes

Some ciphers, like AES-128-GCM, support AEAD (Authenticated Encryption with Associated Data). A tag is then sent with the encrypted data to authenticate the sender of the data. The tag can have differing lengths for different applications and different levels of security.

Definition at line 277 of file AsyncEncryptedUdpSocket.h.

◆ tagLength()

int Async::EncryptedUdpSocket::tagLength ( void ) const

inline

Get the currently set up tag length.

Returns: Returns the tag length

Definition at line 283 of file AsyncEncryptedUdpSocket.h.

◆ write() [1/2]

bool Async::EncryptedUdpSocket::write	(	const IpAddress &	remote_ip,
		int	remote_port,
		const void *	aad,
		int	aadlen,
		const void *	buf,
		int	cnt )

Write data to the remote host.

Parameters

remote_ip	The IP-address of the remote host
remote_port	The remote port to use
aad	Prepended unencrypted data
buf	A buffer containing the data to send
count	The number of bytes to write

Returns: Return true on success or false on failure

◆ write() [2/2]

bool Async::EncryptedUdpSocket::write	(	const IpAddress &	remote_ip,
		int	remote_port,
		const void *	buf,
		int	count )

overridevirtual

Write data to the remote host.

Parameters

remote_ip	The IP-address of the remote host
remote_port	The remote port to use
buf	A buffer containing the data to send
count	The number of bytes to write

Returns: Return true on success or false on failure

Reimplemented from Async::UdpSocket.

Member Data Documentation

◆ cipherDataReceived

sigc::signal<bool, const IpAddress&, uint16_t, void*, int> Async::EncryptedUdpSocket::cipherDataReceived

A signal that is emitted when cipher data has been received.

Parameters

ip	The IP-address the data was received from
port	The remote port number
buf	The buffer containing the read cipher data
count	The number of bytes read

Definition at line 335 of file AsyncEncryptedUdpSocket.h.

◆ dataReceived

sigc::signal<void, const IpAddress&, uint16_t, void*, void*, int> Async::EncryptedUdpSocket::dataReceived

A signal that is emitted when cipher data has been decrypted.

Parameters

ip	The IP-address the data was received from
port	The remote port number
aad	Additional Associated Data
buf	The buffer containing the read data
count	The number of bytes read

Definition at line 346 of file AsyncEncryptedUdpSocket.h.

The documentation for this class was generated from the following file:

AsyncEncryptedUdpSocket.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Cipher

Constructor & Destructor Documentation

◆ EncryptedUdpSocket()

◆ ~EncryptedUdpSocket()

Member Function Documentation

◆ cipherAADLength()

◆ cipherIV()

◆ cipherKey()

◆ cipherName()

◆ fetchCipher()

◆ freeCipher()

◆ initOk()

◆ onDataReceived()

◆ randomBytes()

◆ setCipher() [1/2]

◆ setCipher() [2/2]

◆ setCipherAADLength()

◆ setCipherIV()

◆ setCipherKey() [1/2]

◆ setCipherKey() [2/2]

◆ setTagLength()

◆ tagLength()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ cipherDataReceived

◆ dataReceived