VFER: src/vsl_api.h File Reference

#define VSL_AUTH_KEYLEN 32

VSL MAC key length.

Definition at line 30 of file vsl_api.h.

#define VSL_ENC_KEYLEN 16

VSL encryption key length.

Definition at line 24 of file vsl_api.h.

#define VSL_KEYLEN 32

VSL main key length.

Definition at line 21 of file vsl_api.h.

#define VSL_MACLEN 16

VSL MAC length.

Definition at line 27 of file vsl_api.h.

enum vsl_auth_t

VSL authentication types.

Enumerator:

VSL_AUTH_SSH
VSL_AUTH_DH

Definition at line 33 of file vsl_api.h.

enum vsl_errcode_t

VSL errorcodes.

Enumerator:

VSL_BADPROT	protocol error
VSL_MAXMSG	maximum message count reached
VSL_ERRNO	system call failed
VSL_SSHF	ssh process failed
VSL_TOOBIG	message too big
VSL_TEMP	temporary server error (ssh starting mode)
VSL_PERM	permanent server error (ssh starting mode)

Definition at line 39 of file vsl_api.h.

enum vsl_sock_mark_t

VSL socket select markers.

Enumerator:

VSL_READABLE	ready to read
VSL_WRITABLE	ready to write
VSL_EXCEPTION	exception occured
VSL_AUTHABLE	ready fror next authentication step

Definition at line 75 of file vsl_api.h.

int vsl_accept_ssh ( vsl_sock * socket )

Establishes a secure connection to the specified host using SSL Starting Mode. This function has to be called by the server. It reads the secret from stdin, listens on a free port, prints the port nr. to stdout, accepts a connection and daemonizes. See specification for details.

This call always blocks.

The function requires an initialized VSL socket.

Note that this function creates a new vfer socket when accepting the connection. Therefore, the caller has to make sure that vfer_close() is called both for the listening vfer_fd (that was passed to vsl_socket()) and the new vfer_fd (which is available with vsl_vferfd() after this function returns). The listening vfer fd can be closed as soon as vsl_accept_ssh() returns, the accepted vfer fd must not be closed before vsl_close() is called.

Parameters:

[out] socket VSL socket to use

Returns:

the vfer fd of the created connection on success (>= 0)
VSL_BADPROT in case of a protocol error
VSL_ERRNO if a system call failed (errno is set accordingly)
VFER_TIMEOUT a timeout occured

Definition at line 211 of file vsl_api.c.

void vsl_close ( vsl_sock * sock )

Destructs the given VSL socket.

This function does nothing at the moment, but it should be called as soon as the VSL connection is no longer used in case clean is neccessary in later versions.

This function will not close the underlying vfer_fd, it has to be closed manually or can be used for normal vfer communication.

Parameters:

[in] sock the socket

Definition at line 282 of file vsl_api.c.

int vsl_connect_ssh	(	vsl_sock *	socket,
		const char *	host,
		const char *	user,
		const char *	cmd,
		int	argc,
		const char const	argv,
		char *	errmsg
	)

Establishes a secure connection to the specified host using SSL Starting Mode. This function has to be called by the client. It connects to the remote host via ssh and starts the server. See specification for details.

The function requires an initialized VSL socket.

For non blocking sockets, this function might return VFER_INPROGRESS. That means that the next authentikation step would block. In this case the caller has to call the function repeatedly until it returns 0 or an error. vsl_select() can be used to check whether a socket is ready for the next step.

Note:: The SIGPIPE signal handler is set to ignore by this function. If neccessary, the caller has to save the original handler and restore it after authentication.

Parameters:

`[out]`	socket	VSL socket to use
`[in]`	host	hostname to connect to
`[in]`	user	username for SSH connection, `NULL` to use current user
`[in]`	cmd	program name of the server application
`[in]`	argc	number of arguments in argv that are passed to the server application
`[in]`	argv	arguments that is passed to the server application
`[out]`	errmsg	if the server returns an error message it is stored here. Must be achar array holding at least 512 bytes.

Returns:

