server/admin.c: Remove spurious `ping' in usage message.

[tripe] / priv / priv.h

/* -*-c-*-
 *
 * Privilege separation definitions
 *
 * (c) 2008 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Trivial IP Encryption (TrIPE).
 *
 * TrIPE is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free
 * Software Foundation; either version 3 of the License, or (at your
 * option) any later version.
 *
 * TrIPE is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with TrIPE.  If not, see <https://www.gnu.org/licenses/>.
 */

#ifndef PRIV_H
#define PRIV_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include "config.h"

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>

#include <sys/socket.h>
#include <sys/un.h>

#include <mLib/dstr.h>
#include <mLib/fdpass.h>
#include <mLib/quis.h>
#include <mLib/report.h>
#include <mLib/trace.h>

#include "util.h"

#undef sun

/*----- Protocol ----------------------------------------------------------*/

/* --- Notes --- *
 *
 * The protocol is synchronous.  The socket is not marked as nonblocking;
 * instead we just trust the helper to respond in good time; this is
 * reasonable since it's not doing anything complicated.  The helper is
 * completely trusted.
 *
 * The protocol works like this.  Messages begin with a request code which is
 * a single @unsigned int@.  The server sends a request @PS_TUNRQ@ to the
 * helper, followed by a strin naming the tunnel driver of interest.  The
 * server responds with a sequence of @PS_TRACE@ and/or @PS_WARN@ messages,
 * followed by either a @PS_TUNFD@ carrying a file descriptor, or a
 * @PS_TUNERR@ followed by an integer @errno@ code.
 *
 * Simple data items are sent as native representations.  A string is sent as
 * a @size_t@ giving the string's length in bytes followed by that many
 * characters.  There is no padding for alignment.
 *
 * If all else fails, the helper process will just quit.
 */

enum {
  PS_TUNRQ,				/* Request (string) */
  PS_TUNFD,				/* Tunnel descriptor (nothing) */
  PS_TUNERR,				/* Error (@int errno@) */
#ifndef NTRACE
  PS_TRACE,				/* Trace (@unsigned mask@, string) */
#endif
  PS_WARN,				/* Warning (string) */
};

/*----- Tracing definitions -----------------------------------------------*/

#define T_PRIVSEP 512u

/*----- Global variables --------------------------------------------------*/

extern int pc_fd;			/* File descriptor for comms */

/*----- Functions provided ------------------------------------------------*/

#define COMM_TYPES(_)							\
  _(err, int)								\
  _(uint, unsigned int)							\
  _(sz, size_t)

/* --- @pc_put@ --- *
 *
 * Arguments:	@const void *p@ = pointer to buffer
 *		@size_t sz@ = size of the buffer
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Writes a buffer, handling short writes and other bogosity.
 */

extern int pc_put(const void */*p*/, size_t /*sz*/);

/* --- @pc_puterr@, @pc_putuint@, @pc_putsz@ --- *
 *
 * Arguments:	@int err@ = error number to write
 *		@uint u@ = unsigned integer to write
 *		@size_t sz@ = size to write
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Sends an error/integer/size.
 */

#define DECL(abbr, type) extern int pc_put##abbr(type /*x*/);
COMM_TYPES(DECL)
#undef DECL

/* --- @pc_putstring@ --- *
 *
 * Arguments:	@const char *s@ = pointer to string to write
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Sends a string.
 */

extern int pc_putstring(const char */*s*/);

/* --- @pc_get@ --- *
 *
 * Arguments:	@void *p@ = pointer to buffer
 *		@size_t sz@ = size of the buffer
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Receives a buffer, handling short reads and other bogosity.
 */

extern int pc_get(void */*p*/, size_t /*sz*/);

/* --- @pc_geterr@, @pc_getuint@, @pc_getsz@ --- *
 *
 * Arguments:	@int *err@ = where to put the error number
 *		@uint *u@ = where to put the unsigned integer
 *		@size_t *sz@ = where to put the size
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Receives an error/integer/size.
 */

#define DECL(abbr, type) extern int pc_get##abbr(type */*x*/);
COMM_TYPES(DECL)
#undef DECL

/* --- @pc_getstring@ --- *
 *
 * Arguments:	@dstr *d@ = where to put the string
 *
 * Returns:	Zero on success, @-1@ on error (and @errno@ set).
 *
 * Use:		Receives a string.
 */

extern int pc_getstring(dstr */*d*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif