doc/smack_getlabel.3

   1 '\" t
   2 .\" This file is part of libsmack
   3 .\" Copyright (C) 2012 Samsung Electronics Co.
   4 .\"
   5 .\" This library is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU Lesser General Public License
   7 .\" version 2.1 as published by the Free Software Foundation.
   8 .\"
   9 .\" This library is distributed in the hope that it will be useful, but
  10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  12 .\" Lesser General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU Lesser General Public
  15 .\" License along with this library; if not, write to the Free Software
  16 .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
  17 .\" 02110-1301 USA
  18 .\"
  19 .\" Author:
  20 .\" Rafal Krypa <r.krypa@samsung.com>
  21 .\"
  22 .TH "SMACK_GETLABEL" "3" "07/05/2012" "Libsmack 1\&.0"
  23 .SH NAME
  24 smack_getlabel, smack_lgetlabel, smack_fgetlabel, smack_setlabel, smack_lsetlabel, smack_fsetlabel \- Manipulation of Smack labels for files
  25 .SH SYNOPSIS
  26 .B #include <sys/smack.h>
  27 .sp
  28 .BI "int smack_getlabel(const char *" path ", char **" label ", enum smack_label_type " type ");"
  29 .br
  30 .BI "int smack_lgetlabel(const char *" path ", char **" label ", enum smack_label_type " type ");"
  31 .br
  32 .BI "int smack_fgetlabel(int " fd ", char **" label ", enum smack_label_type " type ");"
  33 .br
  34
  35 .BI "int smack_setlabel(const char *" path ", const char *" label ", enum smack_label_type " type ");"
  36 .br
  37 .BI "int smack_lsetlabel(const char *" path ", const char *" label ", enum smack_label_type " type ");"
  38 .br
  39 .BI "int smack_fsetlabel(int " fd ", const char *" label ", enum smack_label_type " type ");"
  40 .sp
  41 .SH DESCRIPTION
  42 Smack uses extended attributes (xattrs) to store labels on filesystem objects. The attributes are stored in the extended attribute security name space. A process must have CAP_MAC_ADMIN to change any of these attributes.
  43 These functions provide an interface for Smack label manipulation on files and file descriptors.
  44 .SS "Label types"
  45 There are several types of labels and not all of them are valid for every object. All valid types are defined in enum smack_label_type:
  46 .IP \[bu] 2
  47 .BR SMACK_LABEL_ACCESS :
  48 Label used as the object label for Smack access checks when a labeled file is accessed.
  49 .IP \[bu]
  50 .BR SMACK_LABEL_EXEC :
  51 Label used as the subject label for processes executed from a labeled file by means of
  52 .BR exec (3)
  53 functions family.
  54 .IP \[bu]
  55 .BR SMACK_LABEL_MMAP :
  56 Label used as the object label for Smack access checks when a labeled file is mmap-ed (see
  57 .BR mmap (2)).
  58 .IP \[bu]
  59 .BR SMACK_LABEL_TRANSMUTE :
  60 Special purpose label for directories. In contrast with all other label types, this one is of boolean type. If set to true on a directory, all files and directories created in that directory will inherit the directory's
  61 .BR SMACK_LABEL_ACCESS
  62 label. Created subdirectories will also have
  63 .BR SMACK_LABEL_ACCESS
  64 set to true. The described behavior works only if a subject creating those files and directories has "t" (transmute) permission on the directory's
  65 .BR SMACK_LABEL_ACCESS
  66 label.
  67 .IP \[bu]
  68 .BR SMACK_LABEL_IPIN :
  69 Valid only for socket file descriptors. Used as the object label for packets incoming from the socket.
  70 .IP \[bu]
  71 .BR SMACK_LABEL_IPOUT :
  72 Valid only for socket file descriptors. Used as the Smack label transmitted with outgoing packets.
  73 .SS "Get functions"
  74 All of these functions allocate memory for the label contents and assign the pointer to
  75 .IR label .
  76 The caller is responsible for freeing the memory.
  77 .PP
  78 .BR smack_getlabel ()
  79 retrieves the label of specified
  80 .I type
  81 from the given
  82 .I path
  83 in the filesystem.
  84 .PP
  85 .BR smack_lgetlabel ()
  86 is identical to
  87 .BR smack_getlabel (),
  88 except in the case of a symbolic link, where the link itself is interrogated, not the file that it refers to.
  89 .PP
  90 .BR smack_fgetlabel ()
  91 is identical to
  92 .BR smack_getlabel (),
  93 only the open file pointed to by
  94 .I fd
  95 (as returned by
  96 .BR open(2))
  97 is interrogated in place of
  98 .IR path .
  99 .SS "Set functions"
 100 These functions work with files and file descriptors in the same way as the get functions described above.
 101 They set the label to the value passed in
 102 .I value
 103 argument. Valid values are:
 104 .IP \[bu] 2
 105 NULL or empty string - will cause removal of the label, if any was present on a file.
 106 .IP \[bu]
 107 "1" or "0" for the
 108 .BR SMACK_LABEL_TRANSMUTE
 109 label type on a directory will turn transmute on or off.
 110 .IP \[bu]
 111 Any string not longer than
 112 .BR SMACK_LABEL_LEN
 113 for other label types.
 114 .SH RETURN VALUE
 115 On success, zero is returned. On failure, \-1 is returned and
 116 .I errno
 117 is set appropriately.
 118 .SH SEE ALSO
 119 .BR smack_have_access (3),
 120 .BR attr (5),
 121 .BR open (2).