dynamic security class and access vector lookup

I wasn't aware until yesterday that there was an API for looking up security classes (selinux_set_mapping, the name of which doesn't strike me as very intuitive). Can I also lookup the access vectors for a class, if so how?

Quoted 4 lines · Xavier Toth

I wasn't aware until yesterday that there was an API for looking up security classes (selinux_set_mapping, the name of which doesn't strike me as very intuitive). Can I also lookup the access vectors for a class, if so how?

selinux_set_mapping() does that too. dynamic discovery of classes and permissions was discussed quite a bit on list. XSELinux uses it, and so does SE-Postgres.

--
Stephen Smalley
National Security Agency

Quoted 7 lines · Stephen Smalley

Quoted 4 lines · Xavier Toth

I wasn't aware until yesterday that there was an API for looking up security classes (selinux_set_mapping, the name of which doesn't strike me as very intuitive). Can I also lookup the access vectors for a class, if so how?

Quoted 9 lines

selinux_set_mapping() does that too. dynamic discovery of classes and permissions was discussed quite a bit on list. XSELinux uses it, and so does SE-Postgres.

--
Stephen Smalley
National Security Agency

I see the posting of the patch but no discussion. Yesterday Eamon posted an example of setting the mapping of a security class but it didn't address perms. I have some python code where I'm calling selinux.avc_has_perm_noaudit and have been using hard coded values for the security class and perm. I'd like to fix this code but am not sure if this or some other capability I'm unaware of will do the trick.

Quoted 18 lines · Xavier Toth

Quoted 7 lines · Stephen Smalley

Quoted 4 lines · Xavier Toth

I wasn't aware until yesterday that there was an API for looking up security classes (selinux_set_mapping, the name of which doesn't strike me as very intuitive). Can I also lookup the access vectors for a class, if so how?

Quoted 9 lines

selinux_set_mapping() does that too. dynamic discovery of classes and permissions was discussed quite a bit on list. XSELinux uses it, and so does SE-Postgres.

--
Stephen Smalley
National Security Agency

Quoted 6 lines

I see the posting of the patch but no discussion. Yesterday Eamon posted an example of setting the mapping of a security class but it didn't address perms. I have some python code where I'm calling selinux.avc_has_perm_noaudit and have been using hard coded values for the security class and perm. I'd like to fix this code but am not sure if this or some other capability I'm unaware of will do the trick.

See:
http://marc.info/?l=selinux&m=118114723416269&w=2

Then your code can use your own set of private definitions for class and permission values that are just indices starting from 1, and the libselinux avc will map them to the kernel/policy values automatically.

New and updated man pages for AVC, mapping, label.

Includes avc_open() call, deprecated avc_init(), selinux_set_mapping(), and new options to the selabel X backend.

Index: libselinux/man/man3/avc_open.3
===================================================================

man/man3/avc_open.3 +15 -0

@@ -0,0 +1,70 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "avc_open" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+avc_open, avc_destroy, avc_reset, avc_cleanup \- userspace SELinux AVC setup and teardown.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+
+.B #include <selinux/avc.h>
+.sp
+.BI "int avc_open(struct selinux_opt *" options ", unsigned " nopt ");"
+.sp
+.BI "void avc_destroy(void);"
+.sp

Index: libselinux/man/man3/selinux_set_mapping.3
===================================================================

man/man3/selinux_set_mapping.3 +69 -0

