X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/efe9458da1fc73745ded3c8f278501fd88179057..9f8418e870a70c264eda1598f2d470e5428c216d:/h/netsec.h

diff --git a/h/netsec.h b/h/netsec.h
index 98cfe256..e05e79f1 100644
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -22,9 +22,10 @@ netsec_context *netsec_init(void);
  * Arguments:
  *
  * ns_context	- Network security context
+ * closeflag	- If set to 1, close the socket descriptor as well.
  */
 
-void netsec_shutdown(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
@@ -33,31 +34,34 @@ void netsec_shutdown(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 *ns_context, int fd);
+void netsec_set_fd(netsec_context *ns_context, int readfd, int writefd);
 
 /*
- * Set the hostname of the server we're connecting to.
+ * Set the userid used to authenticate to this connection.
  *
  * Arguments:
+ *
  * ns_context	- Network security context
- * hostname	- Server hostname
+ * userid	- Userid to be used for authentication.  Cannot be NULL.
  */
 
-void netsec_set_hostname(netsec_context *ns_context, const char *hostname);
+void netsec_set_userid(netsec_context *ns_context, const char *userid);
 
 /*
- * Set the userid used to authenticate to this connection.
+ * Returns "snoop" status on current connection.
  *
  * Arguments:
  *
  * ns_context	- Network security context
- * userid	- Userid to be used for authentication.  Cannot be NULL.
+ *
+ * Returns "1" if snoop is enabled, 0 if it is not.
  */
 
-void netsec_set_userid(netsec_context *ns_context, const char *userid);
+int netsec_get_snoop(netsec_context *ns_context);
 
 /*
  * Sets "snoop" status; if snoop is set to a nonzero value, network traffic
@@ -71,22 +75,72 @@ void netsec_set_userid(netsec_context *ns_context, const char *userid);
 
 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 terminated with CR/LF.  Note that this will not work
- * if the data might have embedded NULs.
+ * 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, char **errstr);
+char *netsec_readline(netsec_context *ns_context, size_t *length,
+		      char **errstr);
 
 /*
  * Read bytes from the network.
@@ -104,6 +158,24 @@ char *netsec_readline(netsec_context *ns_context, char **errstr);
 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
  *
@@ -120,6 +192,22 @@ ssize_t netsec_read(netsec_context *ns_context, void *buffer, size_t size,
 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.
  *
@@ -141,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 */
 };
 
 /*
@@ -158,18 +247,19 @@ enum sasl_message_type {
  * indatasize	- The size of the input data in bytes
  * outdata	- Output data (freed by caller)
  * outdatasize	- Size of output data
- * snoop	- If set to true, plugin should log SASL exchange to stderr.
  * 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
@@ -178,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.
@@ -190,11 +284,10 @@ enum sasl_message_type {
  */
 
 typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
-				    unsigned char *indata,
+				    unsigned const char *indata,
 				    unsigned int indatasize,
 				    unsigned char **outdata,
-				    unsigned int *outdatasize,
-				    int snoop, char **errstr);
+				    unsigned int *outdatasize, char **errstr);
 
 /*
  * Sets the SASL parameters for this connection.  If this function is
@@ -209,7 +302,6 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  * 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 
@@ -297,3 +389,17 @@ int netsec_set_tls(netsec_context *context, int tls, char **errstr);
  */
 
 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)
+ *
+ */
+
+void netsec_err(char **errstr, const char *format, ...);