-/*
- * 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;
/*
/*
* 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
* writefd - Write file descriptor of remote connection
*/
-void netsec_set_fd(netsec_context *ns_context, int readfd, writefd);
+void netsec_set_fd(netsec_context *ns_context, int readfd, int writefd);
/*
* Set the userid used to authenticate to this connection.
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.
*
* 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
*/
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.
*/
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.
* 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
* 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
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
* 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.
* callback - SASL protocol callbacks
+ * context - Extra context information passed to the protocol callback
* errstr - Error string.
*
* 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,
- netsec_sasl_callback callback, char **errstr);
+int netsec_set_sasl_params(netsec_context *ns_context, const char *service,
+ const char *mechanism,
+ netsec_sasl_callback callback,
+ void *context, char **errstr);
/*
* Start SASL negotiation. The Netsec library will use the callbacks
* 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
* 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
*
*/
-void netsec_err(char **errstr, const char *format, ...);
+void netsec_err(char **errstr, const char *format, ...)
+ CHECK_PRINTF(2, 3);
projects / nmh / blobdiff