doc/smack_have_access.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 .\" Author:
  21 .\" Brian McGillion <brian.mcgillion@intel.com>
  22 .\" Rafal Krypa <r.krypa@samsung.com>
  23 .\"
  24 .TH "SMACK_HAVE_ACCESS" "3" "06/20/2012" "Libsmack 1\&.0"
  25 .SH NAME
  26 smack_have_access, smack_new_label_from_self, smack_new_label_from_socket \- Userspace interaction with Smack
  27 .SH SYNOPSIS
  28 .B #include <sys/smack.h>
  29 .sp
  30 .BI "int smack_have_access(const char *" subject ", const char *" object ", const char *" access ");"
  31 .br
  32 .BI "int smack_new_label_from_self(char **" label ");"
  33 .br
  34 .BI "int smack_set_label_for_self(char **" label ");"
  35 .br
  36 .BI "int smack_new_label_from_socket(int " fd ", char **" label ");"
  37 .sp
  38 .SH DESCRIPTION
  39 Smack is a Mandatory Access Control (MAC) based security mechanism for the Linux kernel.  It works on the basis of context, which is stored as a label in the extended attributes (xattr) of a file.  When a process is started the kernel ensures that this context is assigned to the running process.  By default a process can only interact with processes and filesystem objects that have the same context as itself and is denied access to all other contexts.  Rules can be created to grant access to other contexts, these are generally created on package installation and can only be modified by a process that has the CAP_MAC_ADMIN capability.
  40 .PP
  41 As with most actor based models the entity that initiates the interaction is called the
  42 .I subject
  43 and the item that is being accessed is called the
  44 .IR "object" .
  45 The type of interaction that is being performed is known as the
  46 .I access
  47 and is based on the standard filesystem access types "R","W","X" etc.  The functions presented here provide a way for a process to determine the Smack context of the the system in which it is running and that of a process that is connected to it over a socket connection.
  48 .PP
  49 The function
  50 .BR smack_have_access ()
  51 takes a
  52 .I subject
  53 context, and the context of the item that it is interacting with, the
  54 .IR "object" ,
  55 along with the type of
  56 .I access
  57 that is requested.  The kernel is queried about the access rules and informs the the caller it that access request is allowed.  This method is generally used to allow more fine grained access control to be enforced in userspace processes.
  58 .PP
  59 .BR smack_new_label_from_self ()
  60 determines the context of the current process and creates a new storage for this which it assigns to
  61 .I label
  62 to this upon return.  It is the responsibility of the caller to free
  63 .I label
  64 when it is no longer required.
  65 .PP
  66 .BR smack_set_label_for_self ()
  67 sets the context of the current process to
  68 .IR label .
  69 The calling process must have the CAP_MAC_ADMIN capability.
  70 .PP
  71 .BR smack_new_label_from_socket ()
  72 takes the file descriptor,
  73 .IR "fd" ,
  74 of the socket and determines it's context and creates a new storage for this which it assigns to
  75 .I label
  76 on return.  It is the callers responsibility to free
  77 .I label
  78 when it is no longer required.
  79 .SH RETURN VALUE
  80 .BR smack_new_label_from_self ()
  81 and
  82 .BR smack_new_label_from_socket ()
  83 return 0 on success or \-1 on error (in which case,
  84 .I errno
  85 is set appropriately).
  86
  87 .BR smack_have_access ()
  88 returns 1 if allowed, 0 if no access and \-1 on error (in which case,
  89 .I errno
  90 is set appropriately).