@@ -130,13 +130,29 @@ sepgsql_avc_reclaim(void)
130130}
131131}
132132
133- /*
133+ /* -------------------------------------------------------------------------
134+ *
134135 * sepgsql_avc_check_valid
135136 *
136- * It checks whether the cached entries are still valid, or not.
137- * If security policy has been reloaded since last reference of access
138- * vector cache, we have to release all the entries, because they are
139- * not valid yet.
137+ * This function checks whether the cached entries are still valid. If
138+ * the security policy has been reloaded (or any other events that requires
139+ * resetting userspace caches has occurred) since the last reference to
140+ * the access vector cache, we must flush the cache.
141+ *
142+ * Access control decisions must be atomic, but multiple system calls may
143+ * be required to make a decision; thus, when referencing the access vector
144+ * cache, we must loop until we complete without an intervening cache flush
145+ * event. In practice, looping even once should be very rare. Callers should
146+ * do something like this:
147+ *
148+ * sepgsql_avc_check_valid();
149+ * do {
150+ * :
151+ * <reference to uavc>
152+ * :
153+ * } while (!sepgsql_avc_check_valid())
154+ *
155+ * -------------------------------------------------------------------------
140156 */
141157static bool
142158sepgsql_avc_check_valid (void )
@@ -153,8 +169,8 @@ sepgsql_avc_check_valid(void)
153169/*
154170 * sepgsql_avc_unlabeled
155171 *
156- *It returns an alternative label to be applied when no label or invalid
157- * label would be assigned on objects .
172+ *Returns an alternative label to be applied when no label or an invalid
173+ * label wouldotherwise be assigned.
158174 */
159175static char *
160176sepgsql_avc_unlabeled (void )
@@ -221,9 +237,15 @@ sepgsql_avc_compute(const char *scontext, const char *tcontext, uint16 tclass)
221237sepgsql_compute_avd (scontext ,ucontext ,tclass ,& avd );
222238
223239/*
224- * To boost up trusted procedure checks on db_procedure object
225- * class, we also confirm the decision when user calls a procedure
226- * labeled as 'tcontext'.
240+ * It also caches a security label to be switched when a client
241+ * labeled as 'scontext' executes a procedure labeled as 'tcontext',
242+ * not only access control decision on the procedure.
243+ * The security label to be switched shall be computed uniquely on
244+ * a pair of 'scontext' and 'tcontext', thus, it is reasonable to
245+ * cache the new label on avc, and enables to reduce unnecessary
246+ * system calls.
247+ * It shall be referenced at sepgsql_needs_fmgr_hook to check whether
248+ * the supplied function is a trusted procedure, or not.
227249 */
228250if (tclass == SEPG_CLASS_DB_PROCEDURE )
229251{
@@ -278,9 +300,8 @@ sepgsql_avc_compute(const char *scontext, const char *tcontext, uint16 tclass)
278300/*
279301 * sepgsql_avc_lookup
280302 *
281- * It lookups a cache entry that matches with the supplied object
282- * identifiers and object class. If not found, it tries to create
283- * a new cache entry.
303+ * Look up a cache entry that matches the supplied security contexts and
304+ * object class. If not found, create a new cache entry.
284305 */
285306static avc_cache *
286307sepgsql_avc_lookup (const char * scontext ,const char * tcontext ,uint16 tclass )
@@ -338,8 +359,8 @@ sepgsql_avc_check_perms_label(const char *tcontext,
338359result = true;
339360
340361/*
341- * If target object is unlabeled, weassume it has
342- *system 'unlabeled' security context instead .
362+ * Ifthe target object is unlabeled, weperform the check using the
363+ *label supplied by sepgsql_avc_unlabeled() .
343364 */
344365if (tcontext )
345366cache = sepgsql_avc_lookup (scontext ,tcontext ,tclass );
@@ -362,10 +383,10 @@ sepgsql_avc_check_perms_label(const char *tcontext,
362383{
363384/*
364385 * In permissive mode or permissive domain, violated permissions
365- * shall be auditedon the log files at once, and implicitly
366- * allowedthem to avoid flood of access denied logs, because
367- * the purpose of permissive mode/domain is to collect violation
368- * log to fix up security policy itself .
386+ * shall be auditedto the log files at once, and then implicitly
387+ * allowed to avoid a flood of access denied logs, because
388+ * the purpose of permissive mode/domain is to collecta violation
389+ * logthat will make it possible to fix upthe security policy.
369390 */
370391if (!sepgsql_getenforce ()|| cache -> permissive )
371392cache -> allowed |=required ;
@@ -422,9 +443,9 @@ sepgsql_avc_check_perms(const ObjectAddress *tobject,
422443/*
423444 * sepgsql_avc_trusted_proc
424445 *
425- *It returns a security label to be switched on execution of the supplied
426- *procedure, if it was configured as a trusted procedure. Otherwise, NULL
427- *shall be returned .
446+ *If the supplied function OID is configured as a trusted procedure, this
447+ *function will return a security label to be used during the execution of
448+ *that function. Otherwise, it returns NULL .
428449 */
429450char *
430451sepgsql_avc_trusted_proc (Oid functionId )
@@ -455,7 +476,7 @@ sepgsql_avc_trusted_proc(Oid functionId)
455476/*
456477 * sepgsql_avc_exit
457478 *
458- *It clean up userspaceavc stuff on process exit
479+ *Clean up userspaceAVC on process exit.
459480 */
460481static void
461482sepgsql_avc_exit (int code ,Datum arg )
@@ -466,8 +487,7 @@ sepgsql_avc_exit(int code, Datum arg)
466487/*
467488 * sepgsql_avc_init
468489 *
469- * It shall be invoked at once from _PG_init routine to initialize
470- * userspace access vector cache stuff.
490+ * Initialize the userspace AVC. This should be called from _PG_init.
471491 */
472492void
473493sepgsql_avc_init (void )
@@ -504,8 +524,6 @@ sepgsql_avc_init(void)
504524ereport (LOG ,
505525(errmsg ("SELinux: kernel status page uses fallback mode" )));
506526
507- /*
508- * To close selinux status page on process exit
509- */
527+ /* Arrange to close selinux status page on process exit. */
510528on_proc_exit (sepgsql_avc_exit ,0 );
511529}