@@ -0,0 +1,86 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "selinux_set_mapping" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+selinux_set_mapping \- establish dynamic object class and permission mapping.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.nf
+struct security_class_mapping {
+	const char *name;
+	const char *perms[];
+};
+.fi
+.sp
+.BI "int selinux_set_mapping(struct security_class_mapping *" map ");"
+
+.SH "DESCRIPTION"
+.B 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.
+
+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:
+
+The
+.I map
+argument consists of an array of 
+.B security_class_mapping
+structures, which must be terminated by a structure having a NULL name field.  Except for this last structure, the
+.I name 
+field should refer to the string name of an object class, and the corresponding
+.I perms
+field should refer to an array of permission bit names terminated by a NULL string.
+
+The object classes named in the mapping and each set of permission bits are numbered in order starting from 1.  These numbers are the values that should be passed to subsequent libselinux calls.
+
+.SH "RETURN VALUE"
+Zero is returned on success.  On error, -1 is returned and
+.I errno
+is set appropriately.
+
+.SH "ERRORS"
+.TP
+.B EINVAL
+One of the class or permission names requested in the mapping is not present in the loaded policy.
+.TP
+.B ENOMEM
+An attempt to allocate memory failed.
+
+.SH "EXAMPLE"
+.RS
+.ta 4n 10n
+.nf
+struct security_class_mapping map[] = {
+	{ "file", { "create", "rename", "unlink", NULL } },
+	{ "socket", { "bind", NULL } },
+	{ "process", { "signal", NULL } },
+	{ NULL }
+};
+
+if (selinux_set_mapping(map) < 0)
+	exit(1);
+.fi
+.ta
+.RE
+
+In this example, after the call has succeeded, classes
+.BR file ,
+.BR socket ,

Quoted 4 lines · Eamon Walsh

New and updated man pages for AVC, mapping, label.

Includes avc_open() call, deprecated avc_init(), selinux_set_mapping(), and new options to the selabel X backend.

Thanks for writing these. A few minor comments below.

Quoted 20 lines

Index: libselinux/man/man3/avc_open.3
===================================================================

man/man3/avc_open.3 +15 -0

@@ -0,0 +1,70 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "avc_open" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+avc_open, avc_destroy, avc_reset, avc_cleanup \- userspace SELinux AVC setup and teardown.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+
+.B #include <selinux/avc.h>
+.sp
+.BI "int avc_open(struct selinux_opt *" options ", unsigned " nopt ");"
+.sp
+.BI "void avc_destroy(void);"
+.sp

man/man3/avc_open.3 line 25

Quoted 10 lines

man/man3/avc_open.3 +10 -0

+.BI "int avc_reset(void);"
+.sp
+.BI "void avc_cleanup(void);"
+.SH "DESCRIPTION"
+.B avc_open
+initializes the userspace AVC and must be called before any other AVC operation can be performed.
+
+.B avc_destroy
+destroys the userspace AVC, freeing all internal memory structures.  After this call has been made, 
+.B avc_init

s/avc_init/avc_open/

Quoted 79 lines

Index: libselinux/man/man3/selinux_set_mapping.3
===================================================================

man/man3/selinux_set_mapping.3 +74 -0

@@ -0,0 +1,86 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "selinux_set_mapping" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+selinux_set_mapping \- establish dynamic object class and permission mapping.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.nf
+struct security_class_mapping {
+	const char *name;
+	const char *perms[];
+};
+.fi
+.sp
+.BI "int selinux_set_mapping(struct security_class_mapping *" map ");"
+
+.SH "DESCRIPTION"
+.B 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.
+
+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:
+
+The
+.I map
+argument consists of an array of 
+.B security_class_mapping
+structures, which must be terminated by a structure having a NULL name field.  Except for this last structure, the
+.I name 
+field should refer to the string name of an object class, and the corresponding
+.I perms
+field should refer to an array of permission bit names terminated by a NULL string.
+
+The object classes named in the mapping and each set of permission bits are numbered in order starting from 1.  These numbers are the values that should be passed to subsequent libselinux calls.
+
+.SH "RETURN VALUE"
+Zero is returned on success.  On error, -1 is returned and
+.I errno
+is set appropriately.
+
+.SH "ERRORS"
+.TP
+.B EINVAL
+One of the class or permission names requested in the mapping is not present in the loaded policy.
+.TP
+.B ENOMEM
+An attempt to allocate memory failed.
+
+.SH "EXAMPLE"
+.RS
+.ta 4n 10n
+.nf
+struct security_class_mapping map[] = {
+	{ "file", { "create", "rename", "unlink", NULL } },
+	{ "socket", { "bind", NULL } },
+	{ "process", { "signal", NULL } },
+	{ NULL }
+};
+
+if (selinux_set_mapping(map) < 0)
+	exit(1);
+.fi
+.ta
+.RE
+
+In this example, after the call has succeeded, classes
+.BR file ,
+.BR socket ,
+and
+.B process
+will be identified by 1, 2 and 3, respectively.  Permissions
+.IR create ,
+.IR rename ,

