libmessageclient(3)    FreeBSD Library Functions Manual    libmessageclient(3)

NAME
     libmessageserver - Message-Oriented Client Library

SYNOPSIS
     #include <messageclient.h>
     -I/usr/local/include -L/usr/local/lib -lmessageclient -lcrypto -lssl

DESCRIPTION
     LibMessageClient supplies reentrant, blocking-IO code to communicate with
     LibMessageServer servers.

     LibMessageServer and LibMessageClient make it easy to write network
     clients and servers that exchange messages of arbitrary size, structure,
     and content.  MessageServer provides the framing mechanism.  You
     implement your application protocol on top of MessageServer.  See
     libmessageserver(3) for framing details.

   USAGE
     The library provides 12 functions.

     char mc_error[ 128 ];

     SSL_CTX *ctx;

     struct mc_ssl {
        SSL *ssl;
        int fd;
     };

     int mc_connect_to_tcp_server( char *, char * );
     int mc_connect_to_unix_server( char * );

     int mc_read_frame( int, unsigned char * );
     int mc_send_frame( int, unsigned char *, unsigned int );
     int mc_send_message( int, unsigned char *, unsigned int );

     int mc_init_tls( int );
     void mc_deinit_tls();

     struct mc_ssl *mc_connect_to_tcp_server_with_tls( char *, char * );
     void mc_close_tls_connection( struct mc_ssl * );

     int mc_read_frame_with_tls( struct mc_ssl *, unsigned char * );
     int mc_send_frame_with_tls( struct mc_ssl *, unsigned char *, unsigned int );
     int mc_send_message_with_tls( struct mc_ssl *, unsigned char *, unsigned int );

     Do not define any other global symbol beginning with the 3 characters
     'mc_' because the library reserves that namespace.

   MC_CONNECT_TO_TCP_SERVER()
     Use mc_connect_to_tcp_server() to establish a connection to a TCP server.

     int mc_connect_to_tcp_server( char *host, char *port );

     The host argument is a string representing the hostname or IP address of
     the host on which the server is running.

     The port argument is a string representing the port on which the server
     is listening.

     On success, the function returns a positive value that is the file
     descriptor of the connected socket.

     On error, the function returns -1 and writes an error message into
     mc_error.

   MC_CONNECT_TO_UNIX_SERVER()
     Use mc_connect_to_unix_server() to establish a connection to a local
     UNIX-domain server.

     int mc_connect_to_unix_server( char *path );

     The path argument is the fully qualified path to the UNIX socket on which
     the server is listening.

     On success, the function returns a positive value that is the file
     descriptor of the connected socket.

     On error, the function returns -1 and writes an error message into
     mc_error.

   MC_READ_FRAME()
     Use mc_read_frame() to read unencrypted frames from a server.  If you
     want to timeout reads, use setsockopt() to place a timeout on the
     underlying socket.

     int mc_read_frame( int fd, unsigned char *buffer );

     The fd argument is the file descriptor of the connection.

     The buffer argument is a character array of 65535 bytes.

     On success, the function reads an incoming frame into buffer and returns
     the length of the frame.

     On EOF, the function returns -2.

     On error, the function returns -1 and writes an error message into
     mc_error.

     If the returned length is in the range of 1 to 65535, the frame contains
     a complete message.

     If the returned length is 0, the empty frame indicates that a fragmented
     message follows.  The succeeding frames carry message content in resource
     order.  A final empty frame of length 0 terminates the fragmented
     message.

   MC_SEND_MESSAGE()
     Use mc_send_message() to send unencrypted messages to a server.

     int mc_send_message( int fd, unsigned char *buffer, unsigned int len );

     The fd argument is the file descriptor of the connection.

     The buffer argument is a character array containing message content.

     The len argument is the length of the message in buffer.

     On success, the function sends the message to the server and returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

     Messages that fit within the maximum frame size are delivered as single
     frames.  Messages greater than the maximum frame size are delivered as
     fragments of the maximum frame size or less.

   MC_SEND_FRAME()
     Use send_frame_with_tls() to send one unencrypted frame to a server.  int
     mc_send_frame( int fd, unsigned char *buffer, unsigned int len );

     The fd argument is the file descriptor of the connection.

     The buffer argument is a character array containing message data.

     The len argument is the length of the data in buffer.  The length must be
     <= 65535.

     On success, the function sends the frame to the server and returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

     You can send a 0 length frame. This enables you to manually fragment
     messages that you do not know the size of in advance.  The individual
     message fragments must have lengths in the range of 1 to 65535.  The
     fragmented message must be preceded and terminated by 0 length frames.

   MC_INIT_TLS()
     Use mc_init_tls() to initialize OpenSSL before using any of the TLS
     functions.

     int mc_init_tls();

     On success, the function returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

   MC_DEINIT_TLS()
     Use mc_deinit_tls() to free the OpenSSL context if you are finished using
     the TLS functions.

     void mc_deinit_tls();

   MC_CONNECT_TO_TCP_SERVER_WITH_TLS()
     Use mc_connect_to_tcp_server_with_tls() to establish an encrypted
     connection to a TCP server.

     struct cm_ssl *mc_connect_to_tcp_server_with_tls( char *host, char *port, int ocsp );

     The host argument is a string representing the hostname or IP address of
     the host on which the server is running.

     The port argument is a string representing the port on which the server
     is listening.

     The ocsp argument indicates whether or not to request the certificate
     status with the TLS handshake.  Set ocsp to 1 to request the certificate
     status.  Set ocsp to 0 otherwise.  If the certificate status is
     requested, and the server does not perform OCSP stapling, or if the
     status is not valid, the handshake fails.

     On success, the function returns a pointer to a struct ms_ssl.

     On error, the function returns NULL and writes an error message into
     mc_error.

   MC_CLOSE_TLS_CONNECTION()
     Use mc_close_tls_connection() to close an encrypted connection.

     void mc_close_tls_connection( struct mc_ssl * );

     The function shuts down the TLS connection, closes the underlying
     descriptor, and frees the struct mc_ssl pointed to by the argument.

   MC_READ_FRAME_WITH_TLS()
     Use mc_read_frame_with_tls() to read encrypted frames from a server.  If
     you want to timeout reads, use setsockopt() to place a timeout on the
     underlying socket.

     int mc_read_message_with_tls( struct mc_ssl *conn, unsigned char *buffer );

     The conn argument is the pointer returned by
     mc_connect_to_tcp_server_with_tls().

     The buffer argument is a character array of 65535 bytes.

     On success, the function reads an incoming frame into buffer and returns
     the length of the frame.

     On EOF, the function returns -2.

     On error, the function returns -1 and writes an error message into
     mc_error.

     If the returned length is in the range of 1 to 65535, the frame contains
     a complete message.

     If the returned length is 0, the empty frame indicates that a fragmented
     message follows.  The succeeding frames carry message content in resource
     order.  A final empty frame of length 0 terminates the fragmented
     message.

   MC_SEND_MESSAGE_WITH_TLS()
     Use mc_send_message_with_tls() to send encrypted messages to a server.

     int mc_send_message_with_tls( struct mc_ssl *conn, unsigned char *buffer, unsigned int len );

     The conn argument is the pointer returned by
     mc_connect_to_tcp_server_with_tls();

     The buffer argument is a character array containing message data.

     The len argument is the length of the message in buffer.

     On success, the function sends the message to the server and returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

     Messages that fit within the maximum frame size are delivered as single
     frames.  Messages greater than the maximum frame size are delivered as
     fragments of the maximum frame size or less.

   MC_SEND_FRAME_WITH_TLS()
     Use send_frame_with_tls() to send one encrypted frame to a server.  int
     mc_send_frame_with_tls( struct mc_ssl *conn, unsigned char *buffer,
     unsigned int len );

     The conn argument is the pointer returned by
     mc_connect_to_tcp_server_with_tls();

     The buffer argument is a character array containing message data.

     The len argument is the length of the data in buffer.  The length must be
     <= 65535.

     On success, the function sends the frame to the server and returns 0.

     On error, the function returns -1 and writes an error message into
     mc_error.

     You can send a 0 length frame. This enables you to manually fragment
     messages that you do not know the size of in advance.  The individual
     message fragments must have lengths in the range of 1 to 65535.  The
     fragmented message must be preceded and terminated by 0 length frames.

AUTHORS
     James Bailie <jimmy@mammothcheese.ca>
     http://www.mammothcheese.ca

                                Mon Dec 3, 2018