2 Chapter 26. Amanda Security API
3 Prev Part V. Technical Background Next
5 -------------------------------------------------------------------------------
7 Chapter 26. Amanda Security API
18 XML-conversion;Updates
31 protocol_packet_transmission_functions
87 Refer to http://www.amanda.org/docs/security-api.html for the current version
92 This is a document of the API for defining and utilizing multiple security and
93 transport mechanisms for the Amanda network protocol.
94 The goal of this API is to allow several different forms of communication and
95 authentication to exist between the Amanda server and its clients.
99 There exist many potential ways that a user might wish to grant access to the
100 Amanda daemon. The two currently supported are BSD (reserved port) and Kerberos
101 IV security. The current implementation of these two methods is not very
102 general, and adding additional methods requires a large amount of code to be
104 Additionally, the current methods require the protocol and dump transport to be
105 transmitted across the network using a pre-defined method. The Amanda protocol
106 currently must be sent using udp datagrams to a well-known port, and the dumps
107 are transported using tcp connections between ports negotiated via the
112 The security API was designed to be a layer in between the core logic of Amanda
113 and the transport and authentication of the protocol and dumps.
114 The component server and client programs now deal with abstract concepts
115 instead of concrete udp and tcp handles.
116 The prefix "security_" is reserved for use as the namespace of this API.
118 protocol packet transmission functions
120 These functions exist for transmitting pkt_t's between the client and server.
121 These functions operate on security_handle_t objects. These objects are
126 const security_driver_t *security_getdriver(const char *drivername);
127 Given a security type ("KRB4", "BSD", "SSH", etc), returns a pointer to that
128 type's security_driver_t (section 4.1), or NULL if no driver exists.
132 void security_connect(const security_driver_t *h, const char *hostname, char *
133 (*conf_fn)(char *arg, void *arg), void (*fn)(void *arg, security_handle_t *h,
134 security_status_t s), void *arg);
135 Given a security driver, and a hostname, calls back with a security_handle_t
136 (section 4.2) that can be used to communicate with that host. The status arg to
137 the callback is reflects the success of the request. Error messages can be had
138 via security_geterror().
139 This is expected to be the Amanda server's interface for setting up connections
141 conf_fn is used to determine configuration information. If NULL, no
142 configuration information is available.
146 void security_accept(const security_driver_t *h, int in, int out, void
147 (*callback)(security_handle_t *, pkt_t *));
148 Given a security driver, an input file descriptor, and an output file
149 descriptor, and a callback, when new connections are detected on the given file
150 descriptors, the function is called with a newly created security handle and
151 the initial packet received.
152 This is expected to be the Amanda daemon's interface for setting up incoming
153 connections from the Amanda server. The file descriptors are typically 0 and 1
155 This function uses the event interface, and only works properly when event_loop
156 () is called later in the program.
160 void security_close(security_handle_t *h);
161 Closes a connection created by a security_connect() or security_accept().
165 int security_sendpkt(security_handle_t *h, const pkt_t *pkt);
166 Transmits a pkt_t over a security handle. Returns 0 on success, or negative on
167 error. A descriptive error message can be obtained via security_geterror().
171 int security_recvpkt(security_handle_t *h, void (*callback)(void *arg, pkt_t
172 *pkt, security_status_t), void *arg, int timeout);
173 Requests that when incoming packets arrive for this handle, the given function
174 is called with the given argument, the received packet, and the status of the
176 If a packet does not arrive within the number of seconds specified in the
177 'timeout' argument, RECV_TIMEOUT is passed in the status argument of the
179 On receive error, the callback's status argument will be set to RECV_ERROR. An
180 error message can be retrieved via security_geterror().
181 On successful reception, RECV_OK will be passed in the status argument, and the
182 pkt argument will point to a valid packet.
183 This function uses the event interface. Callbacks will only be generated when
184 event_loop() is called.
186 security_recvpkt_cancel
188 int security_recvpkt_cancel(security_handle_t *h);
189 Cancels a previous recvpkt request for this handle.
193 const char *security_geterror(security_handle_t *h);
194 Returns a descriptive error message for the last error condition on this
199 void security_seterror(security_handle_t *h, const char *msg, ...);
200 Sets the string that security_geterror() returns.
204 void security_handleinit(security_handle_t *, const security_driver_t *);
205 Initializes a security_handle_t. This is meant to be called only by security
206 drivers to initialize the common part of a newly allocated security_handle_t.
210 These functions exist for transmitting random data over a stream-like
212 These functions operate on security_stream_t objects, which are described
215 security_stream_server
217 security_stream_t *security_stream_server(security_handle_t *h);
218 Creates the server end of a security stream, and will receive a connection from
219 the host on the other end of the security handle passed.
220 Returns a security_stream_t on success, and NULL on error. Error messages can
221 be obtained by calling security_geterror() on the security handle associated
224 security_stream_accept
226 int security_stream_accept(security_stream_t *);
227 Given a security stream created by security_stream_server, blocks until a
228 connection is made from the remote end.
229 Returns 0 on success, and -1 on error. Error messages can be obtained by
230 calling security_stream_geterror().
232 security_stream_client
234 security_stream_t *security_stream_client(security_handle_t *h, int id);
235 Creates the client end of a security stream, and connects it to the machine on
236 the other end of the security handle. The 'id' argument identifies which stream
237 on the other end to connect to.
238 Returns a security_stream_t on success, and NULL on error. Error messages can
239 be obtained by calling security_geterror() on the security handle associated
242 security_stream_close
244 void security_stream_close(security_stream_t *s);
245 Closes a security stream and frees up resources associated with it.
249 int security_stream_auth(security_stream_t *s);
250 Authenticate a connected security stream.
251 Returns 0 on success, and -1 on error. Error messages can be obtained by
252 calling security_stream_geterror().
256 int security_stream_id(security_stream_t *s);
257 Returns an identifier which can be used to connect to this security stream with
258 security_stream_client().
259 Typical usage would be for one end of a connection to create a stream with
260 security_stream_server(), and then transmit the id for that stream to the other
261 side. The other side will then connect to that id with security_stream_client
264 security_stream_write
266 int security_stream_write(security_stream_t *s, const void *buf, size_t
268 Writes a chunk of data to the security stream. Returns 0 on success, or
269 negative on error. Error messages can be obtained by calling
270 security_stream_geterror().
274 void security_stream_read(security_stream_t *s, void (*callback)(void *arg,
275 void *buf, int bufsize), void *arg);
276 Requests that when data is ready to be read on this stream, the given function
277 is called with the given arg, a buffer full of data, and the size of that
279 On error, the bufsize will be negative. An error message can be retrieved by
280 calling security_stream_geterror().
281 This function uses the event interface. Callbacks will only be generated while
284 security_stream_read_cancel
286 void security_stream_read_cancel(security_stream_t *s);
287 Cancels a previous read request.
289 security_stream_geterror
291 const char *security_stream_geterror(security_stream_t *h);
292 Returns a descriptive error message for the last error condition on this
295 security_stream_seterror
297 void security_stream_seterror(security_stream_t *h, const char *msg, ...);
298 Sets the string that security_stream_geterror() returns.
302 All visible data types are meant to be opaque to the caller. At no time should
303 a caller have to access a member of any data type directly. The API should
304 always be used instead.
308 This is a static object containing function vectors that implement the API for
309 a particular security type.
313 This is an object that describes a protocol connection to a remote server.
314 There is one security_handle_t per request, and there can be many to the same
319 This is an object that describes a data connection to a remote host. It is
320 always associated and derived from a security_handle_t. Arbitrary data can be
321 passed over a security stream.
325 This is an enumerated type that is passed to the callback of security_recvpkt
326 and security_connect. The possible values it can have are:
327 S_OK - the pkt_t was received fine S_TIMEOUT - no pkt_t was received within the
328 time specified in the timeout argument to security_recvpkt(). S_ERROR - an
329 error occurred during reception. Call security_geterror() for more information.
333 Each security type is defined by a struct of function vectors. These methods
334 implement the details of this security type.
335 This section will document each element of security_driver_t.
340 This is the name of the driver. This is used by security_getdriver() to
341 associate a name with a driver type.
345 void (*connect)(const char *hostname, void (*fn)(void *, security_handle_t *,
346 security_status_t), void *);
347 This is the implementation of security_connect(). It actually sets up the
348 connection, and then returns a structure describing the connection. The first
349 element of this structure MUST be a security_handle_t, because it will be cast
350 to that after it is passed up to the caller.
351 The first argument is the host to connect to. The second argument is a function
352 to call when a connection is made. The third argument is passed to the
354 The callback takes three arguments. The first is the caller supplied void
355 pointer. The second is a newly allocated security handle. The third is a
356 security_status_t flag indicating the success or failure of the operation.
360 void (*accept)(int in, int out, void (*callback)(security_handle_t *handle,
362 This is the implementation of security_accept(). It is passed the input and
363 output file descriptors and a callback. The callback takes a security handle
364 argument and also an initial packet received for that handle.
368 void (*close)(void *handle);
369 The implementation of security_close().
373 int (*sendpkt)(void *handle, pkt_t *pkt);
374 The implementation of security_sendpkt(). Security information is usually added
375 by the driver before transmission.
379 void (*recvpkt)(void *handle, void (*callback)(void *arg, pkt_t *pkt,
380 security_status_t), void *arg);
381 The implementation of security_recvpkt(). It will typically be layered onto the
382 event interface somehow. It can assume that a caller will eventually call
387 void (*recvpkt_cancel)(void *handle);
388 The implementation of security_recvpkt_cancel(). Drivers should allow this to
389 be run even if no recvpkt was scheduled, or if one was previously cancelled.
393 void *(*stream_server)(void *handle);
394 Implementation of security_stream_server(). This function returns a object
395 describing the stream. The first member of this object MUST be a
396 security_stream_t, because it will be cast to that.
400 int (*stream_accept)(void *stream);
401 After calling stream_server, stream_accept must be called on the stream before
402 it is fully connected.
406 void *(*stream_client)(void *handle, int id);
407 Implementation of security_stream_client(). The id argument is something
408 returned by security_stream_id(). Again, the handle is referenced counted.
409 This function returns a object describing the stream. The first member of this
410 object MUST be a security_stream_t, because it will be cast to that.
414 void (*stream_close)(void *stream);
415 Close and free up resources for an open stream.
419 int (*stream_auth)(void *stream);
420 Authenticate a connected stream.
424 int (*stream_id)(void *stream);
425 Return a unique id for this stream. This is to be used by stream_client() to
426 connect to this stream.
430 int (*stream_write)(void *stream, const void *buf, size_t bufsize);
431 Implementation of security_stream_write.
435 void (*stream_read)(void *stream, void (*callback)(void *arg, void *buf, int
436 bufsize), void *arg);
437 Implementation of security_stream_read.
441 void (*stream_read_cancel)(void *stream);
442 Implementation of security_stream_read_cancel.
443 -------------------------------------------------------------------------------
446 Chapter 25. Amanda Event API Home Chapter 27. Virtual Tape API