PERFORCE change 79401 for review

[Andrew Reisse]

http://perforce.freebsd.org/chv.cgi?CH=79401

Change 79401 by areisse at areisse_ibook on 2005/07/01 19:34:35

	Better documentation in security.defs. It is now in the same format
	as mac_policy.h (will be), and covers all functions.

Affected files ...

.. //depot/projects/trustedbsd/sedarwin7/src/darwin/xnu/osfmk/mach/security.defs#4 edit

Differences ...

==== //depot/projects/trustedbsd/sedarwin7/src/darwin/xnu/osfmk/mach/security.defs#4 (text+ko) ====

@@ -12,34 +12,97 @@
 
 type labelstr_t = c_string[*:512];
 
+/**
+  @brief Retrieve a task label in textual form
+  @param task Target's task port
+  @param policies Comma-delimited list of policies to query
+  @param label Returned label text
+
+  This call retrieves an externalized task label for the
+  specified task, with respect to the specified policies.
+
+  @return Standard MiG return values (0 for success)
+*/
+
 routine mach_get_task_label_text(task      : task_t;
 				 policies  : labelstr_t;
 				 out label : labelstr_t);
 
-/* also works on label handles */
+/**
+  @brief Retrieve a port label in textual form
+  @param task Issuer's task port
+  @param name Port to query label from
+  @param policies Comma-delimited list of policies to query
+  @param label Returned label text
+
+  This call retrieves an externalized port label for the specified port,
+  with respect to the specified policies. If the port represents a label
+  handle, the returned label text refers to the stored label and not the
+  access control label.
+
+  @return Standard MiG return values (0 for success)
+*/
 
 routine mach_get_label_text(task      : ipc_space_t;
 			    name      : mach_port_name_t;
 			    policies  : labelstr_t;
 			    out label : labelstr_t);
 
-/*
- * Relabel a port. This does not alter the user label data in a label
- * handle, but changes the label that is used for access control on the
- * port itself. That label cannot be retrieved (with the current interfaces).
- */
+/**
+  @brief Relabel a port
+  @param task Task containing specified ports
+  @param name Port to relabel
+  @param label String representation of new label
+
+  This call attempts to relabel the specified port to the
+  label specified. For label handles, it changes the access control
+  label and not the stored label.
+
+  @return Standard MiG return values (0 for success)
+*/
 
 routine mach_set_port_label(task      : ipc_space_t;
 			    name      : mach_port_name_t;
 			    label     : labelstr_t);
 
+/**
+  @brief Generic access control check
+  @param task Any task port
+  @param subj subject label in textual form
+  @param obj object label in textual form
+  @param serv Service or object class name
+  @param perm Permission, or method, within the specified service
+
+  This function provides a general way for a user process to query
+  an arbitrary access control decision from the system's security policies.
+  Currently, there are no standards for the format of the service and
+  permission names. 
+
+  @return Standard MiG return values (0 for success)
+*/
+
 routine mac_check_named_access(task    : ipc_space_t;
 			       subject : labelstr_t;
 			       object  : labelstr_t;
 			       service : labelstr_t;
 			       perm    : labelstr_t);
 
-/* Uses a string for the subject and a port for the object. */
+/**
+  @brief Generic access control check
+  @param task Task containing specified ports (usually caller's)
+  @param subj subject label in textual form
+  @param obj port containing object label
+  @param serv Service or object class name
+  @param perm Permission, or method, within the specified service
+
+  This function provides a general way for a user process to query
+  an arbitrary access control decision from the system's security policies.
+  Currently, there are no standards for the format of the service and
+  permission names. If the port is a label handle, the stored label is
+  used. Otherwise, its access control label is used.
+
+  @return Standard MiG return values (0 for success)
+*/
 
 routine mac_check_name_port_access(task    : ipc_space_t;
 				   subject : labelstr_t;
@@ -47,7 +110,22 @@
 				   service : labelstr_t;
 				   perm    : labelstr_t);
 
-/* Uses ports (or label handles) for both subject and object. */
+/**
+  @brief Generic access control check
+  @param task Task containing specified ports (usually caller's)
+  @param subj port containing subject label
+  @param obj port containing object label
+  @param serv Service or object class name
+  @param perm Permission, or method, within the specified service
+
+  This function provides a general way for a user process to query
+  an arbitrary access control decision from the system's security policies.
+  Currently, there are no standards for the format of the service and
+  permission names. If any ports are label handles, the stored label is
+  used. Otherwise, the access control labels are used.
+
+  @return Standard MiG return values (0 for success)
+*/
 
 routine mac_check_port_access(task    : ipc_space_t;
 			      subject : mach_port_name_t;
@@ -55,10 +133,44 @@
 			      service : labelstr_t;
 			      perm    : labelstr_t);
 
+/**
+  @brief Create a new label handle
+  @param task Task to receive new ports (usually caller's)
+  @param name Returned label handle port
+  @param label String representation of new label
+
+  Creates a new label handle, with the stored label defined by the
+  given text. Any task may create a label handle with any valid label,
+  not necessarily one that it has permission to access. A port right
+  for the new label handle is inserted into the specified task.
+  Posession of label handles should not imply any security properties.
+
+  @return Standard MiG return values (0 for success)
+*/
+
 routine mac_label_new(task     : ipc_space_t;
 		      out name : mach_port_name_t;
 		      label    : labelstr_t);
 
+/**
+  @brief Request a computed label
+  @param task subj,obj,newlabel relative to this task (usually caller's)
+  @param subj port containing subject label
+  @param obj port containing object label
+  @param serv Service or object class name
+  @param newlabel Returned label handle port
+  
+  Ask the loaded policies to compute a label based on the two input labels
+  and the service name. There is currently no standard for the service name,
+  or even what the input labels represent (Subject and parent object are only
+  a suggestion). If any ports are label handles, the stored label is
+  used. Otherwise, the access control labels are used. A new label handle
+  is created to contain the computed label, and is stored into the
+  specified task.
+
+  @return Standard MiG return values (0 for success)
+*/
+
 routine mac_request_label(task         : ipc_space_t;
 			  subject      : mach_port_name_t;
 			  object       : mach_port_name_t;
To Unsubscribe: send mail to majordomo at trustedbsd.org
with "unsubscribe trustedbsd-cvs" in the body of the message