0 on success
VFER_REFUSED vfer connection attempt refused
VFER_TIMEOUT vfer connection attempt timedout
VFER_INPROGRESS if the socket is nonblocking and the call would block.
VSL_BADPROT in case of a protocol error
VSL_SSHF if the ssh process failed
VSL_TEMP if the server signaled a temporary error
VSL_PERM if the server signaled a permanent error
VSL_ERRNO if a system call failed (errno is set accordingly)

Todo:: reactivate this when vfer debugging is done

Definition at line 87 of file vsl_api.c.

void vsl_debug	(	FILE *	fp,
		const char *	vfer
	)

Definition at line 930 of file vsl_api.c.

char* vsl_errortext ( int err )

Returns a text description of the error code err. If the errorcode is not specific to the security api, vfer_errortext() is called automatically instead.

Parameters:

[in] err error code

Returns:: a pointer to a text description of err

Definition at line 898 of file vsl_api.c.

int vsl_init ( void )

Initializes the VFER security layer. Has to be called before any other VSL functions.

Returns:

0 on success

Definition at line 32 of file vsl_api.c.

ssize_t vsl_max_frame_size ( vsl_sock * socket )

Get the maximum size that can be transmitted in a vsl_send() or vsl_recv() call.

Parameters:

[in] socket the VSL socket

Returns:

the maximum frame size in bytes > 0 on success

Definition at line 306 of file vsl_api.c.

ssize_t vsl_recv	(	vsl_sock *	sock,
		void *	buf,
		size_t	len
	)

Reads len bytes from buf on a connected socket.

Equivalent to vfer_recv(), but uses the vfer security layer to protect the message against modification and eavesdropping.

Due to the used MAC algorithm, the maximum number of messages that can be transferred with one socket is sizeof(uint64_t).

The maximum number of bytes that can be transmitted in one message can be determined with vsl_max_frame_size().

Note that if the incoming message is larger than len, the message cannot be verified and VSL_BADPROT will be returned.

If the vfer socket is of type SOCK_STREAM, nonblocking IO is not supported and VFER_INVAL returned.

Parameters:

`[in]`	sock	the socket to use
`[out]`	buf	a pointer to a buffer into which to receive
`[in]`	len	maximum length of data to receive into buf

Returns:

Returns the actual number of bytes sent on success (a positive number)
VFER_UNCONN sock is not connected
VFER_INVAL invalid buf or len.
VFER_WOULDBLOCK socket is non-blocking and requested operation would block
VSL_BADPROT in case of a protocol error, may also be caused by a forged message
VSL_TOOBIG message is larger than len.
VSL_ERRNO if a system call failed (errno is set accordingly)

Definition at line 469 of file vsl_api.c.

ssize_t vsl_recvfile	(	vsl_sock *	sock,
		int	fd,
		off_t	offset,
		size_t	len
	)

Reads len bytes from buf on a connected socket and writes them into the specified fd, starting at offset.

Equivalent to vfer_recvfile(), but uses the vfer security layer to protect the message against modification and eavesdropping.

Due to the used MAC algorithm, the maximum number of messages that can be transferred with one socket is sizeof(uint64_t). Afterwards, VSL_MAXMSG is returned.

Parameters:

`[in]`	sock	the VFS socket to use
`[out]`	fd	file descriptor for writing
`[in]`	offset	offset to start writing
`[in]`	len	number of bytes to read

Returns:

number of bytes read on success
errors like vsl_recv()

Definition at line 609 of file vsl_api.c.

int vsl_select	(	int	len,
		vsl_sock **	socks,
		struct timeval *	stimeout
	)

Returns the number of VSL sockets in an array that satisfy the marked conditions.

timeout is the maximum time to wait before the call returns. If timeout is NULL the call blocks indefinitely. A timeout value of zero can be used to effect a poll operation.

Warning:: Due to some implementation problems, this function might return immediately with VFER_INPROGRESS. That means that at the moment no socket is ready, and that it is not possible to wait for all specified sockets at the same time. In this case, the application has to poll the sockets by repetedly calling this function. However, this behaviour can only occur if len is bigger than 1 and at least one socket is marked with VSL_AUTHABLE.

