lock_file.c: close(2) file descriptor on failure, avoiding leak.

[nmh] / h / netsec.h

diff --git a/h/netsec.h b/h/netsec.h
index e05e79f1ea1138db6de040cf57599953285598a4..0a14a1d01951e56ed10303ffaffd768ae37f0229 100644 (file)
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -1,11 +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;
 
 /*
@@ -17,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
@@ -51,6 +49,19 @@ void netsec_set_fd(netsec_context *ns_context, int readfd, int writefd);
 
 void netsec_set_userid(netsec_context *ns_context, const char *userid);
 
+/*
+ * Set the hostname of the server we're connecting to.  This is used
+ * by the Cyrus-SASL library and by the TLS code.  This must be called
+ * before netsec_negotiate_tls() or netsec_set_sasl_params().
+ *
+ * Arguments:
+ *
+ * ns_context  - Network security context
+ * hostname    - FQDN of remote host.  Cannot be NULL.
+ */
+
+void netsec_set_hostname(netsec_context *ns_context, const char *hostname);
+
 /*
  * Returns "snoop" status on current connection.
  *
@@ -61,7 +72,7 @@ void netsec_set_userid(netsec_context *ns_context, const char *userid);
  * 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
@@ -190,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.
@@ -206,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.
@@ -300,7 +311,6 @@ typedef int (*netsec_sasl_callback)(enum 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).
  * mechanism   - The mechanism desired by the user.  If NULL, the SASL
  *               library will attempt to negotiate the best mechanism.
@@ -310,8 +320,8 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  * Returns NOTOK if SASL is not supported.
  */
 
-int netsec_set_sasl_params(netsec_context *ns_context, const char *hostname,
-                          const char *service, const char *mechanism,
+int netsec_set_sasl_params(netsec_context *ns_context, const char *service,
+                          const char *mechanism,
                           netsec_sasl_callback callback, char **errstr);
 
 /*
@@ -342,7 +352,7 @@ 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;
 
 /*
  * Set the OAuth service name used to retrieve the OAuth parameters from
@@ -364,17 +374,23 @@ int netsec_set_oauth_service(netsec_context *ns_context, const char *service);
  * Controls whether or not TLS will be negotiated for this connection.
  *
  * Note: callers still have to call netsec_tls_negotiate() to start
- * TLS negotiation at the appropriate point in the protocol.
+ * TLS negotiation at the appropriate point in the protocol.  The
+ * remote hostname (controlled by netsec_set_hostname()) should have
+ * already been set before this function is called unless certificate
+ * verification is disabled.
  *
  * Arguments
  *
  * tls         - If nonzero, enable TLS. Otherwise disable TLS
  *               negotiation.
+ * noverify    - If nonzero, disable server certificate and hostname
+ *               validation.
  *
  * Returns NOTOK if TLS is not supported or was unable to initialize.
  */
 
-int netsec_set_tls(netsec_context *context, int tls, char **errstr);
+int netsec_set_tls(netsec_context *context, int tls, int noverify,
+                  char **errstr);
 
 /*
  * Start TLS negotiation on this protocol.  This connection should have
@@ -402,4 +418,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);