sideband.h

   1 /*
   2  * Copyright (C) 2012 Andre Noll <maan@tuebingen.mpg.de>
   3  *
   4  * Licensed under the GPL v2. For licencing details see COPYING.
   5  */
   6
   7 /** \file sideband.h exported symbols from sideband.c */
   8
   9 /**
  10  * The valid sideband designators.
  11  *
  12  * A sideband packet consists of a header and a body. The header is sent prior
  13  * to the data and contains the length of the buffer and the sideband
  14  * designator, an integer. This scheme allows receivers to never read more data
  15  * than what was specified in the header.
  16  *
  17  * The sideband designator indicates the type of the data. The authentication
  18  * handshake between the command handler (child of para_server) and the client
  19  * requires to exchange several small packages. Each such package is sent as a
  20  * sideband package with a dedicated designator.
  21  *
  22  * Other designators are employed for normal command output and for log
  23  * messages, where each loglevel corresponds to a sideband designator.
  24  *
  25  * Note that the values of this enum are part of the ABI, so never change
  26  * or remove entries. Appending is OK though.
  27  */
  28 #define SB_DESIGNATORS \
  29         /* Special value for receiving only: Accept any band. */ \
  30         DESIGNATOR(ANY), \
  31         /* This packet contains the authentication challenge. */ \
  32         DESIGNATOR(CHALLENGE), \
  33         /* I solved your challenge and here is the proof. */ \
  34         DESIGNATOR(CHALLENGE_RESPONSE), \
  35         /* Congratulations, you are authenticated. */ \
  36         DESIGNATOR(PROCEED), \
  37         /* This is the command I want you to execute. */ \
  38         DESIGNATOR(COMMAND), \
  39         /* Ready to receive a blob (addblob commands only). */ \
  40         DESIGNATOR(AWAITING_DATA), \
  41         /* Normal command output (default). */ \
  42         DESIGNATOR(OUTPUT), \
  43         /* LL_DEBUG. */ \
  44         DESIGNATOR(DEBUG_LOG), \
  45         /* LL_INFO. */ \
  46         DESIGNATOR(INFO_LOG), \
  47         /* LL_NOTICE. */ \
  48         DESIGNATOR(NOTICE_LOG), \
  49         /* LL_WARNING, */ \
  50         DESIGNATOR(WARNING_LOG), \
  51         /* LL_ERROR. */ \
  52         DESIGNATOR(ERROR_LOG), \
  53         /* LL_CRIT. */ \
  54         DESIGNATOR(CRIT_LOG), \
  55         /* LL_EMERG. */ \
  56         DESIGNATOR(EMERG_LOG), \
  57         /* Command terminated successfully. */ \
  58         DESIGNATOR(EXIT__SUCCESS), \
  59         /* Command failed. */ \
  60         DESIGNATOR(EXIT__FAILURE), \
  61         /* The next chunk of the blob (addblob commands only) */ \
  62         DESIGNATOR(BLOB_DATA), \
  63         /* An afs callback failed. */ \
  64         DESIGNATOR(AFS_CB_FAILURE), \
  65
  66 /** Just prefix with \p SBD_. */
  67 #define DESIGNATOR(x) SBD_ ## x
  68
  69 /** All valid sideband designators. */
  70 enum sb_designator {SB_DESIGNATORS NUM_SB_DESIGNATORS};
  71 #undef DESIGNATOR
  72 /** One stringified sideband designator. */
  73 #define DESIGNATOR(x) #x
  74 /** List of stringified sidedband designators. */
  75 #define SB_DESIGNATORS_ARRAY SB_DESIGNATORS
  76
  77 /**
  78  * The information contained in a sideband buffer.
  79  *
  80  * This structure is used for both sending and receiving data through a
  81  * sideband channel. A pointer to a sideband buffer is passed to the sending
  82  * side of a sideband while the receiving end yields a filled out structure
  83  * once all data has been received.
  84  */
  85 struct sb_buffer {
  86         /** Data and length. */
  87         struct iovec iov;
  88         /** The band designator. */
  89         uint8_t band;
  90 };
  91
  92 /**
  93  * The opaque sideband context structure.
  94  *
  95  * A pointer to a structure of this type is returned by the two \a sb_new_xxx
  96  * functions as an opaque handle. Other public functions of the sideband API
  97  * take such a handle as a parameter.
  98  */
  99 struct sb_context;
 100
 101 /**
 102  * The type of a sideband transformation.
 103  *
 104  * The sideband API allows to filter all data through an arbitrary
 105  * transformation, which is useful for crypto purposes. The transformation may
 106  * either transform the data in place, or return a pointer to a new buffer
 107  * which contains the transformed source buffer. The internal sideband
 108  * functions can tell the two types of transformations apart by checking
 109  * whether the destination buffer coincides with the source buffer.
 110  *
 111  * If the transformation allocates a new buffer, it _must_ allocate one extra
 112  * byte for \p NULL termination.
 113  */
 114 typedef void (*sb_transformation)(struct iovec *src, struct iovec *dst,
 115                 void *trafo_context);
 116
 117
 118 /** Initialize a sideband buffer. */
 119 #define SBB_INIT(_band, _buf, _numbytes) \
 120         { \
 121                 .band = _band, \
 122                 .iov = { \
 123                         .iov_base = _buf, \
 124                         .iov_len = _numbytes \
 125                 } \
 126         };
 127
 128 /* receiving */
 129 struct sb_context *sb_new_recv(size_t max_size, sb_transformation t,
 130                 void *trafo_context);
 131 void sb_get_recv_buffer(struct sb_context *c, struct iovec *iov);
 132 int sb_received(struct sb_context *c, size_t nbytes, struct sb_buffer *result);
 133
 134 /* sending */
 135 struct sb_context *sb_new_send(struct sb_buffer *sbb, bool dont_free,
 136                 sb_transformation t, void *trafo_context);
 137 int sb_get_send_buffers(struct sb_context *c, struct iovec iov[2]);
 138 bool sb_sent(struct sb_context *c, size_t nbytes);
 139
 140 void sb_free(struct sb_context *c);