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