X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=docs%2Fsecurity-api.txt;h=e69de29bb2d1d6434b8b29ae775ad8c2e48c5391;hb=d92f70685083588e2a7ce6bc312a735f6937b5a6;hp=e0c4a839ed3904e5dd0a1f9f642ee2e0051db53d;hpb=6c1f39091444e58c33362f0cc086375d9d273e77;p=debian%2Famanda diff --git a/docs/security-api.txt b/docs/security-api.txt index e0c4a83..e69de29 100644 --- a/docs/security-api.txt +++ b/docs/security-api.txt @@ -1,447 +0,0 @@ - - Chapter 26. Amanda Security API -Prev Part V. Technical Background Next - -------------------------------------------------------------------------------- - -Chapter 26. Amanda Security API - - -Mike Grupenhoff - -Original text -AMANDA Core Team - - -Stefan G. Weichinger - -XML-conversion;Updates -AMANDA Core Team - -Table of Contents - - - Introduction - - The_Problem - - The_API - - - protocol_packet_transmission_functions - - stream_functions - - - Data_Types - - - security_driver_t - - security_handle_t - - security_stream_t - - security_status_t - - - SECURITY_DRIVERS - - - name - - connect - - accept - - close - - sendpkt - - recvpkt - - recvpkt_cancel - - stream_server - - stream_accept - - stream_client - - stream_close - - stream_auth - - stream_id - - stream_write - - stream_read - - stream_read_cancel - - - - Introduction - -This is a document of the API for defining and utilizing multiple security and -transport mechanisms for the Amanda network protocol. -The goal of this API is to allow several different forms of communication and -authentication to exist between the Amanda server and its clients. - - The Problem - -There exist many potential ways that a user might wish to grant access to the -Amanda daemon. The two currently supported are BSD (reserved port) and Kerberos -IV security. The current implementation of these two methods is not very -general, and adding additional methods requires a large amount of code to be -modified. -Additionally, the current methods require the protocol and dump transport to be -transmitted across the network using a pre-defined method. The Amanda protocol -currently must be sent using udp datagrams to a well-known port, and the dumps -are transported using tcp connections between ports negotiated via the -protocol. - - The API - -The security API was designed to be a layer in between the core logic of Amanda -and the transport and authentication of the protocol and dumps. -The component server and client programs now deal with abstract concepts -instead of concrete udp and tcp handles. -The prefix "security_" is reserved for use as the namespace of this API. - - protocol packet transmission functions - -These functions exist for transmitting pkt_t's between the client and server. -These functions operate on security_handle_t objects. These objects are -described later. - - security_getdriver - -const security_driver_t *security_getdriver(const char *drivername); -Given a security type ("KRB4", "BSD", "SSH", etc), returns a pointer to that -type's security_driver_t (section 4.1), or NULL if no driver exists. - - security_connect - -void security_connect(const security_driver_t *h, const char *hostname, char * -(*conf_fn)(char *arg, void *arg), void (*fn)(void *arg, security_handle_t *h, -security_status_t s), void *arg); -Given a security driver, and a hostname, calls back with a security_handle_t -(section 4.2) that can be used to communicate with that host. The status arg to -the callback is reflects the success of the request. Error messages can be had -via security_geterror(). -This is expected to be the Amanda server's interface for setting up connections -to clients. -conf_fn is used to determine configuration information. If NULL, no -configuration information is available. - - security_accept - -void security_accept(const security_driver_t *h, int in, int out, void -(*callback)(security_handle_t *, pkt_t *)); -Given a security driver, an input file descriptor, and an output file -descriptor, and a callback, when new connections are detected on the given file -descriptors, the function is called with a newly created security handle and -the initial packet received. -This is expected to be the Amanda daemon's interface for setting up incoming -connections from the Amanda server. The file descriptors are typically 0 and 1 -(stdin/stdout). -This function uses the event interface, and only works properly when event_loop -() is called later in the program. - - security_close - -void security_close(security_handle_t *h); -Closes a connection created by a security_connect() or security_accept(). - - security_sendpkt - -int security_sendpkt(security_handle_t *h, const pkt_t *pkt); -Transmits a pkt_t over a security handle. Returns 0 on success, or negative on -error. A descriptive error message can be obtained via security_geterror(). - - security_recvpkt - -int security_recvpkt(security_handle_t *h, void (*callback)(void *arg, pkt_t -*pkt, security_status_t), void *arg, int timeout); -Requests that when incoming packets arrive for this handle, the given function -is called with the given argument, the received packet, and the status of the -reception. -If a packet does not arrive within the number of seconds specified in the -'timeout' argument, RECV_TIMEOUT is passed in the status argument of the -timeout. -On receive error, the callback's status argument will be set to RECV_ERROR. An -error message can be retrieved via security_geterror(). -On successful reception, RECV_OK will be passed in the status argument, and the -pkt argument will point to a valid packet. -This function uses the event interface. Callbacks will only be generated when -event_loop() is called. - - security_recvpkt_cancel - -int security_recvpkt_cancel(security_handle_t *h); -Cancels a previous recvpkt request for this handle. - - security_geterror - -const char *security_geterror(security_handle_t *h); -Returns a descriptive error message for the last error condition on this -handle. - - security_seterror - -void security_seterror(security_handle_t *h, const char *msg, ...); -Sets the string that security_geterror() returns. - - security_handleinit - -void security_handleinit(security_handle_t *, const security_driver_t *); -Initializes a security_handle_t. This is meant to be called only by security -drivers to initialize the common part of a newly allocated security_handle_t. - - stream functions - -These functions exist for transmitting random data over a stream-like -connection. -These functions operate on security_stream_t objects, which are described -later. - - security_stream_server - -security_stream_t *security_stream_server(security_handle_t *h); -Creates the server end of a security stream, and will receive a connection from -the host on the other end of the security handle passed. -Returns a security_stream_t on success, and NULL on error. Error messages can -be obtained by calling security_geterror() on the security handle associated -with this stream. - - security_stream_accept - -int security_stream_accept(security_stream_t *); -Given a security stream created by security_stream_server, blocks until a -connection is made from the remote end. -Returns 0 on success, and -1 on error. Error messages can be obtained by -calling security_stream_geterror(). - - security_stream_client - -security_stream_t *security_stream_client(security_handle_t *h, int id); -Creates the client end of a security stream, and connects it to the machine on -the other end of the security handle. The 'id' argument identifies which stream -on the other end to connect to. -Returns a security_stream_t on success, and NULL on error. Error messages can -be obtained by calling security_geterror() on the security handle associated -with this stream. - - security_stream_close - -void security_stream_close(security_stream_t *s); -Closes a security stream and frees up resources associated with it. - - security_stream_auth - -int security_stream_auth(security_stream_t *s); -Authenticate a connected security stream. -Returns 0 on success, and -1 on error. Error messages can be obtained by -calling security_stream_geterror(). - - security_stream_id - -int security_stream_id(security_stream_t *s); -Returns an identifier which can be used to connect to this security stream with -security_stream_client(). -Typical usage would be for one end of a connection to create a stream with -security_stream_server(), and then transmit the id for that stream to the other -side. The other side will then connect to that id with security_stream_client -(). - - security_stream_write - -int security_stream_write(security_stream_t *s, const void *buf, size_t -bufsize); -Writes a chunk of data to the security stream. Returns 0 on success, or -negative on error. Error messages can be obtained by calling -security_stream_geterror(). - - security_stream_read - -void security_stream_read(security_stream_t *s, void (*callback)(void *arg, -void *buf, int bufsize), void *arg); -Requests that when data is ready to be read on this stream, the given function -is called with the given arg, a buffer full of data, and the size of that -buffer. -On error, the bufsize will be negative. An error message can be retrieved by -calling security_stream_geterror(). -This function uses the event interface. Callbacks will only be generated while -in event_loop(). - - security_stream_read_cancel - -void security_stream_read_cancel(security_stream_t *s); -Cancels a previous read request. - - security_stream_geterror - -const char *security_stream_geterror(security_stream_t *h); -Returns a descriptive error message for the last error condition on this -stream. - - security_stream_seterror - -void security_stream_seterror(security_stream_t *h, const char *msg, ...); -Sets the string that security_stream_geterror() returns. - - Data Types - -All visible data types are meant to be opaque to the caller. At no time should -a caller have to access a member of any data type directly. The API should -always be used instead. - - security_driver_t - -This is a static object containing function vectors that implement the API for -a particular security type. - - security_handle_t - -This is an object that describes a protocol connection to a remote server. -There is one security_handle_t per request, and there can be many to the same -remote host. - - security_stream_t - -This is an object that describes a data connection to a remote host. It is -always associated and derived from a security_handle_t. Arbitrary data can be -passed over a security stream. - - security_status_t - -This is an enumerated type that is passed to the callback of security_recvpkt -and security_connect. The possible values it can have are: -S_OK - the pkt_t was received fine S_TIMEOUT - no pkt_t was received within the -time specified in the timeout argument to security_recvpkt(). S_ERROR - an -error occurred during reception. Call security_geterror() for more information. - - SECURITY DRIVERS - -Each security type is defined by a struct of function vectors. These methods -implement the details of this security type. -This section will document each element of security_driver_t. - - name - -const char *name; -This is the name of the driver. This is used by security_getdriver() to -associate a name with a driver type. - - connect - -void (*connect)(const char *hostname, void (*fn)(void *, security_handle_t *, -security_status_t), void *); -This is the implementation of security_connect(). It actually sets up the -connection, and then returns a structure describing the connection. The first -element of this structure MUST be a security_handle_t, because it will be cast -to that after it is passed up to the caller. -The first argument is the host to connect to. The second argument is a function -to call when a connection is made. The third argument is passed to the -callback. -The callback takes three arguments. The first is the caller supplied void -pointer. The second is a newly allocated security handle. The third is a -security_status_t flag indicating the success or failure of the operation. - - accept - -void (*accept)(int in, int out, void (*callback)(security_handle_t *handle, -pkt_t *pkt)); -This is the implementation of security_accept(). It is passed the input and -output file descriptors and a callback. The callback takes a security handle -argument and also an initial packet received for that handle. - - close - -void (*close)(void *handle); -The implementation of security_close(). - - sendpkt - -int (*sendpkt)(void *handle, pkt_t *pkt); -The implementation of security_sendpkt(). Security information is usually added -by the driver before transmission. - - recvpkt - -void (*recvpkt)(void *handle, void (*callback)(void *arg, pkt_t *pkt, -security_status_t), void *arg); -The implementation of security_recvpkt(). It will typically be layered onto the -event interface somehow. It can assume that a caller will eventually call -event_loop(). - - recvpkt_cancel - -void (*recvpkt_cancel)(void *handle); -The implementation of security_recvpkt_cancel(). Drivers should allow this to -be run even if no recvpkt was scheduled, or if one was previously cancelled. - - stream_server - -void *(*stream_server)(void *handle); -Implementation of security_stream_server(). This function returns a object -describing the stream. The first member of this object MUST be a -security_stream_t, because it will be cast to that. - - stream_accept - -int (*stream_accept)(void *stream); -After calling stream_server, stream_accept must be called on the stream before -it is fully connected. - - stream_client - -void *(*stream_client)(void *handle, int id); -Implementation of security_stream_client(). The id argument is something -returned by security_stream_id(). Again, the handle is referenced counted. -This function returns a object describing the stream. The first member of this -object MUST be a security_stream_t, because it will be cast to that. - - stream_close - -void (*stream_close)(void *stream); -Close and free up resources for an open stream. - - stream_auth - -int (*stream_auth)(void *stream); -Authenticate a connected stream. - - stream_id - -int (*stream_id)(void *stream); -Return a unique id for this stream. This is to be used by stream_client() to -connect to this stream. - - stream_write - -int (*stream_write)(void *stream, const void *buf, size_t bufsize); -Implementation of security_stream_write. - - stream_read - -void (*stream_read)(void *stream, void (*callback)(void *arg, void *buf, int -bufsize), void *arg); -Implementation of security_stream_read. - - stream_read_cancel - -void (*stream_read_cancel)(void *stream); -Implementation of security_stream_read_cancel. - -Note - -Refer to http://www.amanda.org/docs/security-api.html for the current version -of this document. -------------------------------------------------------------------------------- - -Prev Up Next -Chapter 25. Amanda Event API Home Chapter 27. Virtual Tape API -