Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add message security policy functions to man page #1285

Closed
wants to merge 3 commits into from
Closed

doc: add message security policy functions to man page #1285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
009b7ea
doc/flux_msg_handler_create(3): add rolemask funcs
garlick Nov 7, 2017
021324c
doc/flux_msg_handler_addvec(3): add security section
garlick Nov 7, 2017
d00050a
doc/flux_msg_handler_create(3): define more roles
garlick Nov 13, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions doc/man3/Makefile.am
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -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
Expand Down
11 changes: 11 additions & 0 deletions doc/man3/flux_msg_handler_addvec.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,17 @@ handler, all previously created message handlers in the array are destroyed
before an error is returned.


SECURITY
--------

The _rolemask_ member of _struct flux_msg_handler_spec_ is passed
to `flux_msg_handler_allow_rolemask()`. If no additional roles besides the
instance owner are to be allowed, set _rolemask_ to zero.

See the SECURITY section of `flux_msg_handler_create(3)` for a description
of message handler security.


RETURN VALUE
------------

Expand Down
49 changes: 48 additions & 1 deletion doc/man3/flux_msg_handler_create.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both of these functions really need a clear explanation of how they work. It is a little unual, I think, to have a function that or's the supplied mask rather than just setting the mask, and another that and's the inverse of the supplied mask. I think simple "set" and "get" mask functions would have been better. But since this is what we have, we should document what they do.

uint32_t rolemask);

void flux_msg_handler_deny_rolemask (flux_msg_handler_t *w,
uint32_t rolemask);


DESCRIPTION
-----------
Expand Down Expand Up @@ -59,6 +67,43 @@ 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 roles may be added
to the existing message handler rolemask with
`flux_msg_handler_allow_rolemask()` or removed from it with
`flux_msg_handler_deny_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.

In addition, RFC 12 defines these symbolic rolemask values:

FLUX_ROLE_NONE::
The empty set.

FLUX_ROLE_ALL::
The set of all possible roles.

Other roles are yet to be defined.


CAVEATS
-------

Expand Down Expand Up @@ -103,3 +148,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]