[apparmor] AppArmor APIs

[John Johansen]

On 12/14/2015 07:44 AM, Colin Ian King wrote:
> Hi there,
> 
> I'm looking at writing some stress tests for AppArmor, so I'd like to
> construct some simple rules and insert/remove them.  I looked for some
> API documentation, but all I can find is:
> 
> http://wiki.apparmor.net/index.php/AppArmorAPIs
> 
> Are there any API docs, guides or worked examples for libaaparse and
> libapparmor?
> 

Hey Colin,
sorry the interfaces aren't better documented. It is one of those perpetual
todo items. There is a quick view of the basic apis bellow and I'll work on
getting you some better docs

The libapparmor api, is fairly well documented in the man pages (though it
seems the cross refs to find them could stand to be updated)

  man aa_change_hat
      aa_change_hatv
      aa_change_hat_vargs

  man aa_change_profile
      aa_change_onexec

  man  aa_getprocattr_raw
       aa_getprocattr
       aa_gettaskcon
       aa_getcon
       aa_getpeercon_raw
       aa_getpeercon

  man aa_splitcon

  man aa_features
      aa_features_new
      aa_features_new_from_string
      aa_features_new_from_kernel
      aa_features_ref
      aa_features_unref
      aa_features_write_to_file
      aa_features_is_equal
      aa_features_supports

  man aa_is_enabled
      aa_find_mountpoint

  man aa_kernel_interface
      aa_kernel_interface_new
      aa_kernel_interface_ref
      aa_kernel_interface_unref
      aa_kernel_interface_load_policy
      aa_kernel_interface_load_policy_from_file
      aa_kernel_interface_load_policy_from_fd
      aa_kernel_interface_replace_policy
      aa_kernel_interface_replace_policy_from_file
      aa_kernel_interface_replace_policy_from_fd
      aa_kernel_interface_remove_policy
      aa_kernel_interface_write_policy

  man aa_policy_cache
      aa_policy_cache_new
      aa_policy_cache_ref
      aa_policy_cache_unref
      aa_policy_cache_remove
      aa_policy_cache_replace_all

  man aa_query_label
      aa_query_file_path
      aa_query_file_path_len
      aa_query_link_path_len
      aa_query_link_path



the logparsing doesn't seem to be documented at all :(
The 2 exported functions are
  aa_log_record *parse_record(char *str)
  void free_record(aa_log_record *record)

  with aa_log_record being defined in include/aalogparse.h
there are a fair number of log parsing tests in 
  libraries/libapparmor/testsuite/

there are a set of private functions that a pseudo exported but being private apis may change at any time
                _aa_is_blacklisted;
                _aa_autofree;
                _aa_autoclose;
                _aa_autofclose;
                _aa_dirat_for_each;



the apparmor_parser flags are fairly well documented in
  man apparmor_parser



the lowlevel interfaces are not well documented at all
  reading of a sockets label is done via
    getsockopt(fd, SOL_SOCKET, SO_PEERSEC, buf, &optlen);

  read of a tasks label is done via
    /proc/<pid>/attr/current

  read of a scheduled change at exec via
    /proc/<pid>/attr/exec

  read of parent while in a hat
    /proc/<pid>/attr/prev

  setting self label (another tasks label can not be directly set) is done by writing to
    /proc/<pid>/attr/current

  setting of self label at exec (again another tasks is not allow) is done via writing to
    /proc/<pid>/attr/exec

  the /proc/<pid>/attr/  fscreate  keycreate sockcreate files are currently not used

  the sock and proc/attr interface are limited to pagesize reads and writes atm



the apparmor filesystem used for loading and introspecting policy is usually mounted at
   /sys/kernel/security/apparmor.

Well its not really the apparmor filesystem anymore as it is a sub of the securityfs
filesystem.  Under this there is
  ls apparmor/
  .access  features  .load  .null  policy  profiles  .remove  .replace

.access - is a file that allows querying permissions. I'll work on getting you some docs
  on its format

profiles - flattened, virtualized view of what policy is visible to the inquiring task.
  I'll work on some better docs for you

features - dir of features supported by the kernel (should be read only)

policy - dir of policy currently visible (actually currently this is always from root
         policy ns, but ideally it should get virtualized (except doing that properly
         with the way the vfs is setup is impossible, so there will be something half
         assed for 16.04).

         This represents an expanded view of what is available in the profiles file,
         and is currently entirely read only.

         the hierarch is basically

         policy/namespaces/   #subnamespaces follow exactly same format as whats in policy
               /profiles/<swizzled profile name>.uniq#/
                                                       name       #name of profile
                                                       attach     #exec profile attachment
                                                       mode       #mode of profile
                                                       sha1       #sha1 of loaded profile
                                                       profiles/  #present if profile has its own subprofiles


The policy load/remove interface which could really use some fuzzy.
.load - atomic write of a set of profiles to load (does not allow replacement). I'll work
  on getting you some docs on its format

.replace - same as .load except indicated replacement is allowed.

.replace - similar to .load/.replace but different format.  Again I'll work on getting
  you some docs.


.null - special null file used in mediation of uninheritable files