man/man3/selinux_set_mapping.3 line 76

Quoted 5 lines

man/man3/selinux_set_mapping.3 +5 -0

+and
+.I unlink
+(for the 
+.B file
+class) will be identified by 1, 2, and 4, respectively.  Classes and permissions not listed in the mapping cannot be used.

To be clear, the permissions are identified by bits 1, 2, and 4, but their actual values as access vectors are 1 << (bit - 1).

As a separate matter, we may want to discuss whether we are getting the flexibility we hoped from this dynamic mapping. The other day I was adding a new kernel class for experimentation purposes and inserted it before the new X classes, thinking that this would be ok since they can be dynamically looked up and thus don't require fixed indices. However, when booting the resulting kernel with a stock policy, I found that the kernel refused to load the policy because it saw a conflict between its kernel definition for that class value (the new kernel class) and the policy definition for that class value (the X class). Which would mean that new kernels on legacy distros would break.

One other question I have is what we should do about the flask.h definitions and string tables in libselinux. We obviously need to retain the legacy definitions for old userspace object managers, but we also have the old X definitions there and the db definitions. make LIBSELINUX_D=/path/to/libselinux tolib from refpolicy/policy/flask will install updated headers and string tables with the latest definitions but do we want them all now or just the legacy ones?

I suppose partly that depends on whether we want to use newer object managers on older kernels that don't support the dynamic class/perm discovery mechanism.

Quoted 12 lines

As a separate matter, we may want to discuss whether we are getting the flexibility we hoped from this dynamic mapping. The other day I was adding a new kernel class for experimentation purposes and inserted it before the new X classes, thinking that this would be ok since they can be dynamically looked up and thus don't require fixed indices. However, when booting the resulting kernel with a stock policy, I found that the kernel refused to load the policy because it saw a conflict between its kernel definition for that class value (the new kernel class) and the policy definition for that class value (the X class). Which would mean that new kernels on legacy distros would break.

Stephen Smalley wrote:

[snip]

Quoted 8 lines

One other question I have is what we should do about the flask.h definitions and string tables in libselinux. We obviously need to retain the legacy definitions for old userspace object managers, but we also have the old X definitions there and the db definitions. make LIBSELINUX_D=/path/to/libselinux tolib from refpolicy/policy/flask will install updated headers and string tables with the latest definitions but do we want them all now or just the legacy ones?

I think we need to start removing the userspace classes, starting with the DB and X ones. Even for the legacy object managers, removing the definitions won't break any binaries, just the source code compiling.

Quoted 4 lines

I suppose partly that depends on whether we want to use newer object managers on older kernels that don't support the dynamic class/perm discovery mechanism.

I would argue no, given that X at least depends a lot on new kernel features.

Quoted 12 lines

Quoted 12 lines

As a separate matter, we may want to discuss whether we are getting the flexibility we hoped from this dynamic mapping. The other day I was adding a new kernel class for experimentation purposes and inserted it before the new X classes, thinking that this would be ok since they can be dynamically looked up and thus don't require fixed indices. However, when booting the resulting kernel with a stock policy, I found that the kernel refused to load the policy because it saw a conflict between its kernel definition for that class value (the new kernel class) and the policy definition for that class value (the X class). Which would mean that new kernels on legacy distros would break.

Well I think the kernel needs to grow its own mapping support then.

