doc/smack_accesses_add.3

   1 '\" t
   2 .\" This file is part of libsmack
   3 .\" Copyright (C) 2012 Intel Corporation
   4 .\" Copyright (C) 2012 Samsung Electronics Co.
   5 .\"
   6 .\" This library is free software; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU Lesser General Public License
   8 .\" version 2.1 as published by the Free Software Foundation.
   9 .\"
  10 .\" This library is distributed in the hope that it will be useful, but
  11 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  13 .\" Lesser General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU Lesser General Public
  16 .\" License along with this library; if not, write to the Free Software
  17 .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  18 .\" 02110-1301 USA
  19 .\"
  20 .\" Authors:
  21 .\" Brian McGillion <brian.mcgillion@intel.com>
  22 .\" Rafal Krypa <r.krypa@samsung.com>
  23 .\"
  24 .TH "SMACK_ACCESSES_ADD" "3" "14/06/2012" "Libsmack 1\&.0"
  25 .SH NAME
  26 smack_accesses_new, smack_accesses_free, smack_accesses_save, smack_accesses_apply, smack_accesses_clear, smack_accesses_add, smack_accesses_add_from_file, smack_revoke_subject \- Manipulate Smack rules
  27 .SH SYNOPSIS
  28 .B #include <sys/smack.h>
  29 .sp
  30 .BI "int smack_accesses_new(struct smack_accesses **" accesses ");"
  31 .br
  32 .BI "void smack_accesses_free(struct smack_accesses *" handle ");"
  33 .br
  34
  35 .BI "int smack_accesses_add(struct smack_accesses *" handle ", const char *" subject ", const char *" object ", const char *" access_type ");"
  36 .br
  37 .BI "int smack_accesses_add_modify(struct smack_accesses *" handle ", const char *" subject ", const char *" object ", const char *" access_add ", const char *" access_del ");"
  38 .br
  39 .BI "int smack_accesses_add_from_file(struct smack_accesses *" accesses ", int " fd ");"
  40 .br
  41 .BI "int smack_accesses_save(struct smack_accesses *" handle ", int " fd ");"
  42 .br
  43
  44 .BI "int smack_accesses_apply(struct smack_accesses *" handle ");"
  45 .br
  46 .BI "int smack_accesses_clear(struct smack_accesses *" handle ");"
  47 .br
  48
  49 .BI "int smack_revoke_subject(const char *" subject ");"
  50 .br
  51
  52 .SH DESCRIPTION
  53 These methods provide a means to create properly formatted smack rules that can be stored to file or loaded directly into the kernel.  For loading and unloading rules directly into the kernel the calling process must have the CAP_MAC_ADMIN capability.  Most users will generally store the rules to a file that can be read by
  54 .BR smackload (8).
  55 If the rules should be loaded on system reboot then the file should be stored in /etc/smack/accesses.d/<name>.rules.
  56
  57 .BR smack_accesses_new ()
  58 creates a new empty smack_accesses instance pointed to by
  59 .IR accesses .
  60
  61 .BR smack_accesses_free ()
  62 destroys a previously created instance of smack_accesses pointed to by
  63 .IR handle .
  64
  65 .BR smack_accesses_add ()
  66 create a rule allowing a
  67 .I subject
  68 to access an
  69 .I object
  70 with the type of access defined in
  71 .I access_type
  72 and store the result in
  73 .IR handle .
  74 If a rule for the specified labels already exists it will be overwritten.
  75
  76 .BR smack_accesses_add_modify ()
  77 create a modification rule for the specified
  78 .I subject
  79 and
  80 .I object
  81 labels allowing the access specified in
  82 .I access_add
  83 and disallowing the access defined by
  84 .IR access_del .
  85 The result is stored in
  86 .IR handle .
  87 If a rule for the specified labels already exists it will be modified, otherwise a new rule will be created with the permissions specified in access_add added and those specified in access_del removed.
  88
  89 .BR smack_accesses_add_from_file ()
  90 read a set of rules from a file and store them in
  91 .IR handle .
  92 The file must be a series of lines, 1 per rule, in the format "%s %s %s"
  93 .B "(subject object access_type)"
  94
  95 .BR smack_accesses_save ()
  96 save the smack_accesses instance pointed to by
  97 .I handle
  98 to the file specified by the file-descriptor
  99 .IR fd .
 100
 101 .BR smack_accesses_apply ()
 102 apply the rules pointed to by
 103 .I handle
 104 directly to the kernel.  The calling process must have the CAP_MAC_ADMIN capability.
 105 .BR smack_accesses_clear ()
 106 remove the rules pointed to by
 107 .I handle
 108 directly from the kernel.  The calling process must have the CAP_MAC_ADMIN capability.
 109
 110 .BR smack_revoke_subject ()
 111 Sets the access to '-' (no access allowed) for all access rules with given
 112 .I subject
 113 label directly in the kernel.  The calling process must have the CAP_MAC_ADMIN capability.
 114 .SH RETURN VALUE
 115 All methods, except
 116 .IR smack_accesses_free ,
 117 return 0 on success and a negative value on failure (in which case
 118 .I errno
 119 is set appropriately).
 120 .SH EXAMPLES
 121 .nf
 122 #include <sys/smack.h>
 123
 124 int apply_rules_file(int fd, int clear)
 125 {
 126         struct smack_accesses *rules = NULL;
 127         int ret = 0;
 128
 129         if (smack_accesses_new(&rules))
 130                 return \-1;
 131
 132         if (smack_accesses_add_from_file(rules, fd)) {
 133                 smack_accesses_free(rules);
 134                 return \-1;
 135         }
 136
 137         if (!clear)
 138                 ret = smack_accesses_apply(rules);
 139         else
 140                 ret = smack_accesses_clear(rules);
 141
 142         smack_accesses_free(rules);
 143
 144         return ret;
 145 }
 146 .fi
 147 .SH SEE ALSO
 148 .BR smack_have_access (3)