[PATCH] libselinux: update man pages for userspace policy enforcers

[Stephen Smalley <sds@tycho.nsa.gov>]

Despite deprecating use of flask.h and av_permissions.h back in 2014,
the man pages for avc_has_perm(3) and security_compute_av(3) were not
updated to provide instructions on how to dynamically map class/permission
names nor to encourage use of selinux_check_access(3) instead of these
interfaces.  Also, while selinux_set_mapping(3) supports dynamic
class/perm mapping at initialization, it does not support changes to
the class/perm values at runtime upon a policy reload, and no
instructions were provided on how to set up a callback to support
this case.  Update the man pages accordingly.

Signed-off-by: Stephen Smalley <sds@tycho.nsa.gov>
---
 libselinux/man/man3/avc_has_perm.3        | 37 +++++++++++++++++-
 libselinux/man/man3/security_compute_av.3 | 47 +++++++++++++++++++++--
 libselinux/man/man3/selinux_set_mapping.3 | 20 ++++++++--
 3 files changed, 97 insertions(+), 7 deletions(-)

diff --git a/libselinux/man/man3/avc_has_perm.3 b/libselinux/man/man3/avc_has_perm.3
index 3e9fca8475f1..62809f9af47f 100644
--- a/libselinux/man/man3/avc_has_perm.3
+++ b/libselinux/man/man3/avc_has_perm.3
@@ -34,6 +34,36 @@ avc_has_perm, avc_has_perm_noaudit, avc_audit, avc_entry_ref_init \- obtain and
 .in
 .
 .SH "DESCRIPTION"
+
+Direct use of these functions is generally discouraged in favor of
+the higher level interface
+.BR selinux_check_access(3)
+since the latter automatically handles the dynamic mapping of class
+and permission names to their policy values and proper handling of
+allow_unknown.
+
+When using any of the functions that take policy integer values for
+classes or permissions as inputs, use
+.BR string_to_security_class(3)
+and
+.BR string_to_av_perm(3)
+to map the class and permission names to their policy values.
+These values may change across a policy reload, so they should be
+re-acquired on every use or using a
+.B SELINUX_CB_POLICYLOAD
+callback set via
+.BR selinux_set_callback(3).
+
+An alternative approach is to use
+.BR selinux_set_mapping(3)
+to create a mapping from class and permission index values
+used by the application to the policy values,
+thereby allowing the application to pass its own
+fixed constants for the classes and permissions to
+these functions and internally mapping them on demand.
+However, this also requires setting up a callback as above
+to address policy reloads.
+
 .BR avc_entry_ref_init ()
 initializes an
 .B avc_entry_ref
@@ -146,11 +176,16 @@ Make sure that userspace object managers are granted appropriate access to
 netlink by the policy.
 .
 .SH "AUTHOR"
-Eamon Walsh <ewalsh@tycho.nsa.gov>
+Originally Eamon Walsh.  Updated by Stephen Smalley <sds@tycho.nsa.gov>
 .
 .SH "SEE ALSO"
 .ad l
 .nh
+.BR selinux_check_access(3),
+.BR string_to_security_class(3),
+.BR string_to_av_perm(3),
+.BR selinux_set_callback(3),
+.BR selinux_set_mapping(3),
 .BR avc_init (3),
 .BR avc_context_to_sid (3),
 .BR avc_cache_stats (3),
diff --git a/libselinux/man/man3/security_compute_av.3 b/libselinux/man/man3/security_compute_av.3
index cb1a9ba49f46..3de1b0fe7f1b 100644
--- a/libselinux/man/man3/security_compute_av.3
+++ b/libselinux/man/man3/security_compute_av.3
@@ -50,6 +50,39 @@ the SELinux policy database in the kernel
 .BI "int checkPasswdAccess(access_vector_t " requested );
 .
 .SH "DESCRIPTION"
