2.2.2 Communication Interfaces

The base class aiounicast and the corresponding derived classes aiounicast_nonblock and aiounicast_select provide a simple communication interface for asynchronous point-to-point communication channels. They can be used to transfer data of type mpz_t (big integers, see libgmp for explanation of this data type) between up to n parties, that are connected by sockets, pipes or any other file descriptor based input/output mechanism.

Moreover, the channels can be authenticated by a message authentication code and encrypted by a symmetric cipher. The deployed algorithms are defined by global symbols (TMCG_GCRY_MAC_ALGO and TMCG_GCRY_ENC_ALGO, respectively) and fixed at compile time of LibTMCG.

Class: aiounicast

This class is only an abstract interface and cannot be instantiated directly. We explain some basic class members that are useful for an application programmer.

Member of aiounicast: static const time_t aio_timeout_very_short

This constant defines a very short time interval of only one second.

Member of aiounicast: static const time_t aio_timeout_short

This constant defines a short time interval of 15 seconds.

Member of aiounicast: static const time_t aio_timeout_middle

This constant defines a middle time interval of 30 seconds.

Member of aiounicast: static const time_t aio_timeout_long

This constant defines a long time interval of 90 seconds.

Member of aiounicast: static const time_t aio_timeout_very_long

This constant defines a very long time interval of 180 seconds.

Member of aiounicast: static const time_t aio_timeout_extremly_long

This constant defines an extremly long time interval of 300 seconds.

Member of aiounicast: static const size_t aio_scheduler_roundrobin

This constant represents the round-robin scheduler for message processing.

Member of aiounicast: static const size_t aio_scheduler_random

This constant represents the random select scheduler for message processing.

Member of aiounicast: static const size_t aio_scheduler_direct

This constant represents the constant select scheduler for message processing.

Member of aiounicast: const size_t n

This is the total number of parties n involved in the communication.

Member of aiounicast: const size_t j

This is an uniqe index of the party running this instance.

Member of aiounicast: std::map<size_t, int> fd_in

The input file descriptors of point-to-point links to all parties.

Member of aiounicast: std::map<size_t, int> fd_out

The ouput file descriptors of point-to-point links to all parties.

Member of aiounicast: size_t numWrite

The total number of bytes written to point-to-point links.

Member of aiounicast: size_t numRead

The total number of bytes read from point-to-point links.

Member of aiounicast: size_t numEncrypted

The total number of bytes that have been encrypted yet.

Member of aiounicast: size_t numDecrypted

The total number of bytes that have been decrypted yet.

Member of aiounicast: size_t numAuthenticated

The total number of bytes that have been authenticated yet.

Note that the header files aiounicast_nonblock.hh or aiounicast_select.hh must be included in addition to libTMCG.hh. The use of class aiounicast_select is strongly recommended.

Class: aiounicast_nonblock

This class works with non-blocking file descriptors, i.e., the pipes or sockets have to be opened with the O_NONBLOCK flag. The methods use continiuous polling on the descriptors to achieve asynchronous I/O that results in exorbitant CPU load. The class should be used only, if no select system call is available or appropriate for the application.

Constructor on aiounicast_nonblock: aiounicast_nonblock (const size_t n_in, const size_t j_in, const std::vector<int>& fd_in_in, const std::vector<int>& fd_out_in, const std::vector<std::string>& key_in, const size_t aio_default_scheduler_in =aio_scheduler_roundrobin, const time_t aio_default_timeout_in =aio_timeout_long, const bool aio_is_authenticated_in =true, const bool aio_is_encrypted_in =true)

The constructor initializes internal queues and data structures for asynchronous point-to-point channels connecting n parties (i.e. n_in). The index of the calling party within this set is given by j_in. It is followed by a vector fd_in_in of exactly n input file descriptors that are ready for reading and writing, and by a vector fd_out_in of exactly n output file descriptors. Finally, the vector key_in with exactly n passphrases⁸ or pre-shared keys is neccesary, if aio_is_authenticated_in or aio_is_encrypted_in is set true, which is the default behaviour. The default values for timeout (in seconds) and the receive scheduler can be modified carefully according to the desired usage scenario.

