Garbage-collect all of this unused code.

[nmh] / h / netsec.h

diff --git a/h/netsec.h b/h/netsec.h
index f5abbcb5c80af27c22125a9360304c30e8faa531..27d29382422abc9593225a9703885d88c54b5fbd 100644 (file)
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -22,9 +22,10 @@ netsec_context *netsec_init(void);
  * Arguments:
  *
  * ns_context  - Network security context
  * 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
 
 /*
  * Sets the file descriptor for this connection.  This will be used by


@@ -36,7 +37,30 @@ void netsec_shutdown(netsec_context *ns_context);
  * fd          - File descriptor of network connection.
  */
 
  * fd          - File descriptor of network connection.
  */
 

-void netset_set_fd(netsec_context *ns_context, int fd);
+void netsec_set_fd(netsec_context *ns_context, int fd);
+
+/*
+ * 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
 
 /*
  * Sets "snoop" status; if snoop is set to a nonzero value, network traffic


@@ -50,22 +74,48 @@ void netset_set_fd(netsec_context *ns_context, int fd);
 
 void netsec_set_snoop(netsec_context *ns_context, int snoop);
 
 
 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
+ */
+
+typedef void (*netsec_snoop_callback)(netsec_context *ns_context,
+                                    const char *string, size_t len);
+
+/*
+ * 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
 /*
  * 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
  *
  * Arguments:
  *
  * ns_context  - Network security context

+ * length      - Returned length of string

  * errstr      - Error string
  *
  * Returns pointer to string, or NULL on error.
  */
 
  * 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 *lenght,
+                     char **errstr);

 
 /*
  * Read bytes from the network.
 
 /*
  * Read bytes from the network.


@@ -83,6 +133,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);
 
 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
  *
 /*
  * Write bytes using printf formatting
  *


@@ -99,6 +167,35 @@ 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, ...);
 
 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.
  */
 /*
  * Enumerated types for the type of message we are sending/receiving.
  */


@@ -107,7 +204,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_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 */

 };
 
 /*
 };
 
 /*


@@ -124,18 +222,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
  * 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).
  *
  * 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.
  * 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
  * 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


@@ -144,8 +243,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 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.
  * NETSEC_SASL_CANCEL  - Generate a protocol message that cancels the
  *                       SASL protocol exchange; outdata/outdatasize
  *                       should contain this message.


@@ -156,11 +259,10 @@ enum sasl_message_type {
  */
 
 typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  */
 
 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 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
 
 /*
  * Sets the SASL parameters for this connection.  If this function is


@@ -173,18 +275,49 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  * Arguments:
  *
  * ns_context  - Network security context
  * Arguments:
  *
  * ns_context  - Network security context

+ * hostname    - Fully qualified hostname of remote host.

  * service     - Service name (set to NULL to disable SASL).
  * 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 
  * 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.
  */
 
  *
  * 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
 
 /*
  * Set the OAuth service name used to retrieve the OAuth parameters from


@@ -224,9 +357,24 @@ int netsec_set_tls(netsec_context *context, int tls, char **errstr);
  *
  * Arguments:
  *
  *
  * Arguments:
  *

+ * ns_context  - Network security context

  * errstr      - Error string upon failure.
  *
  * Returns OK on success, NOTOK on failure.
  */
 
  * errstr      - Error string upon failure.
  *
  * Returns OK on success, NOTOK on failure.
  */
 

-int netsec_negotiate_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, ...);