X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/c2655c2b98253e03c42eeeee1e5c60fe7107c5a4..refs/heads/master:/h/netsec.h?ds=sidebyside

diff --git a/h/netsec.h b/h/netsec.h
index b115ed7c..6c69c82c 100644
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -52,7 +52,7 @@ 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().
+ * before netsec_set_tls() or netsec_set_sasl_params().
  *
  * Arguments:
  *
@@ -285,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
@@ -358,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
@@ -379,9 +399,8 @@ int netsec_set_oauth_service(netsec_context *ns_context, const char *service);
  *
  * Note: callers still have to call netsec_tls_negotiate() to start
  * 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.
+ * remote hostname (controlled by netsec_set_hostname()) is required
+ * to be set before calling this function.
  *
  * Arguments
  *
@@ -398,7 +417,7 @@ int netsec_set_tls(netsec_context *context, int tls, int noverify,
 
 /*
  * Start TLS negotiation on this protocol.  This connection should have
- * netsec_set_tls() called on it.
+ * netsec_set_tls() already called on it.
  *
  * Arguments:
  *