Quoted 4 lines · Eamon Walsh

New and updated man pages for AVC, mapping, label.

Includes avc_open() call, deprecated avc_init(), selinux_set_mapping(), and new options to the selabel X backend.

Quoted 4 lines · Stephen Smalley

Quoted 2 lines · Eamon Walsh

New and updated man pages for AVC, mapping, label.

Quoted 3 lines

Quoted 3 lines

Includes avc_open() call, deprecated avc_init(), selinux_set_mapping(), and new options to the selabel X backend.

Revised per comments.

Signed-off-by Eamon Walsh <[email protected]>

---

 man3/avc_cleanup.3         |    2 -
 man3/avc_destroy.3         |    2 -
 man3/avc_init.3            |   40 +++++---------------
 man3/avc_open.3            |   70 ++++++++++++++++++++++++++++++++++++
 man3/avc_reset.3           |    2 -
 man3/selinux_set_mapping.3 |   87 +++++++++++++++++++++++++++++++++++++++++++++
 man5/selabel_x.5           |   27 +++++++++++++
 7 files changed, 198 insertions(+), 32 deletions(-)

Index: libselinux/man/man3/avc_destroy.3
===================================================================

man/man3/avc_destroy.3 +1 -1

@@ -1 +1 @@
-.so man3/avc_init.3
+.so man3/avc_open.3

Index: libselinux/man/man3/avc_open.3
===================================================================

man/man3/avc_open.3 +70 -0

@@ -0,0 +1,70 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "avc_open" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+avc_open, avc_destroy, avc_reset, avc_cleanup \- userspace SELinux AVC setup and teardown.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+
+.B #include <selinux/avc.h>
+.sp
+.BI "int avc_open(struct selinux_opt *" options ", unsigned " nopt ");"
+.sp
+.BI "void avc_destroy(void);"
+.sp
+.BI "int avc_reset(void);"
+.sp
+.BI "void avc_cleanup(void);"
+.SH "DESCRIPTION"
+.B avc_open
+initializes the userspace AVC and must be called before any other AVC operation can be performed.
+
+.B avc_destroy
+destroys the userspace AVC, freeing all internal memory structures.  After this call has been made, 
+.B avc_open
+must be called again before any AVC operations can be performed.
+
+.B avc_reset
+flushes the userspace AVC, causing it to forget any cached access decisions.  The userspace AVC normally calls this function automatically when needed, see
+.B NETLINK NOTIFICATION
+below.
+
+.B avc_cleanup
+forces the userspace AVC to search for and free all unused SID's and any access decision entries that refer to them.  Normally, the userspace AVC lazily reclaims unused SID's.  
+
+.SH "OPTIONS"
+The userspace AVC obeys callbacks set via
+.BR selinux_set_callback (3),
+in particular the logging and audit callbacks.
+
+The options which may be passed to
+.B avc_open
+include the following:
+
+.TP
+.B AVC_OPT_SETENFORCE
+This option forces the userspace AVC into enforcing mode if the option value is non-NULL; permissive mode otherwise.  The system enforcing mode will be ignored.
+
+.SH "NETLINK NOTIFICATION"
+Beginning with version 2.6.4, the Linux kernel supports SELinux status change notification via netlink.  Two message types are currently implemented, indicating changes to the enforcing mode and to the loaded policy in the kernel, respectively.  The userspace AVC listens for these messages and takes the appropriate action, modifying the behavior of
+.BR avc_has_perm (3)
+to reflect the current enforcing mode and flushing the cache on receipt of a policy load notification.  Audit messages are produced when netlink notifications are processed.
+
+.SH "RETURN VALUE"
+Functions with a return value return zero on success.  On error, \-1 is returned and
+.I errno
+is set appropriately.
+
+.SH "AUTHOR"
+Eamon Walsh <[email protected]>
+
+.SH "SEE ALSO"
+.BR selinux (8),
+.BR avc_has_perm (3),
+.BR avc_context_to_sid (3),
+.BR avc_cache_stats (3),
+.BR avc_add_callback (3),
+.BR selinux_set_callback (3),
+.BR security_compute_av (3)
+

