-/*
- * 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;
/*
* 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 netsec_set_fd(netsec_context *ns_context, int fd);
+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.
*
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.
*
* Returns pointer to string, or NULL on error.
*/
-char *netsec_readline(netsec_context *ns_context, size_t *lenght,
+char *netsec_readline(netsec_context *ns_context, size_t *length,
char **errstr);
/*
* outdatasize - Size of output data
* 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. Alternatively, the plugin
- * can choose to send the data on their own.
* 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
* 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. Alternatively
- * the plugin can write the data to the network
- * directly.
+ * 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
* The callback should return OK on success, NOTOK on failure. Depending
* at the point of the authentication exchange, the callback may be asked
* to generate a cancel message.
- *
- * Some higher-level notes in terms of protocol management:
- *
- * Any data returned in outdata should consist of allocated data that
- * the sasl routines is expected to free.
*/
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.
* 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);
/*
* 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
projects / nmh / blobdiff