X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/93a18dd7a6b92922361383a4e6152380da5f3583..94187a80bd60baab4b9c4b949ad820d730578123:/h/netsec.h

diff --git a/h/netsec.h b/h/netsec.h
index 0a14a1d0..3e7975b4 100644
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -258,6 +258,7 @@ enum sasl_message_type {
  * 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
@@ -284,10 +285,12 @@ enum sasl_message_type {
  *			  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
@@ -298,7 +301,8 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
 				    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
@@ -315,6 +319,7 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
  * 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.
@@ -322,7 +327,8 @@ typedef int (*netsec_sasl_callback)(enum sasl_message_type mtype,
 
 int netsec_set_sasl_params(netsec_context *ns_context, const char *service,
 			   const char *mechanism,
-			   netsec_sasl_callback callback, char **errstr);
+			   netsec_sasl_callback callback,
+			   void *context, char **errstr);
 
 /*
  * Start SASL negotiation.  The Netsec library will use the callbacks
@@ -354,6 +360,24 @@ int netsec_negotiate_sasl(netsec_context *ns_context, const char *mechlist,
 
 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
  * user's profile.  Just calling this function is not enough to guarantee