From c7a33af0712116029c3874f5c91d300c48fadbb7 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Tue, 7 Nov 2017 13:05:44 -0800 Subject: [PATCH] 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 #1260 --- doc/man3/Makefile.am | 4 +++ doc/man3/flux_msg_handler_create.adoc | 40 ++++++++++++++++++++++++++- 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/doc/man3/Makefile.am b/doc/man3/Makefile.am index cfa1e9a61f42..7d6819098568 100644 --- a/doc/man3/Makefile.am +++ b/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 diff --git a/doc/man3/flux_msg_handler_create.adoc b/doc/man3/flux_msg_handler_create.adoc index 23d4bf43fbe5..590f1a196b44 100644 --- a/doc/man3/flux_msg_handler_create.adoc +++ b/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]