Wrapper for the SCM_RIGHTS socket ancillary message to pass file descriptors to other processes. More...

#include <unix_aux.hxx>

Inheritance diagram for cosmos::UnixRightsMessage:

Public Types
using	FileNumVector = std::vector<FileNum>
	A vector to keep a series of FileNum file descriptor numbers to pass between processes.

Public Member Functions
void	deserialize (const ReceiveMessageHeader::ControlMessage &msg)
	Parse received file descriptors from the given ControlMessage.

SendMessageHeader::ControlMessage	serialize () const
	Serialize a ControlMessage for passing file descriptors.

void	addFD (cosmos::FileNum fd)

void	clearFDs ()

void	takeFDs (FileNumVector &fds)

size_t	numFDs () const

Static Public Attributes
static constexpr size_t	MAX_FDS = 253
	Maximum number of file descriptors that can be transferred using a single UnixRightsMessage.

Protected Member Functions
void	closeUnclaimed ()

Protected Member Functions inherited from cosmos::AncillaryMessage< OptLevel::SOCKET, UnixMessage >
SendMessageHeader::ControlMessage	createMsg (UnixMessage type, const size_t data_len) const

void	checkMsg (const ReceiveMessageHeader::ControlMessage &msg, UnixMessage type) const

uint8_t *	data (SendMessageHeader::ControlMessage &msg) const

Protected Attributes
FileNumVector	m_fds

bool	m_unclaimed_fds = false
	Flag whether "live" FDs in m_fds have not yet been collected.

Detailed Description

Wrapper for the SCM_RIGHTS socket ancillary message to pass file descriptors to other processes.

UNIX domain sockets can be used to pass file descriptors between unrelated processes. This class supports both, assembling an ancillary message to pass on file descriptors to another process, and deserializing an ancillary message to access file descriptors received from another process.

For sending add the desired file descriptors to the object using addFD(). The object will not take ownership of the file descriptors and will never close them. The file descriptors need to stay valid until the ancillary message has been successfully sent out, though. The final ancillary message can be created using the serialize() method. The resulting SendMessageHeader::ControlMessage can be assigned to the control_msg member of a SendMessageHeader instance, for sending it via Socket::sendMessage() or one of its specializations.

For receiving setup a ReceiveMessageHeader for use with a UNIX domain socket, call setControlBufferSize() on it to allow reception of ancillary data. On successful reception check for a ControlMessage on OptLevel::SOCKET and of type UnixMessage::RIGHTS. Once this message arrives, pass it to the deserialize() function to parse the file descriptor numbers that have been received. At this point the file descriptors will be allocated in the receiving process and ownership of them needs to be managed. The takeFDs() function transfers the ownership of received file descriptors to the caller. This operation can only happen once. If for some reason the file descriptors are never claimed, then they are closed internally upon destruction of the object or before the object state is modified in other ways.

There are a number of pitfalls with this mechanism:

when sending a UnixRightsMessage it is best to send some actual payload in the SendMessageHeader used for this. On Linux when using a UnixDatagramSocket then this is not strictly necessary. For all other socket types at least on byte of payload data is necessary for successfully passing the ancillary message though.
when receiving a UnixRightsMessage then the received file descriptors will automatically be allocated in the current process. If an application fails to parse the message or take ownership of the file descriptors then they will leak. This can lead to a denial-of-service situation especially if the process at the other end is from a different security domain.
when the control message buffer is too small upon reception of a UnixRightsMessage then the control message can be truncated (check Messageflag::CTL_WAS_TRUNCATED). In this case parts of the received file descriptors will be closed again (or not allocated in the first place).
the order and payload/ancillary message combination used for sending the file descriptors can change on the receiving side. Design your application to accept ancillary messages on the receiving end for as long as you expect such a transmission. Don't wait for a specific payload message accompanied by the file descriptors.

Definition at line 106 of file unix_aux.hxx.

Member Typedef Documentation

◆ FileNumVector

using cosmos::UnixRightsMessage::FileNumVector = std::vector<FileNum>

A vector to keep a series of FileNum file descriptor numbers to pass between processes.

Definition at line 111 of file unix_aux.hxx.

Constructor & Destructor Documentation

◆ ~UnixRightsMessage()

cosmos::UnixRightsMessage::~UnixRightsMessage ( )

inline

Definition at line 120 of file unix_aux.hxx.

                             {
                closeUnclaimed();
        }

Member Function Documentation

◆ addFD()

void cosmos::UnixRightsMessage::addFD ( cosmos::FileNum fd )

inline

Definition at line 141 of file unix_aux.hxx.

                                     {
                m_fds.push_back(fd);
        }

◆ clearFDs()

void cosmos::UnixRightsMessage::clearFDs ( )

inline

Definition at line 145 of file unix_aux.hxx.

                        {
                closeUnclaimed();
                m_fds.clear();
        }

◆ closeUnclaimed()

void cosmos::UnixRightsMessage::closeUnclaimed ( )

protected

Definition at line 59 of file unix_aux.cxx.

                                       {
        if (m_unclaimed_fds) {
                for (auto fd: m_fds) {
                        cosmos::FileDescriptor{fd}.close();
                }
 
                m_fds.clear();
 
                m_unclaimed_fds = false;
        }
}

◆ deserialize()

void cosmos::UnixRightsMessage::deserialize ( const ReceiveMessageHeader::ControlMessage & msg )

Parse received file descriptors from the given ControlMessage.

If msg is not of the right type then an exception is thrown.

On success check numFDs() to learn of the amount of received file descriptors and use takeFDs() to transfer ownership of them to the caller.

Definition at line 20 of file unix_aux.cxx.

                                                                                 {
        this->checkMsg(msg, UnixMessage::RIGHTS);
 
        clearFDs();
 
        const uint8_t *data = reinterpret_cast<const uint8_t*>(msg.data());
 
        auto left = msg.dataLength();
        FileNum fd;
 
        while (left >= sizeof(fd)) {
                std::memcpy(&fd, data, sizeof(fd));
                data += sizeof(fd);
                left -= sizeof(fd);
                m_fds.push_back(fd);
        }
 
        if (!m_fds.empty()) {
                m_unclaimed_fds = true;
        }
}

◆ numFDs()

size_t cosmos::UnixRightsMessage::numFDs ( ) const

inline

Definition at line 160 of file unix_aux.hxx.

                              {
                return m_unclaimed_fds ? m_fds.size() : 0;
        }

◆ serialize()

SendMessageHeader::ControlMessage cosmos::UnixRightsMessage::serialize ( ) const

Serialize a ControlMessage for passing file descriptors.

This will serialize a ControlMessage containing all file descriptors previously added via addFD().

Definition at line 42 of file unix_aux.cxx.

                                                                   {
        if (m_fds.empty()) {
                cosmos_throw (UsageError("Attempt to serialize empty vector of FileNum"));
        }
 
        auto ret = this->createMsg(UnixMessage::RIGHTS, sizeof(FileNum) * m_fds.size());
 
        auto data = this->data(ret);
 
        for (auto fd: m_fds) {
                std::memcpy(data, &fd, sizeof(fd));
                data += sizeof(fd);
        }
 
        return ret;
}

◆ takeFDs()

void cosmos::UnixRightsMessage::takeFDs ( FileNumVector & fds )

inline

Definition at line 150 of file unix_aux.hxx.

                                         {
                if (!m_unclaimed_fds) {
                        fds.clear();
                        return;
                }
                fds = std::move(m_fds);
                m_fds = FileNumVector{};
                m_unclaimed_fds = false;
        }

Member Data Documentation

◆ m_fds

FileNumVector cosmos::UnixRightsMessage::m_fds

protected

Definition at line 170 of file unix_aux.hxx.

◆ m_unclaimed_fds

bool cosmos::UnixRightsMessage::m_unclaimed_fds = false

protected

Flag whether "live" FDs in m_fds have not yet been collected.

Definition at line 171 of file unix_aux.hxx.

◆ MAX_FDS

size_t cosmos::UnixRightsMessage::MAX_FDS = 253

staticconstexpr

Maximum number of file descriptors that can be transferred using a single UnixRightsMessage.

Definition at line 116 of file unix_aux.hxx.

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

include/net/unix_aux.hxx
src/net/unix_aux.cxx

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ FileNumVector

Constructor & Destructor Documentation

◆ ~UnixRightsMessage()

Member Function Documentation

◆ addFD()

◆ clearFDs()

◆ closeUnclaimed()

◆ deserialize()

◆ numFDs()

◆ serialize()

◆ takeFDs()

Member Data Documentation

◆ m_fds

◆ m_unclaimed_fds

◆ MAX_FDS