+
+This family of functions is used to obtain policy decisions from the
+SELinux kernel security server (policy engine).  In general, direct use of
+.BR security_compute_av ()
+and its variant interfaces is discouraged in favor of using
+.BR selinux_check_access ()
+since the latter automatically handles the dynamic mapping of class
+and permission names to their policy values, initialization and use of
+the Access Vector Cache (AVC), and proper handling of per-domain and
+global permissive mode and allow_unknown.
+
+When using any of the functions that take policy integer values for
+classes or permissions as inputs, use
+.BR string_to_security_class(3)
+and
+.BR string_to_av_perm(3)
+to map the class and permission names to their policy values.
+These values may change across a policy reload, so they should be
+re-acquired on every use or using a
+.B SELINUX_CB_POLICYLOAD
+callback set via
+.BR selinux_set_callback(3).
+
+An alternative approach is to use
+.BR selinux_set_mapping(3)
+to create a mapping from class and permission index values
+used by the application to the policy values,
+thereby allowing the application to pass its own
+fixed constants for the classes and permissions to
+these functions and internally mapping them on demand.
+However, this also requires setting up a callback as above
+to address policy reloads.
+
 .BR security_compute_av ()
 queries whether the policy permits the source context
 .I scon
@@ -102,7 +135,7 @@ instance.
 .BR security_compute_user ()
 is used to determine the set of user contexts that can be reached from a
 source context. It is mainly used by
-.BR get_ordered_context_list ().
+.BR get_ordered_context_list (3).
 
 .BR security_validatetrans ()
 is used to determine if a transition from scon to newcon using tcon as the object
@@ -135,7 +168,9 @@ is used to check for a permission in the
 .I passwd
 class.
 .BR selinux_check_passwd_access ()
-uses getprevcon() for the source and target security contexts.
+uses
+.BR getprevcon(3)
+for the source and target security contexts.
 
 .BR checkPasswdAccess ()
 is a deprecated alias of the
@@ -146,4 +181,10 @@ function.
 Returns zero on success or \-1 on error.
 .
 .SH "SEE ALSO"
-.BR selinux "(8), " getcon "(3), " getfilecon "(3), " get_ordered_context_list "(3)"
+.BR string_to_security_class (3),
+.BR string_to_av_perm (3),
+.BR selinux_set_callback (3),
+.BR selinux_set_mapping (3),
+.BR getprevcon (3),
+.BR get_ordered_context_list (3),
+.BR selinux (8)
diff --git a/libselinux/man/man3/selinux_set_mapping.3 b/libselinux/man/man3/selinux_set_mapping.3
index a93f7b29497a..4624fbc7918a 100644
--- a/libselinux/man/man3/selinux_set_mapping.3
+++ b/libselinux/man/man3/selinux_set_mapping.3
@@ -19,7 +19,19 @@ struct security_class_mapping {
 .
 .SH "DESCRIPTION"
 .BR selinux_set_mapping ()
-establishes a mapping from a user-provided ordering of object classes and permissions to the numbers actually used by the loaded system policy.  Use of this function is highly preferred over the generated constants in the libselinux header files, as this method allows the policy's class and permission values to change over time.
+establishes a mapping from a user-provided ordering of object classes and permissions to the numbers actually used by the loaded system policy. If using this function, applications should also set a
+.B SELINUX_CB_POLICYLOAD
+callback via
+.BR selinux_set_callback(3)
+that calls this function again upon a policy reload to re-create the mapping
+in case the class or permission values change in the new policy.
+Generally it is preferred to instead use
+.BR selinux_check_access(3)
+instead of
+.BR avc_has_perm(3)
+or
+.BR security_compute_av(3)
+and not use this function at all.
 
 After the mapping is established, all libselinux functions that operate on class and permission values take the user-provided numbers, which are determined as follows:
 
@@ -81,8 +93,10 @@ and
 class) will be identified by 1, 2, 4, and 8 respectively.  Classes and permissions not listed in the mapping cannot be used.
 .
 .SH "AUTHOR"
-Eamon Walsh <ewalsh@tycho.nsa.gov>
+Originally Eamon Walsh.  Updated by Stephen Smalley <sds@tycho.nsa.gov>
 .
 .SH "SEE ALSO"
-.BR avc_open (8),
+.BR selinux_check_access (3),
+.BR selinux_set_callback (3),
+.BR avc_has_perm (3),
 .BR selinux (8)
-- 
2.24.1