Index: libselinux/man/man3/avc_cleanup.3
===================================================================

man/man3/avc_cleanup.3 +1 -1

@@ -1 +1 @@
-.so man3/avc_init.3
+.so man3/avc_open.3

Index: libselinux/man/man3/avc_init.3
===================================================================

man/man3/avc_init.3 +11 -29

@@ -3,7 +3,7 @@
 .\" Author: Eamon Walsh ([email protected]) 2004
 .TH "avc_init" "3" "27 May 2004" "" "SELinux API documentation"
 .SH "NAME"
-avc_init, avc_destroy, avc_reset, avc_cleanup \- userspace SELinux AVC setup and teardown.
+avc_init - legacy userspace SELinux AVC setup.
 .SH "SYNOPSIS"
 .B #include <selinux/selinux.h>
 

@@ -18,34 +18,19 @@
 .BI "const struct avc_thread_callback *" thread_callbacks ,
 
 .BI "const struct avc_lock_callback *" lock_callbacks ");"
-.in
-.sp
-.BI "void avc_destroy(void);"
-.sp
-.BI "int avc_reset(void);"
-.sp
-.BI "void avc_cleanup(void);"
 .SH "DESCRIPTION"
 .B avc_init
+is deprecated; please use
+.BR avc_open (3)
+in conjunction with
+.BR selinux_set_callback (3)
+in all new code.
+
+.B avc_init
 initializes the userspace AVC and must be called before any other AVC operation can be performed.  A non-NULL
 .I msgprefix
-will be prepended to all audit messages produced by the userspace AVC.  The default is `uavc'.  The remaining arguments, if non-NULL, specify callbacks to be used by the userspace AVC.  See 
-.B CALLBACKS
-below.
+will be prepended to all audit messages produced by the userspace AVC.  The default is `uavc'.  The remaining arguments, if non-NULL, specify callbacks to be used by the userspace AVC.
 
-.B avc_destroy
-destroys the userspace AVC, freeing all internal memory structures.  After this call has been made, 
-.B avc_init
-must be called again before any AVC operations can be performed.
-
-.B avc_reset
-flushes the userspace AVC, causing it to forget any cached access decisions.  The userspace AVC normally calls this function automatically when needed, see
-.B NETLINK NOTIFICATION
-below.
-
-.B avc_cleanup
-forces the userspace AVC to search for and free all unused SID's and any access decision entries that refer to them.  Normally, the userspace AVC lazily reclaims unused SID's.  
-
 .SH "CALLBACKS"
 The userspace AVC can be directed how to perform memory allocation, logging, thread creation, and locking via callback functions passed to
 .BR avc_init .

@@ -204,10 +189,7 @@
 Eamon Walsh <[email protected]>
 
 .SH "SEE ALSO"
-.BR avc_has_perm (3),
-.BR avc_context_to_sid (3),
-.BR avc_cache_stats (3),
-.BR avc_add_callback (3),
-.BR security_compute_av (3)
+.BR avc_open (3),
+.BR selinux_set_callback (3),
 .BR selinux (8)
 

Index: libselinux/man/man3/avc_reset.3
===================================================================

man/man3/avc_reset.3 +1 -1

@@ -1 +1 @@
-.so man3/avc_init.3
+.so man3/avc_open.3

Index: libselinux/man/man3/selinux_set_mapping.3
===================================================================

man/man3/selinux_set_mapping.3 +87 -0