Parameters:

`[in]`	len	length of socks array
`[in]`	socks	an array of sockets to check for marked conditions
`[in]`	stimeout	a timeout value to control waiting time

Returns:

a positive number if some sockets satisfy the marked conditions (not the number of sockets).
VFER_INVAL timeout value is invalid
VFER_INPROGRESS blocking select not possible
VSL_ERRNO if a system call failed (errno is set accordingly)

Definition at line 683 of file vsl_api.c.

int vsl_selectmark	(	vsl_sock *	socket,
		int	mark
	)

Marks socket with the conditions to be tested by the select call.

Called prior to using vsl_select(). Mark is a bitwise OR of

VSL_READABLE if the socket has received a message
VSL_WRITABLE if the socket can send a message
VSL_AUTHABLE if the socket is ready for the next authenticiation step by one of the VLS authentication functions.
VSL_EXCEPTION if an error occured for the socket

Parameters:

`[in]`	socket	VSL socket to mark
`[in]`	mark	a mark to associate with the socket

Returns:

0 on succes
VFER_INVAL invalid mark value

Definition at line 631 of file vsl_api.c.

int vsl_selectpoll	(	int	len,
		vsl_sock **	socks,
		struct timeval *	stimeout,
		int	usec
	)

Like vsl_select(), but automatically polls every usec microseconds when vsl_select() would return VFER_INPROGRESS.

Parameters:

`[in]`	len	length of socks array
`[in]`	socks	an array of sockets to check for marked conditions
`[in]`	stimeout	a timeout value to control waiting time
`[in]`	usec	polling intervall in microseconds

Returns:

number of sockets in array socks that satisfy the marked conditions
VFER_INVAL timeout value is invalid
VSL_ERRNO if a system call failed (errno is set accordingly)

Definition at line 979 of file vsl_api.c.

int vsl_selecttest ( vsl_sock * sock )

Returns the result of the vsl_select() call for socket.

The return value will be a bitwise OR of the constants described in vsl_selectmark(), depending on how sock was marked and the result of the vsl_select() call.

Parameters:

[in] sock the VSL socket

Returns:

bitwise OR of marks for socket sock on succes
VFER_BADSOCK bad socket

Definition at line 653 of file vsl_api.c.

ssize_t vsl_send	(	vsl_sock *	sock,
		const void *	buf,
		size_t	len
	)

Sends len bytes from buf over a socket.

Equivalent to vfer_send(), but uses the vfer security layer to protect the message against modification and eavesdropping.

Due to the used MAC algorithm, the maximum number of messages that can be transferred with one socket is sizeof(uint64_t). Afterwards, VSL_MAXMSG is returned.

The maximum number of bytes that can be transmitted in a single message can be determined with vsl_max_frame_size().

If the vfer socket is of type SOCK_STREAM, nonblocking IO is not supported and VFER_INVAL returned.

Parameters:

`[in]`	sock	VSL socket to use
`[in]`	buf	buffer to send
`[in]`	len	length of the data to send

Returns:

len on success
VSL_TOOBIG message is bigger than vsl_max_frame_size().
VFER_UNCONN sock is not connected
VFER_INVAL invalid buf or len
VFER_WOULDBLOCK socket is non-blocking and requested operation would block
VSL_MAXMSG maximum message count reached
VSL_ERRNO if a system call failed (errno is set accordingly)

Definition at line 342 of file vsl_api.c.

ssize_t vsl_sendfile	(	vsl_sock *	sock,
		int	fd,
		off_t	offset,
		size_t	len
	)

Sends len bytes from file fd starting at offset buf over socket sock.

Equivalent to vfer_sendfile(), but uses the vfer security layer to protect the message against modification and eavesdropping.

Due to the used MAC algorithm, the maximum number of messages that can be transferred with one socket is sizeof(uint64_t). So it may happen that large files cannot be transferred completely. In this case VSL_MAXMSG is returned after the maximum number of bytes has been transferred.

Parameters:

`[in]`	sock	the VFS socket to use
`[out]`	fd	file descriptor for reading
`[in]`	offset	offset to start reading
`[in]`	len	number of bytes to write

