From: Ken Hornstein Date: Mon, 12 Sep 2016 23:07:29 +0000 (-0400) Subject: Beginnings of a new library API. X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/9a8d690de3666e648cb70b1301a28a141aeb4ded?ds=inline;hp=-c Beginnings of a new library API. --- 9a8d690de3666e648cb70b1301a28a141aeb4ded diff --git a/Makefile.am b/Makefile.am index f618f24d..1b31fa1a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -197,9 +197,9 @@ noinst_LIBRARIES = sbr/libmh.a mts/libmts.a noinst_HEADERS = h/addrsbr.h h/aliasbr.h h/crawl_folders.h h/dropsbr.h \ h/fmt_compile.h h/fmt_scan.h h/icalendar.h h/md5.h h/mf.h \ h/mh.h h/mhcachesbr.h h/mhparse.h h/mime.h \ - h/mts.h h/nmh.h h/picksbr.h h/popsbr.h h/prototypes.h \ - h/rcvmail.h h/scansbr.h h/signals.h h/tws.h h/utils.h \ - mts/smtp/smtp.h sbr/ctype-checked.h h/oauth.h \ + h/mts.h h/nmh.h h/netsec.h h/picksbr.h h/popsbr.h + h/prototypes.h h/rcvmail.h h/scansbr.h h/signals.h h/tws.h + h/utils.h mts/smtp/smtp.h sbr/ctype-checked.h h/oauth.h \ thirdparty/jsmn/jsmn.h ## diff --git a/h/netsec.h b/h/netsec.h new file mode 100644 index 00000000..48349392 --- /dev/null +++ b/h/netsec.h @@ -0,0 +1,156 @@ +/* + * Network security library routines for nmh. + * + * 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; + +/* + * Create a network security context. Returns the allocated network + * security context. Cannot fail. + */ + +netsec_context *netsec_init(void); + +/* + * Free()s an allocated netsec context and all associated resources. + * + * Arguments: + * + * ns_context - Network security context + */ + +void netsec_free(netsec_context *ns_context); + +/* + * Sets the file descriptor for this connection. This will be used by + * the underlying communication. + * + * Arguments: + * + * ns_context - Network security context + * fd - File descriptor of network connection. + */ + +void netset_set_fd(netsec_context *, int fd); + +/* + * Enumerated types for the type of message we are sending/receiving. + */ + +enum sasl_message_type { + NETSEC_SASL_START, /* Start of SASL authentication */ + NETSEC_SASL_READ, /* Reading a message */ + NETSEC_SASL_WRITE, /* Writing a message */ + NETSEC_CANCEL /* Cancel a SASL exchange */ +}; + +/* + * The SASL callback; this is designed to parse a protocol-specific + * message and return the SASL protocol message back. + * + * The meaning of the arguments to the callback depend on the mtype + * arguments. See below for more detail. + * + * Arguments: + * + * mtype - The type of message we are processing (read/write/cancel). + * indata - A pointer to any input data. + * indatasize - The size of the input data in bytes + * outdata - Output data (freed by caller) + * outdatasize - Size of output data + * errstr - An error string to be returned (freed by caller). + * + * 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. + * 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 + * data using the appropriate netsec function. + * outdata/outdatasize should contain the decoded + * 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. + * NETSEC_SASL_CANCEL - Generate a protocol message that cancels the + * SASL protocol exchange; outdata/outdatasize + * should contain this message. + * + * 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. + */ + +typedef int (*_netsec_sasl_callback)(sasl_message_type mtype, + unsigned char *indata, + unsigned int indatasize, + unsigned char **outdata, + unsigned int *outdatasize, + char **errstr) netsec_sasl_callback; + +/* + * Sets the SASL parameters for this connection. If this function is + * not called or is called with NULL for arguments, SASL authentication + * will not be attempted for this connection. + * + * The caller must provide a callback to parse the protocol and return + * the SASL protocol messages (see above for callback details). + * + * Arguments: + * + * ns_context - Network security context + * service - Service name (set to NULL to disable SASL). + * mechlist - A space-separated list of mechanisms supported by the server. + * mechanism - The mechanism desired by the user. If NULL, the SASL + * library will attempt to negotiate the best mechanism. + * callback - SASL protocol callbacks + * + * Returns NOTOK if SASL is not supported. + */ + +int netsec_set_sasl_params(netsec_context *ns_context, const char *service, + const char *mechanism, + netsec_sasl_callback *callback); + +/* + * Set the OAuth service name used to retrieve the OAuth parameters from + * user's profile. Just calling this function is not enough to guarantee + * that XOAUTH2 authentication will be performed; the appropriate mechanism + * name must be passed into netsec_set_sasl_params(). + * + * Arguments: + * + * ns_context - Network security context + * service - OAuth2 service names. + * + * Returns NOTOK if OAuth2 is not supported. + */ + +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. + * + * Arguments + * + * tls - If nonzero, enable TLS. Otherwise disable TLS + * negotiation. + * + * Returns NOTOK if TLS is not supported. + */ + +int netsec_set_tls(netsec_context *context, int tls);