@@ -0,0 +1,87 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Author: Eamon Walsh ([email protected]) 2008
+.TH "selinux_set_mapping" "3" "12 Jun 2008" "" "SELinux API documentation"
+.SH "NAME"
+selinux_set_mapping \- establish dynamic object class and permission mapping.
+.SH "SYNOPSIS"
+.B #include <selinux/selinux.h>
+.sp
+.nf
+struct security_class_mapping {
+	const char *name;
+	const char *perms[];
+};
+.fi
+.sp
+.BI "int selinux_set_mapping(struct security_class_mapping *" map ");"
+
+.SH "DESCRIPTION"
+.B 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.
+
+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:
+
+The
+.I map
+argument consists of an array of 
+.B security_class_mapping
+structures, which must be terminated by a structure having a NULL name field.  Except for this last structure, the
+.I name 
+field should refer to the string name of an object class, and the corresponding
+.I perms
+field should refer to an array of permission bit names terminated by a NULL string.
+
+The object classes named in the mapping and the bit indexes of each set of permission bits named in the mapping are numbered in order starting from 1.  These numbers are the values that should be passed to subsequent libselinux calls.
+
+.SH "RETURN VALUE"
+Zero is returned on success.  On error, -1 is returned and
+.I errno
+is set appropriately.
+
+.SH "ERRORS"
+.TP
+.B EINVAL
+One of the class or permission names requested in the mapping is not present in the loaded policy.
+.TP
+.B ENOMEM
+An attempt to allocate memory failed.
+
+.SH "EXAMPLE"
+.RS
+.ta 4n 10n
+.nf
+struct security_class_mapping map[] = {
+	{ "file", { "create", "unlink", "read", "write", NULL } },
+	{ "socket", { "bind", NULL } },
+	{ "process", { "signal", NULL } },
+	{ NULL }
+};
+
+if (selinux_set_mapping(map) < 0)
+	exit(1);
+.fi
+.ta
+.RE
+
+In this example, after the call has succeeded, classes
+.BR file ,
+.BR socket ,
+and
+.B process
+will be identified by 1, 2 and 3, respectively.  Permissions
+.IR create ,
+.IR unlink ,
+.IR read ,
+and
+.I write
+(for the 
+.B file
+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 <[email protected]>
+
+.SH "SEE ALSO"
+.BR avc_open (8),
+.BR selinux (8)

Index: libselinux/man/man5/selabel_x.5
===================================================================

man/man5/selabel_x.5 +27 -0

@@ -27,15 +27,39 @@
 .I object_name
 argument specifies the name of a window property, such as "WM_NAME".
 .TP
+.B SELABEL_X_SELN
+The
+.I object_name
+argument specifies the name of a selection, such as "PRIMARY".
+.TP
 .B SELABEL_X_EXT
 The
 .I object_name
 argument specifies the name of a protocol extension, such as "RENDER".
 .TP
+.B SELABEL_X_EVENT
+The
+.I object_name
+argument specifies the name of an event type, such as "X11:ButtonPress".
+.TP
 .B SELABEL_X_CLIENT
 The
 .I object_name
 argument is ignored and should be set to NULL.  The default context for labeling remote X clients is returned.
+.TP
+.B SELABEL_X_POLYPROP
+Like
+.BR SELABEL_X_PROP ,
+but checks if the property was marked as being polyinstantiated.  See
+.B NOTES
+below.
+.TP
+.B SELABEL_X_POLYSELN
+Like
+.BR SELABEL_X_SELN ,
+but checks if the selection was marked as being polyinstantiated.  See
+.B NOTES
+below.
 
 .SH "OPTIONS"
 In addition to the global options described in 

@@ -46,6 +70,9 @@
 .B SELABEL_OPT_PATH
 A non-null value for this option specifies a path to a file that will be opened in lieu of the standard X contexts file.  
 
+.SH "NOTES"
+Properties and selections are marked as either polyinstantiated or not.  For these name types, the "POLY" option searches only the names marked as being polyinstantiated, while the other option searches only the names marked as not being polyinstantiated.  Users of the interface should check both mappings, optionally taking action based on the result (e.g. polyinstantiating the object).
+
 .SH "SEE ALSO"
 .BR selabel_open (3),
 .BR selabel_lookup (3),