git.gag.com Git - debian/amanda/blob - docs/security-api.txt

   1
   2       Chapter 26. Amanda Security API
   3 Prev  Part V. Technical Background  Next
   4
   5 -------------------------------------------------------------------------------
   6
   7 Chapter 26. Amanda Security API
   8
   9
  10 Mike Grupenhoff
  11
  12 Original text
  13 AMANDA Core Team
  14 <kashmir@munge.com>
  15
  16 Stefan G. Weichinger
  17
  18 XML-conversion;Updates
  19 AMANDA Core Team
  20 <sgw@amanda.org>
  21 Table of Contents
  22
  23
  24   Introduction
  25
  26   The_Problem
  27
  28   The_API
  29
  30
  31         protocol_packet_transmission_functions
  32
  33         stream_functions
  34
  35
  36   Data_Types
  37
  38
  39         security_driver_t
  40
  41         security_handle_t
  42
  43         security_stream_t
  44
  45         security_status_t
  46
  47
  48   SECURITY_DRIVERS
  49
  50
  51         name
  52
  53         connect
  54
  55         accept
  56
  57         close
  58
  59         sendpkt
  60
  61         recvpkt
  62
  63         recvpkt_cancel
  64
  65         stream_server
  66
  67         stream_accept
  68
  69         stream_client
  70
  71         stream_close
  72
  73         stream_auth
  74
  75         stream_id
  76
  77         stream_write
  78
  79         stream_read
  80
  81         stream_read_cancel
  82
  83
  84
  85  Introduction
  86
  87 This is a document of the API for defining and utilizing multiple security and
  88 transport mechanisms for the Amanda network protocol.
  89 The goal of this API is to allow several different forms of communication and
  90 authentication to exist between the Amanda server and its clients.
  91
  92  The Problem
  93
  94 There exist many potential ways that a user might wish to grant access to the
  95 Amanda daemon. The two currently supported are BSD (reserved port) and Kerberos
  96 IV security. The current implementation of these two methods is not very
  97 general, and adding additional methods requires a large amount of code to be
  98 modified.
  99 Additionally, the current methods require the protocol and dump transport to be
 100 transmitted across the network using a pre-defined method. The Amanda protocol
 101 currently must be sent using udp datagrams to a well-known port, and the dumps
 102 are transported using tcp connections between ports negotiated via the
 103 protocol.
 104
 105  The API
 106
 107 The security API was designed to be a layer in between the core logic of Amanda
 108 and the transport and authentication of the protocol and dumps.
 109 The component server and client programs now deal with abstract concepts
 110 instead of concrete udp and tcp handles.
 111 The prefix "security_" is reserved for use as the namespace of this API.
 112
 113  protocol packet transmission functions
 114
 115 These functions exist for transmitting pkt_t's between the client and server.
 116 These functions operate on security_handle_t objects. These objects are
 117 described later.
 118
 119  security_getdriver
 120
 121 const security_driver_t *security_getdriver(const char *drivername);
 122 Given a security type ("KRB4", "BSD", "SSH", etc), returns a pointer to that
 123 type's security_driver_t (section 4.1), or NULL if no driver exists.
 124
 125  security_connect
 126
 127 void security_connect(const security_driver_t *h, const char *hostname, char *
 128 (*conf_fn)(char *arg, void *arg), void (*fn)(void *arg, security_handle_t *h,
 129 security_status_t s), void *arg);
 130 Given a security driver, and a hostname, calls back with a security_handle_t
 131 (section 4.2) that can be used to communicate with that host. The status arg to
 132 the callback is reflects the success of the request. Error messages can be had
 133 via security_geterror().
 134 This is expected to be the Amanda server's interface for setting up connections
 135 to clients.
 136 conf_fn is used to determine configuration information. If NULL, no
 137 configuration information is available.
 138
 139  security_accept
 140
 141 void security_accept(const security_driver_t *h, int in, int out, void
 142 (*callback)(security_handle_t *, pkt_t *));
 143 Given a security driver, an input file descriptor, and an output file
 144 descriptor, and a callback, when new connections are detected on the given file
 145 descriptors, the function is called with a newly created security handle and
 146 the initial packet received.
 147 This is expected to be the Amanda daemon's interface for setting up incoming
 148 connections from the Amanda server. The file descriptors are typically 0 and 1
 149 (stdin/stdout).
 150 This function uses the event interface, and only works properly when event_loop
 151 () is called later in the program.
 152
 153  security_close
 154
 155 void security_close(security_handle_t *h);
 156 Closes a connection created by a security_connect() or security_accept().
 157
 158  security_sendpkt
 159
 160 int security_sendpkt(security_handle_t *h, const pkt_t *pkt);
 161 Transmits a pkt_t over a security handle. Returns 0 on success, or negative on
 162 error. A descriptive error message can be obtained via security_geterror().
 163
 164  security_recvpkt
 165
 166 int security_recvpkt(security_handle_t *h, void (*callback)(void *arg, pkt_t
 167 *pkt, security_status_t), void *arg, int timeout);
 168 Requests that when incoming packets arrive for this handle, the given function
 169 is called with the given argument, the received packet, and the status of the
 170 reception.
 171 If a packet does not arrive within the number of seconds specified in the
 172 'timeout' argument, RECV_TIMEOUT is passed in the status argument of the
 173 timeout.
 174 On receive error, the callback's status argument will be set to RECV_ERROR. An
 175 error message can be retrieved via security_geterror().
 176 On successful reception, RECV_OK will be passed in the status argument, and the
 177 pkt argument will point to a valid packet.
 178 This function uses the event interface. Callbacks will only be generated when
 179 event_loop() is called.
 180
 181  security_recvpkt_cancel
 182
 183 int security_recvpkt_cancel(security_handle_t *h);
 184 Cancels a previous recvpkt request for this handle.
 185
 186  security_geterror
 187
 188 const char *security_geterror(security_handle_t *h);
 189 Returns a descriptive error message for the last error condition on this
 190 handle.
 191
 192  security_seterror
 193
 194 void security_seterror(security_handle_t *h, const char *msg, ...);
 195 Sets the string that security_geterror() returns.
 196
 197  security_handleinit
 198
 199 void security_handleinit(security_handle_t *, const security_driver_t *);
 200 Initializes a security_handle_t. This is meant to be called only by security
 201 drivers to initialize the common part of a newly allocated security_handle_t.
 202
 203  stream functions
 204
 205 These functions exist for transmitting random data over a stream-like
 206 connection.
 207 These functions operate on security_stream_t objects, which are described
 208 later.
 209
 210  security_stream_server
 211
 212 security_stream_t *security_stream_server(security_handle_t *h);
 213 Creates the server end of a security stream, and will receive a connection from
 214 the host on the other end of the security handle passed.
 215 Returns a security_stream_t on success, and NULL on error. Error messages can
 216 be obtained by calling security_geterror() on the security handle associated
 217 with this stream.
 218
 219  security_stream_accept
 220
 221 int security_stream_accept(security_stream_t *);
 222 Given a security stream created by security_stream_server, blocks until a
 223 connection is made from the remote end.
 224 Returns 0 on success, and -1 on error. Error messages can be obtained by
 225 calling security_stream_geterror().
 226
 227  security_stream_client
 228
 229 security_stream_t *security_stream_client(security_handle_t *h, int id);
 230 Creates the client end of a security stream, and connects it to the machine on
 231 the other end of the security handle. The 'id' argument identifies which stream
 232 on the other end to connect to.
 233 Returns a security_stream_t on success, and NULL on error. Error messages can
 234 be obtained by calling security_geterror() on the security handle associated
 235 with this stream.
 236
 237  security_stream_close
 238
 239 void security_stream_close(security_stream_t *s);
 240 Closes a security stream and frees up resources associated with it.
 241
 242  security_stream_auth
 243
 244 int security_stream_auth(security_stream_t *s);
 245 Authenticate a connected security stream.
 246 Returns 0 on success, and -1 on error. Error messages can be obtained by
 247 calling security_stream_geterror().
 248
 249  security_stream_id
 250
 251 int security_stream_id(security_stream_t *s);
 252 Returns an identifier which can be used to connect to this security stream with
 253 security_stream_client().
 254 Typical usage would be for one end of a connection to create a stream with
 255 security_stream_server(), and then transmit the id for that stream to the other
 256 side. The other side will then connect to that id with security_stream_client
 257 ().
 258
 259  security_stream_write
 260
 261 int security_stream_write(security_stream_t *s, const void *buf, size_t
 262 bufsize);
 263 Writes a chunk of data to the security stream. Returns 0 on success, or
 264 negative on error. Error messages can be obtained by calling
 265 security_stream_geterror().
 266
 267  security_stream_read
 268
 269 void security_stream_read(security_stream_t *s, void (*callback)(void *arg,
 270 void *buf, int bufsize), void *arg);
 271 Requests that when data is ready to be read on this stream, the given function
 272 is called with the given arg, a buffer full of data, and the size of that
 273 buffer.
 274 On error, the bufsize will be negative. An error message can be retrieved by
 275 calling security_stream_geterror().
 276 This function uses the event interface. Callbacks will only be generated while
 277 in event_loop().
 278
 279  security_stream_read_cancel
 280
 281 void security_stream_read_cancel(security_stream_t *s);
 282 Cancels a previous read request.
 283
 284  security_stream_geterror
 285
 286 const char *security_stream_geterror(security_stream_t *h);
 287 Returns a descriptive error message for the last error condition on this
 288 stream.
 289
 290  security_stream_seterror
 291
 292 void security_stream_seterror(security_stream_t *h, const char *msg, ...);
 293 Sets the string that security_stream_geterror() returns.
 294
 295  Data Types
 296
 297 All visible data types are meant to be opaque to the caller. At no time should
 298 a caller have to access a member of any data type directly. The API should
 299 always be used instead.
 300
 301  security_driver_t
 302
 303 This is a static object containing function vectors that implement the API for
 304 a particular security type.
 305
 306  security_handle_t
 307
 308 This is an object that describes a protocol connection to a remote server.
 309 There is one security_handle_t per request, and there can be many to the same
 310 remote host.
 311
 312  security_stream_t
 313
 314 This is an object that describes a data connection to a remote host. It is
 315 always associated and derived from a security_handle_t. Arbitrary data can be
 316 passed over a security stream.
 317
 318  security_status_t
 319
 320 This is an enumerated type that is passed to the callback of security_recvpkt
 321 and security_connect. The possible values it can have are:
 322 S_OK - the pkt_t was received fine S_TIMEOUT - no pkt_t was received within the
 323 time specified in the timeout argument to security_recvpkt(). S_ERROR - an
 324 error occurred during reception. Call security_geterror() for more information.
 325
 326  SECURITY DRIVERS
 327
 328 Each security type is defined by a struct of function vectors. These methods
 329 implement the details of this security type.
 330 This section will document each element of security_driver_t.
 331
 332  name
 333
 334 const char *name;
 335 This is the name of the driver. This is used by security_getdriver() to
 336 associate a name with a driver type.
 337
 338  connect
 339
 340 void (*connect)(const char *hostname, void (*fn)(void *, security_handle_t *,
 341 security_status_t), void *);
 342 This is the implementation of security_connect(). It actually sets up the
 343 connection, and then returns a structure describing the connection. The first
 344 element of this structure MUST be a security_handle_t, because it will be cast
 345 to that after it is passed up to the caller.
 346 The first argument is the host to connect to. The second argument is a function
 347 to call when a connection is made. The third argument is passed to the
 348 callback.
 349 The callback takes three arguments. The first is the caller supplied void
 350 pointer. The second is a newly allocated security handle. The third is a
 351 security_status_t flag indicating the success or failure of the operation.
 352
 353  accept
 354
 355 void (*accept)(int in, int out, void (*callback)(security_handle_t *handle,
 356 pkt_t *pkt));
 357 This is the implementation of security_accept(). It is passed the input and
 358 output file descriptors and a callback. The callback takes a security handle
 359 argument and also an initial packet received for that handle.
 360
 361  close
 362
 363 void (*close)(void *handle);
 364 The implementation of security_close().
 365
 366  sendpkt
 367
 368 int (*sendpkt)(void *handle, pkt_t *pkt);
 369 The implementation of security_sendpkt(). Security information is usually added
 370 by the driver before transmission.
 371
 372  recvpkt
 373
 374 void (*recvpkt)(void *handle, void (*callback)(void *arg, pkt_t *pkt,
 375 security_status_t), void *arg);
 376 The implementation of security_recvpkt(). It will typically be layered onto the
 377 event interface somehow. It can assume that a caller will eventually call
 378 event_loop().
 379
 380  recvpkt_cancel
 381
 382 void (*recvpkt_cancel)(void *handle);
 383 The implementation of security_recvpkt_cancel(). Drivers should allow this to
 384 be run even if no recvpkt was scheduled, or if one was previously cancelled.
 385
 386  stream_server
 387
 388 void *(*stream_server)(void *handle);
 389 Implementation of security_stream_server(). This function returns a object
 390 describing the stream. The first member of this object MUST be a
 391 security_stream_t, because it will be cast to that.
 392
 393  stream_accept
 394
 395 int (*stream_accept)(void *stream);
 396 After calling stream_server, stream_accept must be called on the stream before
 397 it is fully connected.
 398
 399  stream_client
 400
 401 void *(*stream_client)(void *handle, int id);
 402 Implementation of security_stream_client(). The id argument is something
 403 returned by security_stream_id(). Again, the handle is referenced counted.
 404 This function returns a object describing the stream. The first member of this
 405 object MUST be a security_stream_t, because it will be cast to that.
 406
 407  stream_close
 408
 409 void (*stream_close)(void *stream);
 410 Close and free up resources for an open stream.
 411
 412  stream_auth
 413
 414 int (*stream_auth)(void *stream);
 415 Authenticate a connected stream.
 416
 417  stream_id
 418
 419 int (*stream_id)(void *stream);
 420 Return a unique id for this stream. This is to be used by stream_client() to
 421 connect to this stream.
 422
 423  stream_write
 424
 425 int (*stream_write)(void *stream, const void *buf, size_t bufsize);
 426 Implementation of security_stream_write.
 427
 428  stream_read
 429
 430 void (*stream_read)(void *stream, void (*callback)(void *arg, void *buf, int
 431 bufsize), void *arg);
 432 Implementation of security_stream_read.
 433
 434  stream_read_cancel
 435
 436 void (*stream_read_cancel)(void *stream);
 437 Implementation of security_stream_read_cancel.
 438
 439 Note
 440
 441 Refer to http://www.amanda.org/docs/security-api.html for the current version
 442 of this document.
 443 -------------------------------------------------------------------------------
 444
 445 Prev                           Up                           Next
 446 Chapter 25. Amanda Event API  Home  Chapter 27. Virtual Tape API
 447