X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/ceaab2f46ae8fa4598b9682eaf3210cda21517c9..c02f66668d32980a3770e450061c5b96b9f31690:/h/netsec.h diff --git a/h/netsec.h b/h/netsec.h index ef0d521d..7dac5214 100644 --- a/h/netsec.h +++ b/h/netsec.h @@ -34,10 +34,11 @@ void netsec_shutdown(netsec_context *ns_context, int closeflag); * 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. @@ -50,6 +51,19 @@ void netsec_set_fd(netsec_context *ns_context, int fd); 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. * @@ -74,6 +88,44 @@ int netsec_get_snoop(netsec_context *ns_context); 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. * @@ -100,7 +152,7 @@ void netsec_set_timeout(netsec_context *ns_context, int timeout); * 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); /* @@ -210,16 +262,17 @@ enum sasl_message_type { * 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 @@ -228,10 +281,7 @@ 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 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 @@ -244,11 +294,6 @@ enum sasl_message_type { * 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, @@ -268,7 +313,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. @@ -278,8 +322,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); /* @@ -332,17 +376,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