doc/flux_msg_handler_create(3): add rolemask funcs

Problem: message handler filtering based on rolemasks
is not discussed in flux_msg_handler_create(3).

Add man page stubs for flux_msg_handler_allow_rolemask()
and flux_msg_handler_deny_rolemask(), a SECURITY section,
and a reference to RFC 12.

Fixes flux-framework#1260

doc/man3/Makefile.am

@@ -88,6 +88,8 @@ MAN3_FILES_SECONDARY = \
 	flux_msg_handler_destroy.3 \
 	flux_msg_handler_start.3 \
 	flux_msg_handler_stop.3 \
+	flux_msg_handler_allow_rolemask.3 \
+	flux_msg_handler_deny_rolemask.3 \
 	flux_msg_handler_delvec.3 \
 	flux_child_watcher_get_rpid.3 \
 	flux_child_watcher_get_rstatus.3 \
@@ -202,6 +204,8 @@ flux_check_watcher_create.3: flux_idle_watcher_create.3
 flux_msg_handler_destroy.3: flux_msg_handler_create.3
 flux_msg_handler_start.3: flux_msg_handler_create.3
 flux_msg_handler_stop.3: flux_msg_handler_create.3
+flux_msg_handler_allow_rolemask.3: flux_msg_handler_create.3
+flux_msg_handler_deny_rolemask.3: flux_msg_handler_create.3
 flux_msg_handler_delvec.3: flux_msg_handler_addvec.3
 flux_child_watcher_get_rpid.3: flux_child_watcher_create.3
 flux_child_watcher_get_rstatus.3: flux_child_watcher_create.3

doc/man3/flux_msg_handler_create.adoc

@@ -6,7 +6,9 @@ flux_msg_handler_create(3)
 NAME
 ----
 flux_msg_handler_create, flux_msg_handler_destroy,
-flux_msg_handler_start, flux_msg_handler_stop -  manage message handlers
+flux_msg_handler_start, flux_msg_handler_stop,
+flux_msg_handler_allow_rolemask,
+flux_msg_handler_deny_rolemask  -  manage message handlers
 
 
 SYNOPSIS
@@ -30,6 +32,12 @@ SYNOPSIS
 
  void flux_msg_handler_stop (flux_msg_handler_t *mh);
 
+ void flux_msg_handler_allow_rolemask (flux_msg_handler_t *w,
+                                       uint32_t rolemask);
+
+ void flux_msg_handler_deny_rolemask (flux_msg_handler_t *w,
+                                      uint32_t rolemask);
+
 
 DESCRIPTION
 -----------
@@ -59,6 +67,34 @@ are automatically sent an ENOSYS response by the dispatcher.
 stopping it.
 
 
+SECURITY
+--------
+
+As described in RFC 12, Flux connectors authenticate each broker
+connection, mapping it to a Flux userid and set of "roles" allocated
+to that user.  This userid and rolemask is stamped on all messages
+originating from the connection.
+
+A message handler only receives a message if a bit-wise and of the message
+rolemask and the message handler rolemask evaluates to a non-zero value,
+or the message rolemask contains the FLUX_ROLE_OWNER (instance owner) role.
+
+By default, the message handler rolemask is 0, but may be changed with
+`flux_msg_handler_allow_rolemask()` and `flux_msg_handler_deny_rolemask()`,
+which add or remove roles from the message handler rolemask.  The
+FLUX_ROLE_OWNER bit position is ignored in the message handler rolemask.
+
+The following roles are defined in RFC 12:
+
+FLUX_ROLE_OWNER::
+The instance owner role has maximum privilege within the Flux instance.
+
+FLUX_ROLE_USER::
+The user role confers access, but not administrative privilege.
+
+Other roles are yet to be defined.
+
+
 CAVEATS
 -------
 
@@ -103,3 +139,5 @@ include::COPYRIGHT.adoc[]
 SEE ALSO
 ---------
 flux_get_reactor(3), flux_reactor_start(3), flux_msg_cmp(3)
+
+https://github.com/flux-framework/rfc/blob/master/spec_6.adoc[RFC 12: Flux Security Architecture]