X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/9a8d690de3666e648cb70b1301a28a141aeb4ded..9f8418e870a70c264eda1598f2d470e5428c216d:/h/netsec.h diff --git a/h/netsec.h b/h/netsec.h index 48349392..e05e79f1 100644 --- a/h/netsec.h +++ b/h/netsec.h @@ -16,14 +16,16 @@ typedef struct _netsec_context netsec_context; netsec_context *netsec_init(void); /* - * Free()s an allocated netsec context and all associated resources. + * Shuts down the security context for a connection and frees all + * associated resources. * * Arguments: * * ns_context - Network security context + * closeflag - If set to 1, close the socket descriptor as well. */ -void netsec_free(netsec_context *ns_context); +void netsec_shutdown(netsec_context *ns_context, int closeflag); /* * Sets the file descriptor for this connection. This will be used by @@ -32,10 +34,192 @@ void netsec_free(netsec_context *ns_context); * Arguments: * * ns_context - Network security context - * fd - File descriptor of network connection. + * readfd - Read file descriptor of remote connection. + * writefd - Write file descriptor of remote connection */ -void netset_set_fd(netsec_context *, int fd); +void netsec_set_fd(netsec_context *ns_context, int readfd, int writefd); + +/* + * Set the userid used to authenticate to this connection. + * + * Arguments: + * + * ns_context - Network security context + * userid - Userid to be used for authentication. Cannot be NULL. + */ + +void netsec_set_userid(netsec_context *ns_context, const char *userid); + +/* + * Returns "snoop" status on current connection. + * + * Arguments: + * + * ns_context - Network security context + * + * Returns "1" if snoop is enabled, 0 if it is not. + */ + +int netsec_get_snoop(netsec_context *ns_context); + +/* + * Sets "snoop" status; if snoop is set to a nonzero value, network traffic + * will be logged on standard error. + * + * Arguments: + * + * ns_context - Network security context + * snoop - Integer value; set to nonzero to enable traffic logging + */ + +void netsec_set_snoop(netsec_context *ns_context, int snoop); + +/* + * A callback designed to handle the snoop output; it can be used by + * a protocol to massage the data in a more user-friendly way. + * + * Arguments: + * + * ns_context - Network security context + * string - String to output + * len - Length of string + * context - "Extra" context information to be used by callback. + */ + +typedef void (netsec_snoop_callback)(netsec_context *ns_context, + const char *string, size_t len, + void *context); + +/* + * Set the snoop callback function; will be used to handle protocol-specific + * messages. Set to NULL to disable. + * + * Arguments: + * + * ns_context - Network security context + * callback - Snoop callback + * context - Extra context information to be passed to callback. + */ + +void netsec_set_snoop_callback(netsec_context *ns_context, + netsec_snoop_callback *callback, void *context); + +/* + * A sample callback protocols can utilize; decode base64 tokens in the + * output. The context is a pointer to an int which contains an offset + * into the data to start decoding. + */ + +extern netsec_snoop_callback netsec_b64_snoop_decoder; + +/* + * Set the read timeout for this connection. + * + * Arguments: + * + * ns_context - Network security context + * timeout - Read timeout, in seconds. + */ + +void netsec_set_timeout(netsec_context *ns_context, int timeout); + +/* + * Read a "line" from the network. This reads one CR/LF terminated line. + * Returns a pointer to a NUL-terminated string. This memory is valid + * until the next call to any read function. Will return an error if + * the line does not terminate with a CR/LF. + * + * Arguments: + * + * ns_context - Network security context + * length - Returned length of string + * errstr - Error string + * + * Returns pointer to string, or NULL on error. + */ + +char *netsec_readline(netsec_context *ns_context, size_t *length, + char **errstr); + +/* + * Read bytes from the network. + * + * Arguments: + * + * ns_context - Network security context + * buffer - Read buffer + * size - Buffer size + * errstr - Error size + * + * Returns number of bytes read, or -1 on error. + */ + +ssize_t netsec_read(netsec_context *ns_context, void *buffer, size_t size, + char **errstr); + +/* + * Write data to the network; if encryption is being performed, we will + * do it. Data may be buffered; use netsec_flush() to flush any outstanding + * data to the network. + * + * Arguments: + * + * ns_context - Network security context + * buffer - Output buffer to write to network + * size - Size of data to write to network + * errstr - Error string + * + * Returns OK on success, NOTOK otherwise. + */ + +int netsec_write(netsec_context *ns_context, const void *buffer, size_t size, + char **errstr); + +/* + * Write bytes using printf formatting + * + * Arguments: + * + * ns_context - Network security context + * errstr - Error string + * format - Format string + * ... - Arguments for format string + * + * Returns OK on success, NOTOK on error. + */ + +int netsec_printf(netsec_context *ns_context, char **errstr, + const char *format, ...); + +/* + * Write bytes using a va_list argument. + * + * Arguments: + * + * ns_context - Network security context + * errstr - Error string + * format - Format string + * ap - stdarg list. + * + * Returns OK on success, NOTOK on error. + */ + +int netsec_vprintf(netsec_context *ns_context, char **errstr, + const char *format, va_list ap); + +/* + * Flush any buffered bytes to the network. + * + * Arguments: + * + * ns_context - Network security context + * errstr - Error string + * + * Returns OK on success, NOTOK on error. + */ + +int netsec_flush(netsec_context *ns_context, char **errstr); /* * Enumerated types for the type of message we are sending/receiving. @@ -45,7 +229,8 @@ enum sasl_message_type { NETSEC_SASL_START, /* Start of SASL authentication */ NETSEC_SASL_READ, /* Reading a message */ NETSEC_SASL_WRITE, /* Writing a message */ - NETSEC_CANCEL /* Cancel a SASL exchange */ + NETSEC_SASL_FINISH, /* Complete SASL exchange */ + NETSEC_SASL_CANCEL /* Cancel a SASL exchange */ }; /* @@ -64,15 +249,17 @@ enum sasl_message_type { * outdatasize - Size of output data * errstr - An error string to be returned (freed by caller). * + * As a general note, plugins should perform their own I/O. Buffers returned + * by NETSEC_SASL_READ should be allocated by the plugins and will be freed + * by the netsec package. Error messages returned should be created by + * netsec_err(). + * * Parameter interpretation based on mtype value: * * NETSEC_SASL_START - Create a protocol message that starts SASL * authentication. If an initial response is * supported, indata and indatasize will contain it. * Otherwise they will be set to NULL and 0. - * The complete protocol message should be - * stored in outdata/outdatasize, to be free()d - * by the caller. * NETSEC_SASL_READ - Parse and decode a protocol message and extract * out the SASL payload data. indata will be set * to NULL; the callback must read in the necessary @@ -81,8 +268,12 @@ enum sasl_message_type { * SASL message (again, must be free()d by the caller). * NETSEC_SASL_WRITE - Generate a protocol message to send over the * network. indata/indatasize will contain the - * SASL payload data. outdata/outdatasize should - * contain the complete protocol message. + * SASL payload data. + * NETSEC_SASL_FINISH - Process the final SASL message exchange; at + * this point SASL exchange should have completed + * and we should get a message back from the server + * telling us whether or not authentication is + * successful. All buffer parameters are NULL. * NETSEC_SASL_CANCEL - Generate a protocol message that cancels the * SASL protocol exchange; outdata/outdatasize * should contain this message. @@ -92,12 +283,11 @@ enum sasl_message_type { * to generate a cancel message. */ -typedef int (*_netsec_sasl_callback)(sasl_message_type mtype, - unsigned char *indata, - unsigned int indatasize, - unsigned char **outdata, - unsigned int *outdatasize, - char **errstr) netsec_sasl_callback; +typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype, + unsigned const char *indata, + unsigned int indatasize, + unsigned char **outdata, + unsigned int *outdatasize, char **errstr); /* * Sets the SASL parameters for this connection. If this function is @@ -110,18 +300,49 @@ typedef int (*_netsec_sasl_callback)(sasl_message_type mtype, * Arguments: * * ns_context - Network security context + * hostname - Fully qualified hostname of remote host. * service - Service name (set to NULL to disable SASL). - * mechlist - A space-separated list of mechanisms supported by the server. * mechanism - The mechanism desired by the user. If NULL, the SASL * library will attempt to negotiate the best mechanism. * callback - SASL protocol callbacks + * errstr - Error string. * * Returns NOTOK if SASL is not supported. */ -int netsec_set_sasl_params(netsec_context *ns_context, const char *service, - const char *mechanism, - netsec_sasl_callback *callback); +int netsec_set_sasl_params(netsec_context *ns_context, const char *hostname, + const char *service, const char *mechanism, + netsec_sasl_callback callback, char **errstr); + +/* + * Start SASL negotiation. The Netsec library will use the callbacks + * supplied in netsec_set_sasl_params() to format and parse the protocol + * messages. + * + * Arguments: + * + * ns_context - Network security context + * mechlist - Space-separated list of supported SASL mechanisms + * errstr - An error string to be returned upon error. + * + * Returns OK on success, NOTOK on failure. + */ + +int netsec_negotiate_sasl(netsec_context *ns_context, const char *mechlist, + char **errstr); + +/* + * Returns the chosen SASL mechanism by the SASL library or netsec. + * + * Arguments: + * + * ns_context - Network security context + * + * Returns a string containing the chosen mech, or NULL if SASL is not + * supported or in use. + */ + +char *netsec_get_sasl_mechanism(netsec_context *ns_context); /* * Set the OAuth service name used to retrieve the OAuth parameters from @@ -150,7 +371,35 @@ int netsec_set_oauth_service(netsec_context *ns_context, const char *service); * tls - If nonzero, enable TLS. Otherwise disable TLS * negotiation. * - * Returns NOTOK if TLS is not supported. + * Returns NOTOK if TLS is not supported or was unable to initialize. + */ + +int netsec_set_tls(netsec_context *context, int tls, char **errstr); + +/* + * Start TLS negotiation on this protocol. This connection should have + * netsec_set_tls() called on it. + * + * Arguments: + * + * ns_context - Network security context + * errstr - Error string upon failure. + * + * Returns OK on success, NOTOK on failure. + */ + +int netsec_negotiate_tls(netsec_context *ns_context, char **errstr); + +/* + * Allocate and format an error string; should be used by plugins + * to report errors. + * + * Arguments: + * + * errstr - Error string to be returned + * format - printf(3) format string + * ... - Arguments to printf(3) + * */ -int netsec_set_tls(netsec_context *context, int tls); +void netsec_err(char **errstr, const char *format, ...);