Fix invalid pointer arithmetic.

[nmh] / h / netsec.h

diff --git a/h/netsec.h b/h/netsec.h
index e22b39e3f461c10c4feee9f3e931d99c432b2048..3e7975b417f742b78cfa3312dc06924d24893394 100644 (file)
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -1,10 +1,9 @@
-/* Network security library routines for nmh.
+/* netsec.h -- network-security library routines.
  *
  * These are a common set of routines to handle network security for
  * things like SASL and OpenSSL.
  */
 
-struct _netsec_context;
 typedef struct _netsec_context netsec_context;
 
 /*
@@ -16,15 +15,15 @@ netsec_context *netsec_init(void);
 
 /*
  * Shuts down the security context for a connection and frees all
- * associated resources.
+ * associated resources.  Will unconditionally close the network socket
+ * as well.
  *
  * Arguments:
  *
  * ns_context  - Network security context
- * closeflag   - If set to 1, close the socket descriptor as well.
  */
 
-void netsec_shutdown(netsec_context *ns_context, int closeflag);
+void netsec_shutdown(netsec_context *ns_context);
 
 /*
  * Sets the file descriptor for this connection.  This will be used by
@@ -73,7 +72,7 @@ void netsec_set_hostname(netsec_context *ns_context, const char *hostname);
  * Returns "1" if snoop is enabled, 0 if it is not.
  */
 
-int netsec_get_snoop(netsec_context *ns_context);
+int netsec_get_snoop(netsec_context *ns_context) PURE;
 
 /*
  * Sets "snoop" status; if snoop is set to a nonzero value, network traffic
@@ -202,7 +201,7 @@ int netsec_write(netsec_context *ns_context, const void *buffer, size_t size,
  */
 
 int netsec_printf(netsec_context *ns_context, char **errstr,
-                 const char *format, ...);
+                 const char *format, ...) CHECK_PRINTF(3, 4);
 
 /*
  * Write bytes using a va_list argument.
@@ -218,7 +217,7 @@ int netsec_printf(netsec_context *ns_context, char **errstr,
  */
 
 int netsec_vprintf(netsec_context *ns_context, char **errstr,
-                  const char *format, va_list ap);
+                  const char *format, va_list ap) CHECK_PRINTF(3, 0);
 
 /*
  * Flush any buffered bytes to the network.
@@ -259,6 +258,7 @@ enum sasl_message_type {
  * indatasize  - The size of the input data in bytes
  * outdata     - Output data (freed by caller)
  * outdatasize - Size of output data
+ * context     - Extra context information potentially required by callback
  * errstr      - An error string to be returned (freed by caller).
  *
  * As a general note, plugins should perform their own I/O.  Buffers returned
@@ -285,10 +285,12 @@ enum sasl_message_type {
  *                       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.
+ *                       successful; the plugin should return OK/NOTOK
+ *                       to indicate whether or not the authentication
+ *                       was 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.
+ *                       SASL protocol exchange; the plugin should
+ *                       send this message.  All buffer parameters are NULL.
  *
  * The callback should return OK on success, NOTOK on failure.  Depending
  * at the point of the authentication exchange, the callback may be asked
@@ -299,7 +301,8 @@ 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);
+                                   unsigned int *outdatasize,
+                                   void *context, char **errstr);
 
 /*
  * Sets the SASL parameters for this connection.  If this function is
@@ -316,6 +319,7 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  * mechanism   - The mechanism desired by the user.  If NULL, the SASL
  *               library will attempt to negotiate the best mechanism.
  * callback    - SASL protocol callbacks 
+ * context     - Extra context information passed to the protocol callback
  * errstr      - Error string.
  *
  * Returns NOTOK if SASL is not supported.
@@ -323,7 +327,8 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
 
 int netsec_set_sasl_params(netsec_context *ns_context, const char *service,
                           const char *mechanism,
-                          netsec_sasl_callback callback, char **errstr);
+                          netsec_sasl_callback callback,
+                          void *context, char **errstr);
 
 /*
  * Start SASL negotiation.  The Netsec library will use the callbacks
@@ -353,7 +358,25 @@ int netsec_negotiate_sasl(netsec_context *ns_context, const char *mechlist,
  * supported or in use.
  */
 
-char *netsec_get_sasl_mechanism(netsec_context *ns_context);
+char *netsec_get_sasl_mechanism(netsec_context *ns_context) PURE;
+
+/*
+ * Returns the SASL strength security factor (SSF) for the negotiated
+ * authentication mechanism.
+ *
+ * The exact meaning of the SSF depends on the mechanism chosen, but in
+ * general:
+ *
+ * 0   - No encryption or integrity protection via SASL.
+ * 1   - Integrity protection only.
+ * >1  - Encryption
+ *
+ * The SSF is distinct from any encryption that is negotiated by TLS;
+ * if TLS is negotiated then the netsec SASL code will automatically disable
+ * any attempt to negotiate a security layer and thus the SSF will be 0.
+ */
+
+int netsec_get_sasl_ssf(netsec_context *ns_context) PURE;
 
 /*
  * Set the OAuth service name used to retrieve the OAuth parameters from
@@ -419,4 +442,5 @@ int netsec_negotiate_tls(netsec_context *ns_context, char **errstr);
  *
  */
 
-void netsec_err(char **errstr, const char *format, ...);
+void netsec_err(char **errstr, const char *format, ...)
+    CHECK_PRINTF(2, 3);