Returns:

Returns the actual number of bytes sent on success (a positive number)
errors like vsl_send()

Definition at line 431 of file vsl_api.c.

int vsl_socket	(	vsl_sock *	socket,
		const vfer_fd	fd
	)

Initializes a VSL socket using an existing and connected vfer fd. Before the socket can be used to transfer data, an authentication function has to be called to perform the handshake.

Parameters:

`[in]`	fd	the VFER fd.
`[out]`	socket	VSL socket

Returns:

0 on success
VFER_BADSOCK if fd is invalid

Definition at line 244 of file vsl_api.c.

void vsl_test_mode ( vsl_sock * sock )

Activates some behaviour that is only useful for testing VSL internals:

vsl_connect_ssh() returns after each step in non blocking mode

Parameters:

[in] sock socket to mark

Definition at line 961 of file vsl_api.c.

int vsl_uninit ( void )

Cleanup the ressources used by the security layer. Has to be called before the program ends. In case of forked children, every process has to call the function before exiting.

Returns:

0 on success

Definition at line 43 of file vsl_api.c.

vfer_fd vsl_vferfd ( vsl_sock * socket )

Get the underlying VFER fd of a VSL socket.

Parameters:

[in] socket

Returns:: the vfer fd

Definition at line 294 of file vsl_api.c.

FILE* debug

Activates debugging messages

Parameters:

`[in]`	fp	stream to send debugging messages to, `NULL` deactivates debugging.
`[in]`	vfer	If not `NULL`, configures vfer to send its debugging output (level given by the contents of vfer) to the same file.

Definition at line 929 of file vsl_api.c.

src/vsl_api.h File Reference

Data Structures

Defines

Enumerations

Functions

Variables

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation


Data Structures
struct	vsl_sock
	VSL socket structure. More...
Defines
#define	VSL_AUTH_KEYLEN 32
	VSL MAC key length.
#define	VSL_ENC_KEYLEN 16
	VSL encryption key length.
#define	VSL_KEYLEN 32
	VSL main key length.
#define	VSL_MACLEN 16
	VSL MAC length.
Enumerations
enum	vsl_auth_t { VSL_AUTH_SSH, VSL_AUTH_DH }
	VSL authentication types. More...
enum	vsl_errcode_t { VSL_BADPROT = -255, VSL_MAXMSG, VSL_ERRNO, VSL_SSHF, VSL_TOOBIG, VSL_TEMP = 20, VSL_PERM }
	VSL errorcodes. More...
enum	vsl_sock_mark_t { VSL_READABLE = 1, VSL_WRITABLE = 2, VSL_EXCEPTION = 4, VSL_AUTHABLE = 8 }
	VSL socket select markers. More...
Functions
int	vsl_accept_ssh (vsl_sock *sock)
void	vsl_close (vsl_sock *socket)
int	vsl_connect_ssh (vsl_sock sock, const char host, const char user, const char cmd, int argc, const char const argv, char *errmsg)
void	vsl_debug (FILE fp, const char vfer)
char *	vsl_errortext (int err)
int	vsl_init (void)
ssize_t	vsl_max_frame_size (vsl_sock *socket)
ssize_t	vsl_recv (vsl_sock socket, void buf, size_t len)
ssize_t	vsl_recvfile (vsl_sock *socket, int fd, off_t offset, size_t size)
int	vsl_select (int len, vsl_sock *socks, struct timeval timeout)
int	vsl_selectmark (vsl_sock *socket, int mark)
int	vsl_selectpoll (int len, vsl_sock *socks, struct timeval stimeout, int usec)
int	vsl_selecttest (vsl_sock *socket)
ssize_t	vsl_send (vsl_sock socket, const void buf, size_t len)
ssize_t	vsl_sendfile (vsl_sock *socket, int fd, off_t offset, size_t size)
int	vsl_socket (vsl_sock *socket, const vfer_fd vfd)
void	vsl_test_mode (vsl_sock *sock)
int	vsl_uninit (void)
vfer_fd	vsl_vferfd (vsl_sock *socket)
Variables
FILE *	debug