Method on aiounicast_nonblock: bool Send (mpz_srcptr m, const size_t i_in, time_t timeout =aio_timeout_default)

This method sends an integer m over the corresponding point-to-point link to the party with index i_in. In presence of the third argument this transmission is tried for at most timeout seconds. Otherwise, the default timeout given to the constructor is applied.

The method returns false, if sending fails, and error messages are written to std::cerr.

Method on aiounicast_nonblock: bool Send (const std::vector<mpz_srcptr>& m, const size_t i_in, time_t timeout =aio_timeout_default)

This method works as above, however, a vector m of integers is sent.

Method on aiounicast_nonblock: bool Receive (mpz_ptr m, size_t& i_out, size_t scheduler =aio_scheduler_default, time_t timeout =aio_timeout_default)

This method receives an integer m over the point-to-point links from any party. The index of the sender is returned in i_out. In presence of the third argument it waits for at most timeout seconds. Otherwise, the default timeout given to the constructor is applied.

The method returns false, if receiving fails. Only in critical cases some error messages are written to std::cerr.

Method on aiounicast_nonblock: bool Receive (std::vector<mpz_ptr>& m, size_t& i_out, size_t scheduler =aio_scheduler_default, time_t timeout =aio_timeout_default)

This method works as above, however, a vector m of integers is received.

Destructor on aiounicast_nonblock: ~aiounicast_nonblock ()

This destructor releases all occupied resources.

Class: aiounicast_select

This class works with arbitrary file descriptors. It uses the select interface of the operation system with negligible timeout of 1000us to achieve asynchronous I/O. This results in a reasonable CPU load in comparison with aiounicast_nonblock.

Constructor on aiounicast_select: aiounicast_select (const size_t n_in, const size_t j_in, const std::vector<int>& fd_in_in, const std::vector<int>& fd_out_in, const std::vector<std::string>& key_in, const size_t aio_default_scheduler_in =aio_scheduler_roundrobin, const time_t aio_default_timeout_in =aio_timeout_long, const bool aio_is_authenticated_in =true, const bool aio_is_encrypted_in =true)

The constructor initializes internal queues and data structures for asynchronous point-to-point channels connecting n parties (i.e. n_in). The index of the calling party within this set is given by j_in. It is followed by a vector fd_in_in of exactly n input file descriptors that are ready for reading and writing, and by a vector fd_out_in of exactly n output file descriptors. Finally, the vector key_in with exactly n passphrases⁹ or pre-shared keys is neccesary, if aio_is_authenticated_in or aio_is_encrypted_in is set true, which is the default behaviour. The default values for timeout (in seconds) and the receive scheduler can be modified carefully according to the desired usage scenario.

Method on aiounicast_select: bool Send (mpz_srcptr m, const size_t i_in, time_t timeout =aio_timeout_default)

This method sends an integer m over the corresponding point-to-point link to the party with index i_in. In presence of the third argument this transmission is tried for at most timeout seconds. Otherwise, the default timeout given to the constructor is applied.

The method returns false, if sending fails, and error messages are written to std::cerr.

Method on aiounicast_select: bool Send (const std::vector<mpz_srcptr>& m, const size_t i_in, time_t timeout =aio_timeout_default)

This method works as above, however, a vector m of integers is sent.

Method on aiounicast_select: bool Receive (mpz_ptr m, size_t& i_out, size_t scheduler =aio_scheduler_default, time_t timeout =aio_timeout_default)

This method receives an integer m over the point-to-point links from any party. The index of the sender is returned in i_out. In presence of the third argument it waits for at most timeout seconds. Otherwise, the default timeout given to the constructor is applied.

The method returns false, if receiving fails. Only in critical cases some error messages are written to std::cerr.

Method on aiounicast_select: bool Receive (std::vector<mpz_ptr>& m, size_t& i_out, size_t scheduler =aio_scheduler_default, time_t timeout =aio_timeout_default)

This method works as above, however, a vector m of integers is received.

Destructor on aiounicast_select: ~aiounicast_select ()

This destructor releases all occupied resources.