Added the online documentation.
[py-rsbac] / py-rsbac.txt
1 ## target: py-rsbac
2 ## name: index
3
4 *** RSBAC Python bindings ***
5
6 [[TableOfContents]]
7
8 = rsbac -- An Python interface to the RSBAC system =
9
10 The `rsbac` package is a full interface to the [RSBAC
11 http://rsbac.org] Linux security system, including support to manage
12 the various models it provides. Its goal is to be easy to use,
13 high-level, "object-oriented", complete and with acceptable
14 performance. It allows to easily administrate the RSBAC configuration
15 with the power of Python.
16
17 You can download a frequently updated release [here
18 py-rsbac-unstable-latest.tar.gz].
19
20 Multithreading is not supported at all. Please use some lock to access
21 the package in a multithread environment.
22
23 It was developped first for RSBAC 1.2.8 then for RSBAC 1.3.0, tested
24 mainly on a x86 machine and a PowerPC (G4) machine. Compatibility with
25 1.2.8 is not ensured. However with the correct `rsbac.headers` module,
26 it should works.
27
28 The first release of this package will target full coverage of the
29 RSBAC API (except for PM and MAC models which remain to be added.)
30 More high-level tools built on top of it are planned (such as a GUI,
31 new command line tools, a dedicated shell, backup tools or automatic
32 deployment for example.)
33
34 == Main functions and variables ==
35
36 The `rsbac` package provides some generic functions.
37
38 `moduleVersion`
39
40  The RSBAC Python package version as a tuple
41  `(major,middle,minor,extra)` where `extra` is a string, and other
42  components are integers.
43
44 `kernelVersion`
45
46  The RSBAC kernel version as a tuple `(major,middle,minor)`.
47
48 `libraryVersion`
49
50  The RSBAC library version as a tuple `(major,middle,minor)`.
51
52 `headerVersion`
53
54  The RSBAC headers version as a tuple `(major,middle,minor)`.
55
56 `dumpStats()`
57
58  Dump statistics about RSBAC to kernel log.
59
60 `checkConsistency(correct, checkInode)`
61
62  Check RSBAC configuration consistency. The `correct` argument is 0 to
63  do only a check, 1 to correct errors and 2 to correct even more
64  errors. The `checkInode` argument is a boolean which indicate if
65  inode numbers must also be checked or not.
66
67 `writeDirtyList()`
68
69  Write all dirty lists to disk. Returns number of lists written.
70
71 `init(path)`
72
73  Initialize a filesystem with RSBAC. This is normally not needed,
74  since filesystems are automatically initialized on mount.
75
76 === symbolics name and documentation related functions ===
77
78 The `librsbac.so` provides various functions to retrieve symbolic
79 names for most of the RSBAC constants and conversely to retrieve
80 constant from the symbolic name. These various functions are provided
81 in the rsbac python package.
82
83 For each types of constants, there are 3 functions defined as follow:
84
85 `getFooNumber(name)`
86
87  Retrieve the integer constant from the symbolic name `name`.
88
89 `getFooName(n)`
90
91  Retrieve the symbolic name from the integer constant `n`.
92
93 `getFooNames()`
94
95  Retrieve the list of names. Note that `getFooNames()[n]` is
96  equivalent to `getFooName(n)`, as long as `n` is valid.
97
98
99 There are the following functions:
100
101 `getRequestName(n)`, `getRequestNames()`, `getRequestNumber(name)`
102
103  Name of the requests (`ADD_TO_KERNEL`, `ALTER`, `APPEND_OPEN`,..)
104
105 `getResultName(n)`, `getResultNames()`, `getResultNumber(name)`
106
107  Name of the results (`NOT_GRANTED`, `GRANTED`,..)
108
109 `getAttributeName(n)`, `getAttributeNames()`, `getAttributeNumber(name)`
110
111  Name of the attributes (`pseudo`, `security_level`, `rc_type_fd`,..)
112
113 `getScdTypeName(n)`, `getScdTypeNames()`, `getScdTypeNumber(name)`
114
115  Name of the system control data (`time_strucs`, `clock`, `host_id`,..)
116
117 `getTargetName(n)`, `getTargetNames()`, `getTargetNumbel(name)`
118
119  Name of the RSBAC target (`FILE`, `DIR`, `NETTEMP_NT`,..)
120
121 `getIpcTargetName(n)`, `getIpcTargetNames()`, `getIpcTargetNumber(name)`
122
123  Name of the IPC types (`sem`, `msg`, `shm`,..)
124
125 `getSwitchTargetName(n)`, `getSwitchTargetNames()`, `getSwitchTargetNumber(name)`
126
127  Name of the RSBAC modules (`GEN`, `MAC`, `PM`,..)
128
129 `getCapName(n)`, `getCapNames()`, `getCapNumber(name)`
130
131  Name of the Linux capabilities (`CHOWN`, `DAC_OVERRIDE`, `NET_RAW`,..)
132
133 `getRcTargetName(n)`, `getRcTargetNames()`, `getRcTargetNumber(name)`
134
135  Name of the RC target (`ROLE` and `TYPE`)
136
137 `getRcAdminName(n)`, `getRcAdminNames()`, `getRcAdminNumber(name)`
138
139  Name of the RC admin types (`no_admin`, `role_admin`,..)
140
141 `getRcScdTypeName(n)`, `getRcScdTypeNames()`, `getRcScdTypeNumber(name)`
142
143  Like `ScdType`, but with additionnal constants specific to the RC
144  model.
145
146 `getRcSpecialRightName(n)`, `getRcSpecialRightNames()`, `getRcSpecialRightNumber(name)`
147
148  Like `Request`, but with additionnal constants specific to the RC
149  model.
150
151 `getRessourceName(n)`, `getRessourceNames()`, `getRessourceNumbers(name)`
152
153  Name of the ressource (those settable by ulimit.) (`cpu`, `stack`,
154  `core`,..)
155
156 `getLogLevelName(n)`, `getLogLevelNames()`, `getLogLevelNumber(name)`
157
158  Name of the log levels (`none`, `denied`, `full`,..)
159
160 `getAttributeModule(attribute)`
161
162  Get the module ID to which an attribute belong. The `attribute`
163  parameter is an integer.
164
165 `getErrorName(n)`
166
167  Get the name of the error identified by `n`. This value must be
168  negative, and is usually below or equal to -1001. Be careful: All
169  unknown errors are reported as "Success"!
170
171 `getAttributeParameters(attribute)`
172
173  Return a textual description of the attribute. The resulting string
174  is only useful for debugging purpose.
175
176 `getRcItemParameters(value)`
177
178  Return a textual description of the RC item. The resulting string is
179  only useful for debugging purpose.
180
181 === log related functions ===
182
183 `openLog()`
184
185  Open RSBAC log. *Note*: This function does nothing.
186
187 `closeLog()`
188
189  Close RSBAC log. *Note*: This function does nothing.
190
191 `readLog(size=4096)`
192
193  Read RSBAC log. Up to `size` bytes are read. Return a string.
194
195 `readRingBuffer(size=4096)`
196
197  Read the RSBAC ring buffer. Up to `size` bytes are read. Return a
198  string.
199
200 `readAndClearRingBuffer(size=4096)`
201
202  Read then clear the RSBAC ring buffer. Up to `size` bytes are
203  read. Return a string.
204
205 `clearRingBuffer()`
206
207  Clear the RSBAC ring buffer.
208
209 == Data types ==
210
211 === System roles ===
212
213 Each users have several type of roles for each of the RSBAC
214 modules. For example, root default system role for the FF module is
215 "administrator", while default system role for the security officer
216 for this module is "security_officer" and all others users have the
217 role "user". This way, each users can administrate or obtains rights
218 for a given module.
219
220 The module `rsbac.roles` allows to represent the system roles (not
221 related to RC roles!) The class `SystemRole` is already instantiated
222 for the predefined RSBAC system role, which are:
223
224  * `roles.user`
225
226  * `roles.security_officer`
227
228  * `roles.administrator`
229
230  * `roles.auditor`
231
232 Since `SystemRole` class build singleton instances, it is possible to
233 compare them with the `is` operator.
234
235 === Flags ===
236
237 Several data types in RSBAC are in fact integers used as bit vector.
238 For example, the `rsbac_request_vector_t` is an integer that hold a
239 set of flags related to allowed requests. To manipulate them
240 conveniently under Python, a class was created for each such
241 types. So, for the `rsbac_request_vector_t` there is the corresponding
242 `rsbac.RequestVector` data type in the rsbac package, and so on for
243 other types.
244
245 Such classes provides an immutable set. To modify them, it is
246 necessary to create a new instance. It is similar to string
247 manipulations under Python, where a new string must be created for
248 each operation.
249
250 The flags classes defined in the `rsbac` module are the following:
251
252  * `RequestVector`, `RcRequestVector`, `AclRequestVector`
253
254  * `ScdVector`, `JailScdVector`
255
256  * `FileFlags`
257
258  * `PaxFlags`
259
260  * `CapsFlags`
261
262  * `JailFlags`
263
264 Generic description follows: (where `Flags` name is for illustration
265 purpose)
266
267 `class Flags(init)`
268
269  `init` is a versatile mean to specify an initial value. It can be
270  either:
271
272  * a string, naming a flag,
273
274  * a tuple or a list, which is recursively visited and whose items are
275  combined (OR'ed),
276
277  * an integer or any object castable to an integer, representing a bit
278  vector (each bit of the integer correspond to a flag.)
279
280 `__iter__()`
281
282  Return an iterator over each set flags. First the flags whose name is
283  know are returned, then follows each integer representing unknown
284  flag (each integer is a power of 2, to match the constructor
285  requirement.)
286
287 `__repr__()`
288
289  Return a string representation of the instance such that executing
290  the string give back the same object.
291
292 `__int__()`
293
294 `__long__()`
295
296  Return respectively an int or a long which is the integer with the
297  bit pattern described by all the flags.
298
299 `__cmp__(other)`
300
301  Compare two instances. The order is stable but undefined.
302
303 `__or__(other)`
304
305 `__xor__(other)`
306
307 `__and__(other)`
308
309  Combine two instances with one of the respective boolean operator OR,
310  XOR or AND. The `other` value should be either a `Flags` instance or
311  a value accepted by the `Flags` constructor.
312
313 `__invert__()`
314
315  Return a new instance where all *known* flags are inverted. Unknown
316  bit are kept unchanged.
317
318 FIXME: Give a better set of examples..
319
320 --- Example with the RequestVector type ---
321 -=-=-
322 >>> import rsbac
323 >>> rsbac.RequestVector()
324 RequestVector()
325 >>> rsbac.RequestVector('lock', 'connect', 'alter')
326 RequestVector('alter', 'connect', 'lock')
327 >>> int( rsbac.RequestVector('lock') )
328 562949953421312L  # 2**49
329 >>> rsbac.RequestVector( 2**49 )
330 RequestVector('lock')
331 >>> int( rsbac.RequestVector('alter') )
332 2
333 >>> rsbac.RequestVector( [ ( 'lock' , 'ioctl' ) , [ 'mount' ] , 2 ] )
334 RequestVector('alter', 'mount', 'ioctl', 'lock')
335 >>> ~rsbac.RequestVector()
336 RequestVector('add_to_kernel', 'alter', 'append_open', ..., 'ioctl', 'lock', 'authenticate')
337 >>> rsbac.RequestVector('bind', 'listen') ^ rsbac.RequestVector('bind', 'connect')
338 RequestVector('listen', 'connect')
339 >>> rsbac.RequestVector('bind', 'listen') & ~rsbac.RequestVector('bind', 'connect')
340 RequestVector('listen')
341 >>> list( rsbac.RequestVector( 127 ) )
342 ['add_to_kernel', 'alter', 'append_open', 'change_group', 'change_owner', 'chdir', 'clone']
343 -=-=-
344
345 -=-=-
346 >>> a = rsbac.RequestVector( 'bind' )
347 >>> a |= 'listen' , 'connect'
348 >>> a
349 RequestVector('bind', 'listen', 'connect')
350 >>> a &= ~rsbac.RequestVector( 'bind' , 'listen' )
351 >>> a
352 RequestVector('connect')
353 -=-=-
354
355 === dict- and set- like variables ===
356
357 At some places, some variables have a dict-like or a set-like
358 interface, meaning that they can be used and updated like the usual
359 Python dictionnaries or Python sets. These variables are usually
360 dynamic, meaning that there contents reflect the state of the RSBAC
361 configuration.
362
363 There is also a type named "TTL dict-like variable" at some place in
364 this document. It's in fact a type sharing both `set` and `dict`
365 interface. This type act as a dictionnary, where the values have the
366 meaning described in the "TTL" section. To summarize: a value with
367 `False` mean that there is no entry for the given key, `None` mean to
368 keep the existing TTL, other value mean that the entry exists where an
369 integer specify the TTL and `True` mean that the TTL is illimited.
370
371 === TTL ===
372
373 The way to specify TTL in the rsbac package is a bit different from
374 the usage in other RSBAC tools.
375
376 In other RSBAC tools (as understood internally in the kernel), a
377 special value (maximum representable TTL value) is used when we want
378 to preserve the TTL, 0 is for unlimited TTL and any other integers are
379 interpreted as a duration in seconds.
380
381 But we have chosen another approach. In the rsbac package, `None` mean
382 that we want to keep the TTL (thus we specify "no" TTL), `False` mean
383 that the object doesn't exists (the TTL expired, or is undefined or
384 unknown), `True` means unlimited TTL and any integer means a duration
385 in seconds. Since TTL cannot be lower than 1s, any integers is clamped
386 to this minimal duration. It means that 0 is also interpreted as a
387 number of second, which is clamped to 1s. The whole point is to have a
388 coherent behavior. (A better behavior could have been reached if it
389 was possible to set the TTL to 0s to discard immediatly the
390 corresponding settings in the RSBAC configuration.)
391
392 To summarize:
393
394 | *TTL*   | *Meaning*                             |
395 | `False` | Expired TTL (No entry/no such object) |
396 | integer | remaining TTL in seconds              |
397 | `True`  | unlimited TTL                         |
398 | `None`  | ask to keep the current TTL           |
399
400 == RSBAC modules ==
401
402 RSBAC is divided into various models (aka modules, depending of the
403 context.) There are for example the ACL, RC and PM modules. Each of
404 these modules can be turned on and off (depending of kernel options
405 when the kernel was compiled, or depending of the nature of the
406 model), and their softmode may be enabled or disabled. Also,
407 naturally, a model can be available or not, according to choice made
408 when compiling the kernel.
409
410 The `rsbac.module` module provides a list of all the RSBAC modules
411 known to the rsbac package. This module contains an instance of a
412 `module.Module` class for each of them. There is also a `module.all`
413 variable which is a list of all these instances.
414
415 Each module is represented by the following class:
416
417 `class Module(..)`
418
419  This class is not meant to be instantiated by the user.
420
421 `__int__()`
422
423 `__long__()`
424
425  Cast the module instance to the corresponding RSBAC identifier.
426
427 `id`
428
429  This read-only property is the RSBAC identifier for the module.
430
431 `name`
432
433  This read-only property is the name of the module.
434
435 `available`
436
437  This read-only property is a boolean, which is true if the module was
438  compiled in the kernel and False otherwise. If the module is not
439  available, then access to other properties will fail.
440
441 `enabled`
442
443  This read/write property is the state of the module. If true, the
444  module is enabled. Otherwise, it is disabled.
445
446 `switchableOn`
447
448  This read-only property indicate if the module can be switched on.
449
450 `switchableOff`
451
452  This read-only property indicate if the module can be switched off.
453
454 `softmode`
455
456  This read/write property is the state of the softmode for the
457  module. If true, the softmode is enabled. Otherwise, it is disabled.
458
459 `softmodeSwitchableOn`
460
461  This read-only property indicate if the softmode of the module can be
462  switched on.
463
464 `softmodeSwitchableOff`
465
466  This read-only property indicate if the softmode of the module can be
467  switched off.
468
469 == Transactions ==
470
471 RSBAC transactions are fully supported. To make them easy to use, it
472 was chosen to use a global variable used internally by the rsbac
473 package, rather than letting the user specify the current transaction
474 manually when reading/modifying RSBAC system configuration. The module
475 `rsbac.transaction` contains the class and functions needed to manage
476 transaction.
477
478 The standard method to run a block of code with a new transaction and
479 ensuring the transaction is correctly terminated even if exception
480 occurs, is to use the `transaction.withTransaction` function.
481
482 `withTransaction(function, uid=.., password=None, ttl=True)`
483
484  Create a new transaction, then call `function` to which a
485  `Transaction` instance is passed as the only argument. Anything
486  happening while `function` is called, is performed with the
487  corresponding transaction. The function must `commit` or `forget` the
488  transaction at some point before returning. If the function doesn't
489  terminate the transaction, then it is automatically canceled when the
490  function returns. See the documentation of the `Transaction` instance
491  below.
492
493  `function` is a callable taking one argument.
494
495  `uid` is the UID to which the transaction belong. The default value
496  allows any users to use the transaction, in which case a password may
497  be useful.
498
499  `password` is an optional password to protect the transaction. The
500  default value doesn't define any password.
501
502  `ttl`, used to select the time to live of the transaction. The TTL
503  cannot exceed the maximum duration specified in the kernel. The
504  default is the maximum allowed TTL.
505
506 The transaction is represented by a instance of the following class:
507
508 `class Transaction(..)`
509
510  This class is not meant to be instantied by the user. See
511  `withTransaction` to create and use such instance.
512
513  Its purpose is to represent an existing transaction, not to create
514  them.
515
516 `refresh(ttl=True)`
517
518  Reset the TTL of the transaction. Default value is to extend the TTL
519  to the maximum allowed duration.
520
521 `commit()`
522
523  Commit the transaction.
524
525 `forget()`
526
527  Forget (revert, cancel) the transaction.
528
529 --- Example of transaction ---
530 -=-=-
531 def doSomething( transaction ) :
532   doThing1()
533   doThing2()
534   if not doThing3() :
535     transaction.forget()
536   else :
537     doThing4()
538     transaction.commit()
539
540 withTransaction( doSomething , ttl = 300 )
541 -=-=-
542
543 == Representing objects ==
544
545 A central concept to RSBAC is the various Unix objects such as file
546 system objects (file, directory, fifo pipe, ..), processes, network
547 device and so on. To represent them, the `rsbac.objects` package
548 provides a hierarchy of classes for each RSBAC object type. Through
549 these classes, all RSBAC objects attributes can be read and written.
550
551 The module described below also contains 3 functions
552 `listAllDevices()`, `listAllUsers()` and `listAllGroups()` which
553 return the corresponding list of objects known to RSBAC.
554
555 Most of the following class contains a `rcTypes` attribute with a
556 dict-like interface which gives access to all the defined RC type
557 specific to the corresponding class. For more information, see the
558 section discussing this topic.
559
560 [[LocalTableOfContents]]
561
562 === FD objects ===
563
564 All common filesystem objects are represented with one of the
565 following class:
566
567 `class FD(id)`
568
569 `class Directory(id)`
570
571 `class File(id)`
572
573 `class Symlink(id)`
574
575 `class Device(id)`
576
577 `class Fifo(id)`
578
579 `class UnixSocket(id)`
580
581  The constructor takes a path to the file system objects.
582
583  The FD class is an abstract data type which resolve to the correct
584  type (`File`, `Directory`, `Symlink`, `Device`, `Fifo` or
585  `UnixSocket`) inside the RSBAC system (not by the `rsbac` Python
586  package.)
587
588 `__str__()`
589
590  Return the ID (the path).
591
592 `acl`
593
594  This dict-like attribute gives access to ACL entries for the
595  object. It's indexed by a subject (user, RC role or ACL group.)
596
597 Class attribute:
598
599 `rcTypes`
600
601  A dict-like attribute which contains all FD RC types.
602
603 Additionnaly, there are some predefined instances to match particular
604 RSBAC objects:
605
606  * `defaultFD`
607
608  * `defaultFile`
609
610  * `defaultFifo`
611
612  * `defaultSymlink`
613
614  * `defaultDirectory`
615
616  * `defaultDevice`
617
618  * `defaultUnixSocket`
619
620 These instances are useful for the ACL entries on the default targets.
621
622 === Device ===
623
624 The following classes derive from the `DeviceBase` class.
625
626 It is different from the `Device` class which is instantiated with a
627 path, while here we need the `major` and `minor` numbers.
628
629 `class BlockDevice(major[, minor])`
630
631 `class CharacterDevice(major[, minor])`
632
633  If `minor` is not specified, then construct an object that match any
634  device with the specified `major` number.
635
636 `acl`
637
638  This dict-like attribute gives access to ACL entries for the
639  object. It's indexed by a subject (user, RC role or ACL group.)
640
641 Class attribute:
642
643 `rcTypes`
644
645  A dict-like attribute which contains all network device RC types.
646
647 === User and group ===
648
649 See also `um.User` and `um.Group` for the UM specific settings related
650 to users and groups.
651
652 The `rsbac.um` class contains the dict-like variable `users` and
653 `groups` which gives access to all defined users and groups in RSBAC.
654 Note that you should not perform a call like `users.clear()` (which
655 remove ALL the users from the UM module) by mistake, especially if the
656 system is configured to rely on RSBAC for all authentication.
657
658 `addUser(name, uid=None, password=None, ttl=True)`
659
660  Add an user to the UM module named 'name'. If `uid` is None, then an
661  UID is automatically chosen, otherwise the argument specify the UID
662  to use. The `password` if not None, specify the user password.
663
664  Return an User instance for the newly created account.
665
666 `addGroup(name, gid=None, password=None, ttl=True)`
667
668  Add an group to the UM module named 'name'. If `uid` is None, then an
669  GID is automatically chosen, otherwise the argument specify the GID
670  to use. The `password` if not None, specify the group password.
671
672  Return a Group instance for the newly created group.
673
674 ==== User class ====
675
676 `class User(uid)`
677
678  The `uid` is the UID of an Unix user.
679
680 `removeFromAcl()`
681
682  Remove all ACL entries on all objects whose subject is this user.
683
684 `acl`
685
686  This dict-like attribute gives access to ACL entries for the
687  object. It's indexed by a subject (user, RC role or ACL group.)
688
689 Class attribute:
690
691 `rcTypes`
692
693  A dict-like attribute which contains all user RC types.
694
695 There is also a module `objects.pseudoUsers` which contains predefined
696 `User` instance to represent pseudo users named `all_users` and
697 `no_user`.
698
699 ==== Group class ====
700
701 `class Group(gid)`
702
703  The `gid` in the GID of an Unix group.
704
705 `acl`
706
707  This dict-like attribute gives access to ACL entries for the
708  object. It's indexed by a subject (user, RC role or ACL group.)
709
710 Class attribute:
711
712 `rcTypes`
713
714  A dict-like attribute which contains all group RC types.
715
716 There is also a module `objects.pseudoGroups` which contains
717 predefined `Group` instance to represent pseudo groups named
718 `all_groups` and `no_group`.
719
720 === Process ===
721
722 `class Process(pid)`
723
724  The `pid` is the PID of an Unix process.
725
726 `acl`
727
728  This dict-like attribute gives access to ACL entries for the
729  object. It's indexed by a subject (user, RC role or ACL group.)
730  Note that it make sense only on the `defaultProcess` instance.
731
732 Class attribute:
733
734 `rcTypes`
735
736  A dict-like attribute which contains all process RC types.
737
738 There is also a `defaultProcess` instance to represent the default
739 process (useful for the ACL entries.)
740
741 === IPC ===
742
743 The following classes derive from the `objects.Ipc` class.
744
745 `class IpcSem(semid)`
746
747  A class to represent an IPC Semaphore with ID `semid`.
748
749 `class IpcMsg(msgid)`
750
751  A class to represent an IPC Message with ID `msgid`.
752
753 `class IpcShm(shmid)`
754
755  A class to represent an IPC Shared Memory with ID `shmid`.
756
757 `class IpcAnonPipe(inode)`
758
759  A class to represent an Anonymous pipe with inode `inode` (as created by `pipe(2)`.)
760
761 `class IpcMqueue(mqdes)`
762
763  A class to represent a POSIX message queues with descriptor `mqdes`
764  (as created by `mq_open(3)`.)
765
766  Note that it doesn't appear to be supported by RSBAC however!
767
768 `class IpcAnonUnix(inode)`
769
770  A class to represent an Anonymous Unix socket with inode `inode` (as
771  created by `socketpair(2)`)
772
773 Class attribute:
774
775 `rcTypes`
776
777  A dict-like attribute which contains all IPC RC types.
778
779 === SCD ===
780
781 `class SCD(..)`
782
783  The class `SCD` is not meant to be instantiated by the user. It is
784  already instantiated for all known system objects (System Control
785  Data) and these instances are availables in the module
786  `rsbac.objects.system` (see below.)
787
788 `rc_type`
789
790  The RC type corresponding to the SCD object.
791
792 `acl`
793
794  This dict-like attribute gives access to ACL entries for the
795  object. It's indexed by a subject (user, RC role or ACL group.)
796
797 Class attribute:
798
799 `rcTypes`
800
801  A dict-like attribute which contains all SCD RC types.
802
803 There is also a `defaultScd` instance to represent the default SCD
804 object.
805
806 --- SCD instances defined in objects.system ---
807 -=-=-
808 >>> dir(rsbac.objects.system)
809 ['__doc__', '__name__',
810  'capability', 'clock', 'firewall', 'host_id', 'ioports',
811  'kexec', 'kmem', 'ksyms', 'mlock', 'net_id', 'network',
812  'nfsd', 'none', 'other', 'priority', 'quota', 'rlimit',
813  'rsbac', 'rsbac_log', 'rsbac_remote_log', 'swap', 'sysctl',
814  'sysfs', 'syslog', 'time_strucs']
815 -=-=-
816
817 === Network device ===
818
819 `class NetworkDevice(name)`
820
821  The `name` is the network device name.
822
823 `acl`
824
825  This dict-like attribute gives access to ACL entries for the
826  object. It's indexed by a subject (user, RC role or ACL group.)
827
828 Class attribute:
829
830 `rcTypes`
831
832  A dict-like attribute which contains all network device RC types.
833
834 There is also a `defaultNetworkDevice` instance to represent the
835 default network device.
836
837 === Network template ===
838
839 `class NetworkTemplate(id)`
840
841  The `id` is the ID of the RSBAC network template.
842
843 `acl`
844
845  This dict-like attribute gives access to ACL entries for the
846  object. It's indexed by a subject (user, RC role or ACL group.)
847
848 `selfAcl`
849
850  This dict-like attribute gives access to ACL entries for the template
851  itself (not to the object matched by the template.) It's indexed by a
852  subject (user, RC role or ACL group.)
853
854  FIXME: Choose another name for this attribute?
855
856 This class also contains specific attributes:
857
858 `name`
859
860  This read/write property is the name of the network
861  template. Setting the name of an undefined network template creates
862  it.
863
864 `addresses`
865
866  This read/write property is a tuple `(address_family, addresses)`
867  where `address_family` is an integer as defined by the constants in
868  the standard module `socket` (such as `socket.AF_INET` and so on) and
869  `addresses` is a list of addresses (as string) specific to the
870  address family. To represent the IPv4 address `127.0.0.1` and the
871  IPv4 network `192.168.1.0/24`, this property can be set to
872  `(socket.AF_INET, ['127.0.0.1', '192.168.1.0/24'])`.
873
874 `socketType`
875
876  This read/write property is the type of socket to match by the
877  network template, as defined by the constants in the standard module
878  `socket` (such as `socket.SOCK_STREAM`, `socket.SOCK_DGRAM` and so
879  on). A value of 0 means any socket types.
880
881 `protocol`
882
883  This read/write property is the protocol to match by the network
884  template, as defined by the constants in the standard module `socket`
885  (such as `socket.IPPROTO_TCP`, `socket.IPPROTO_UDP` and so on). A
886  value of 0 means any protocols.
887
888 `networkDevice`
889
890  This read/write property is the name of a network device. If empty,
891  any network devices is matched.
892
893 `ports`
894
895  This read/write property is a list of range of ports. A range of a
896  single port can be written as a single integer. To represent the
897  ports 1024 to 1099, plus the single port 1200, the property is
898  `[(1024,1099), 1200]`.
899
900 Methods for this class are:
901
902 `checkId()`
903
904  Retrieve the ID of the network template if it is defined or throw an
905  exception of type `errors.Error` if not found.
906
907 `copyTo(target)`
908
909  Copy the network template to a new one with ID `target`. The target
910  network template can be an existing one.
911
912 `delete()`
913
914  Remove the network template from the RSBAC system.
915
916 A class method is provided to create new network templates:
917
918 `create(id, name)`
919
920  Create a new network template of ID `id` named with the string
921  `name`. Return a `NetworkTemplate` instance for the newly created
922  network template.
923
924 Class attribute:
925
926 `rcTypes`
927
928  A dict-like attribute which contains all network template RC types.
929
930 The module also provides a variable `networkTemplates` with a
931 dict-like interface to give access to all defined network templates. A
932 network template can be created with `networkTemplates[id]=name`,
933 since setting the name of an undefined network template automatically
934 creates it.
935
936 === Network object ===
937
938 `class NetworkObject(..)`
939
940  This type is particular because it cannot really be instantiated from
941  the userland. The reason is that it refers to a structure which is
942  inside the kernel. See `objects.defaultNetworkObject` for the only
943  instance available.
944
945 `acl`
946
947  This dict-like attribute gives access to ACL entries for the
948  object. It's indexed by a subject (user, RC role or ACL group.)
949
950 There is however an instance `objects.defaultNetworkObject` to
951 represent the default network object.
952
953 Class attribute:
954
955 `rcTypes`
956
957  A dict-like attribute which contains all network device RC types.
958
959 == Details about objects properties ==
960
961 The following properties are part of the classes described is the
962 previous section.
963
964 === RSBAC attributes ===
965
966 All the classes used to represent a RSBAC object give access to the
967 set of RSBAC attributes for the corresponding object via
968 properties. Each of these properties is of a type specific to the
969 RSBAC attribute. The following table gives the name of the attributes,
970 the module concerned (for information purpose, but not needed
971 otherwise), the targets that own the attribute and the type as handled
972 by the rsbac package.
973
974 For example, to retrieve the RC type of the process of PID 1 you can
975 use `rsbac.objects.Process(1).rc_type`.
976
977 FIXME: Complete the following table.
978
979 | *Module* | *Attribute*              | *Type*          | *Target*                                                                        |
980 | `GEN`    | `audit_uid`              | `objects.User`  | `Process`                                                                       |
981 | `GEN`    | `auid_exempt`            | `objects.User`  | `FD`, `Process`                                                                 |
982 | `AUTH`   | `auth_last_auth`         | `objects.User`  | `Process`                                                                       |
983 | `AUTH`   | `auth_learn`             | `bool`          | `FD`, `Process`                                                                 |
984 | `AUTH`   | `auth_may_set_cap`       | `bool`          | `FD`, `Process`                                                                 |
985 | `AUTH`   | `auth_may_setuid`        | `int`           | `FD`, `Process`                                                                 |
986 | `AUTH`   | `auth_role`              | `SystemRole`    | `User`                                                                          |
987 | `CAP`    | `cap_ld_env`             | `int`           | `FD`, `Process`, `User`                                                         |
988 | `CAP`    | `cap_process_hiding`     | `int`           | `Process`                                                                       |
989 | `CAP`    | `cap_role`               | `SystemRole`    | `User`                                                                          |
990 | `MAC`    | `current_sec_level`      |                 | `Process`                                                                       |
991 | `DAZ`    | `daz_role`               |                 | `User`                                                                          |
992 | `DAZ`    | `daz_scanned`            |                 | `FD`                                                                            |
993 | `DAZ`    | `daz_scanner`            |                 | `FD`, `Process`                                                                 |
994 | `GEN`    | `fake_root_uid`          | `int`           | `FD`, `Process`                                                                 |
995 | `FF`     | `ff_flags`               | `FileFlags`     | `FD`                                                                            |
996 | `FF`     | `ff_role`                | `SystemRole`    | `User`                                                                          |
997 | `MAC`    | `initial_security_level` |                 | `Process`, `User`                                                               |
998 | `JAIL`   | `jail_flags`             | `JailFlags`     | `Process`                                                                       |
999 | `JAIL`   | `jail_id`                | `int`           | `Ipc`, `Process`                                                                |
1000 | `JAIL`   | `jail_ip`                | IP²             | `Process`                                                                       |
1001 | `JAIL`   | `jail_max_caps`          | `CapsFlags`     | `Process`                                                                       |
1002 | `JAIL`   | `jail_parent`            | `int`           | `Process`                                                                       |
1003 | `JAIL`   | `jail_role`              | `SystemRole`    | `User`                                                                          |
1004 | `JAIL`   | `jail_scd_get`           | `JailScdVector` | `Process`                                                                       |
1005 | `JAIL`   | `jail_scd_modify`        | `JailScdVector` | `Process`                                                                       |
1006 | `GEN`    | `linux_dac_disable`      | `int`           | `FD`                                                                            |
1007 | `GEN`    | `local_log_array`        | -               | `NetworkObject`                                                                 |
1008 | `MAC`    | `local_mac_categories`   | -               | `NetworkObject`                                                                 |
1009 | `PM`     | `local_pm_ipc_purpose`   | -               | `NetworkObject`                                                                 |
1010 | `PM`     | `local_pm_object_class`  | -               | `NetworkObject`                                                                 |
1011 | `PM`     | `local_pm_object_type`   | -               | `NetworkObject`                                                                 |
1012 | `RC`     | `local_rc_type`          | -               | `NetworkObject`                                                                 |
1013 | `MAC`    | `local_sec_level`        | -               | `NetworkObject`                                                                 |
1014 | `GEN`    | `log_array`              | `tuple`³        | `Device`, `FD`, `NetworkDevice`, `NetworkTemplate`                              |
1015 | `GEN`    | `log_program_based`      | `RequestVector` | `FD`, `Process`                                                                 |
1016 | `GEN`    | `log_user_based`         | `RequestVector` | `User`                                                                          |
1017 | `MAC`    | `mac_auto`               |                 | `FD`, `Process`                                                                 |
1018 | `MAC`    | `mac_categories`         |                 | `Device`, `FD`, `Ipc`, `NetworkTemplate`, `Process`, `User`                     |
1019 | `MAC`    | `mac_check`              |                 | `Device`                                                                        |
1020 | `MAC`    | `mac_curr_categories`    |                 | `Process`                                                                       |
1021 | `MAC`    | `mac_file_flags`         |                 | `FD`                                                                            |
1022 | `MAC`    | `mac_initial_categories` |                 | `Process`, `User`                                                               |
1023 | `MAC`    | `mac_min_categories`     |                 | `Process`, `User`                                                               |
1024 | `MAC`    | `mac_process_flags`      |                 | `Process`                                                                       |
1025 | `MAC`    | `mac_prop_trusted`       |                 | `FD`                                                                            |
1026 | `MAC`    | `mac_role`               |                 | `User`                                                                          |
1027 | `MAC`    | `mac_user_flags`         |                 | `User`                                                                          |
1028 | `CAP`    | `max_caps`               | `CapsFlags`     | `FD`, `User`                                                                    |
1029 | `CAP`    | `max_caps_program`       |                 | `Process`                                                                       |
1030 | `CAP`    | `max_caps_user`          |                 | `Process`                                                                       |
1031 | `MAC`    | `max_read_categories`    |                 | `Process`                                                                       |
1032 | `MAC`    | `max_read_open`          |                 | `Process`                                                                       |
1033 | `CAP`    | `min_caps`               | `CapsFlags`     | `FD`, `User`                                                                    |
1034 | `MAC`    | `min_security_level`     |                 | `Process`, `User`                                                               |
1035 | `MAC`    | `min_write_categories`   |                 | `Process`                                                                       |
1036 | `MAC`    | `min_write_open`         |                 | `Process`                                                                       |
1037 | `PAX`    | `pax_flags`              | `PaxFlags`      | `FD`, `Process`                                                                 |
1038 | `PAX`    | `pax_role`               | `SystemRole`    | `User`                                                                          |
1039 | `PM`     | `pm_current_task`        |                 | `Process`                                                                       |
1040 | `PM`     | `pm_ipc_purpose`         |                 | `Ipc`, `NetworkTemplate`                                                        |
1041 | `PM`     | `pm_object_class`        |                 | `Device`, `FD`, `Ipc`, `NetworkTemplate`                                        |
1042 | `PM`     | `pm_object_type`         |                 | `Device`, `FD`, `Ipc`, `NetworkTemplate`                                        |
1043 | `PM`     | `pm_process_type`        |                 | `Process`                                                                       |
1044 | `PM`     | `pm_role`                |                 | `User`                                                                          |
1045 | `PM`     | `pm_task_set`            |                 | `User`                                                                          |
1046 | `PM`     | `pm_tp`                  |                 | `FD`, `Process`                                                                 |
1047 | `GEN`    | `pseudo`                 | -               | `User`                                                                          |
1048 | `RC`     | `rc_def_role`            | `rc.Role`       | `User`                                                                          |
1049 | `RC`     | `rc_force_role`          | `rc.Role`       | `FD`, `Process`                                                                 |
1050 | `RC`     | `rc_initial_role`        | `rc.Role`       | `FD`                                                                            |
1051 | `RC`     | `rc_role`                | `rc.Role`       | `Process`                                                                       |
1052 | `RC`     | `rc_select_type`         | `rc.Type`       | `Process`                                                                       |
1053 | `RC`     | `rc_type`                | `rc.Type`       | `Device`, `Group`, `Ipc`, `NetworkDevice`, `NetworkTemplate`, `Process`, `User` |
1054 | `RC`     | `rc_type_fd`             | `rc.Type`       | `FD`                                                                            |
1055 | `RC`     | `rc_type_nt`             | `rc.Type`       | `NetworkTemplate`                                                               |
1056 | `GEN`    | `remote_ip`              | IP²             | `Process`                                                                       |
1057 | `GEN`    | `remote_log_array`       | -               | `NetworkObject`                                                                 |
1058 | `MAC`    | `remote_mac_categories`  | -               | `NetworkObject`                                                                 |
1059 | `PM`     | `remote_pm_ipc_purpose`  | -               | `NetworkObject`                                                                 |
1060 | `PM`     | `remote_pm_object_class` | -               | `NetworkObject`                                                                 |
1061 | `PM`     | `remote_pm_object_type`  | -               | `NetworkObject`                                                                 |
1062 | `RC`     | `remote_rc_type`         | -               | `NetworkObject`                                                                 |
1063 | `MAC`    | `remote_sec_level`       | -               | `NetworkObject`                                                                 |
1064 | `RES`    | `res_max`                | `tuple`³        | `FD`, `User`                                                                    |
1065 | `RES`    | `res_min`                | `tuple`³        | `FD`, `User`                                                                    |
1066 | `RES`    | `res_role`               | `SystemRole`    | `User`                                                                          |
1067 | `MAC`    | `security_level`         |                 | `Device`, `FD`, `Ipc`, `NetworkTemplate`, `Process`, `User`                     |
1068 | `GEN`    | `symlink_add_mac_level`  | `bool`          | `FD`                                                                            |
1069 | `GEN`    | `symlink_add_rc_role`    | `bool`          | `FD`                                                                            |
1070 | `GEN`    | `symlink_add_remote_ip`  | `bool`          | `FD`                                                                            |
1071 | `GEN`    | `symlink_add_uid`        | `bool`          | `FD`                                                                            |
1072
1073  * Note¹: ..
1074
1075  * Note²: an IPv4 address represented by a tuple of 4 integers
1076  (between 0 and 255 inclusive.)
1077
1078  * Note³: These tuples are subject to change in the future to a more
1079  convenient data type. Please refer to the RSBAC documentation in the
1080  meantime to figure the meaning of each items.
1081
1082  * Note: The default network object doesn't have any
1083  attributes. Moreover, network object cannot be represented from
1084  userland. Thus, attributes for this target is not supported by the
1085  rsbac Python package.
1086
1087 === rcTypes property ===
1088
1089 This class attribute gives access to all the RC type which are
1090 specific to the corresponding objects. It's a dict-like object.
1091
1092 For example, to obtain the RC Type 2 of the target FD, you could use
1093 `rsbac.objects.FD.rcTypes[2]`. It also works if you've an instance of
1094 the FD class in which case you could use
1095 `rsbac.objects.FD('/some/path').rcTypes[2]`, since `rcTypes` is a
1096 class attribute (not specific to an instance.)
1097
1098 === acl property ===
1099
1100 This dict-like attribute gives access to ACL entries for an object
1101 against a particular subject.
1102
1103 The entries are represented by a couple `(requests,ttl)` where
1104 `requests` is of type `AclRequestVector` and `ttl` is as described in
1105 the data section.
1106
1107 As a convenience, it is possible to the set the entry to just
1108 `request`, in which case an unlimited TTL is implied.
1109
1110 For example, to obtain the ACL entry where:
1111
1112 -=-=-
1113 file = rsbac.objects.FD('/some/path')
1114 user = rsbac.objects.User(0)
1115 -=-=-
1116
1117 you simply use `file.acl[user]` to read and write the entry on FD
1118 object `/some/path` for the subject `User(0)` (the `root` user in this
1119 case.)
1120
1121 == User management ==
1122
1123 RSBAC can optionnaly manage the Unix users and groups from inside the
1124 kernel (rather than relying on method such as the use of files
1125 `/etc/passwd` and `/etc/group`.) The `rsbac.um` package provides the
1126 API to manage these users and groups.
1127
1128 Note that the class `um.User` is not the same as `objects.User`! The
1129 former is to manage settings related to the user as stored in RSBAC,
1130 while the latter is to manage behavior of an Unix user to a RSBAC
1131 system. FIXME: Not clear.
1132
1133 The module also provides two dict-like variables named `users` and
1134 `groups`. They contain the list of users and groups currently
1135 registered.
1136
1137 === User ===
1138
1139 `class User(uid)`
1140
1141  Create an instance which represent the user with UID `uid`.
1142
1143 `__int__()`
1144
1145 `__long__()`
1146
1147  Cast the instance to an integer which is the user's UID.
1148
1149 `name`
1150
1151  This read/write property is the name of the user. It is the
1152  shortname, usually called the login name.
1153
1154 `fullname`
1155
1156  This read/write property is the full user name. Only useful for some
1157  tools.
1158
1159 `hashedPassword`
1160
1161  This read/write property is the hashed password of the user. This
1162  value is only useful for backup purpose, since it is not possible to
1163  deduce the clear password from it. And it is not recommended to set
1164  the hashed password by hand. Use the `password` property instead.
1165
1166 `password`
1167
1168  This write-only property is the user password. Since the password is
1169  stored with a cryptographic hash, it is not possible to retrieve the
1170  original password from this property.
1171
1172 `homeDirectory`
1173
1174  This read/write property is the path to the user home directory.
1175
1176 `shell`
1177
1178  This read/write property is the path to the user shell.
1179
1180 `group`
1181
1182  This read/write property is the GID of the main group for this user.
1183  It should not be confused with the `groups` attribute.
1184
1185 `groups`
1186
1187  This set-like attribute hold the set of extra groups to which the
1188  user belong. It should not be confused with the `group` property.
1189
1190 `exists`
1191
1192  This read-only property is True if the user exists and False
1193  otherwise.
1194
1195 `ttl`
1196
1197  This read-write property is the TTL (time to live) in seconds for
1198  this user.
1199
1200 Additionnaly, there is two methods:
1201
1202 `updatePassword(old,new)`
1203
1204  Update the user password the usual way. The `old` password should be
1205  the actual password, and the `new` password is the password to set.
1206  This method is available to the owner of the account, while the
1207  `password` property is only settable by a security officer.
1208
1209 `delete()`
1210
1211  Remove the account from the UM configuration.
1212
1213 === Group ===
1214
1215 `class Group(gid)`
1216
1217  Create an instance which represent the user with GID `gid`.
1218
1219 `__int__()`
1220
1221 `__long__()`
1222
1223  Cast the instance to an integer which is the group's GID.
1224
1225 `name`
1226
1227  This read/write property is the name of the group.
1228
1229 `hashedPassword`
1230
1231  This read/write property is the hashed password of the group. This
1232  value is only useful for backup purpose, since it is not possible to
1233  deduce the clear password from it. And it is not recommended to set
1234  the hashed password by hand. Use the `password` property instead.
1235
1236 `password`
1237
1238  This write-only property is the group password. Since the password is
1239  stored with a cryptographic hash, it is not possible to retrieve the
1240  original password from this property.
1241
1242 `ttl`
1243
1244  This read/write property is the TTL (time to live) in seconds for
1245  this group.
1246
1247 `members`
1248
1249  This read-only property is a tuple which contains the `um.User` which
1250  belong to this groups.
1251
1252 `extraMembers`
1253
1254  This read-only property is a tuple which contains the `um.User` which
1255  have this group as an extra group.
1256
1257 `exists`
1258
1259  This read-only property is True if the group exists and False otherwise.
1260
1261 Additionnaly, there is two methods:
1262
1263 `updatePassword(old,new)`
1264
1265  Update the group password the usual way. The `old` password should be
1266  the actual password, and the `new` password is the password to set.
1267  This method is available to the members of the group, while the
1268  `password` property is only settable by a security officer.
1269
1270 `delete()`
1271
1272  Remove the group from the UM configuration.
1273
1274 == ACL ==
1275
1276 The module `rsbac.acl` allows to manage the ACL groups. There is a
1277 dict-like variable named `acl.groups` which contains all the existing
1278 ACL groups.
1279
1280 ACL groups are represented with the following class:
1281
1282 `Group(id)`
1283
1284  Create an instance to represent the ACL group with ID `id`.
1285
1286 `name`
1287
1288  This read/write property is the name of the group.
1289
1290 `members`
1291
1292  This TTL dict-like attribute give access to the members of the group.
1293
1294 `owner`
1295
1296  This read/write property is the owner of the group, represented by an
1297  `objects.User` instance.
1298
1299 `private`
1300
1301  This read/write property is a boolean which indicate if the type is
1302  private (True) or global (False).
1303
1304 The `rsbac.acl` module also provides some additionnal utility functions
1305 related to ACL:
1306
1307 `grant(subject, object, requests)`
1308
1309  Grant `requests` to the subject for the given object. The TTL is kept
1310  unchanged.
1311
1312 `revoke(subject, object, requests)`
1313
1314  Revoke `requests` to the subject for the given object. The TTL is
1315  kept unchanged.
1316
1317 == RC ==
1318
1319 The module `rsbac.rc` allows to manage RC Roles and RC Types.
1320
1321 === Type ===
1322
1323 `Type(..)`
1324
1325  This class is not meant to be instanciated by the user. Use the
1326  various `rcTypes` class attribute instead.
1327
1328 `__int__()`
1329
1330 `__long__()`
1331
1332  Cast the RC Type to the corresponding type ID. (But note that a RC
1333  type is fully qualified by a couple `(target,id)`. So the value
1334  returned is not sufficient to uniquely identify the RC type.)
1335
1336 `name`
1337
1338  This read/write property is the name of the RC type.
1339
1340 `needSecureDelete`
1341
1342  This read/write property is a boolean which indicate if secure
1343  deletion is required for objects with this type. Note that secure
1344  deletion is not guaranteed to work with usual file systems. Be
1345  careful before trusting the behavior of this feature.
1346
1347 `copyTo(dest)`
1348
1349  Copy all the attribute of the RC type to another RC type (existing or
1350  not) of ID `dest`.
1351
1352 `clone([name])`
1353
1354  Clone the RC type with an optional new name (otherwise the original
1355  name is also copied.) Returns the new RC Type.
1356
1357 `delete()`
1358
1359  Delete the RC type from the RSBAC system. Basically it only means
1360  that the type become unnamed.
1361
1362 === Role ===
1363
1364 `Role(id)`
1365
1366  Create an instance to represent the RC role with ID `id`.
1367
1368 `__int__()`
1369
1370 `__long__()`
1371
1372  Cast the instance to the RC role ID.
1373
1374 `id`
1375
1376  This read-only property is the ID of the RC role.
1377
1378 `name`
1379
1380  This read/write property is the name of the RC role.
1381
1382 `compatibility`
1383
1384  This attribute is a TTL dict-like variable which gives access to the
1385  role compatibility.
1386
1387 `adminRoles`
1388
1389  This attribute is a TTL dict-like variable which gives access to the
1390  list of RC roles that can administrate this RC role. FIXME.
1391
1392 `assignRoles`
1393
1394  This attribute is a TTL dict-like variable which gives access to the
1395  list of RC roles that.. FIXME.
1396
1397 `typeCompatibility`
1398
1399  This attribute is a dict-like variable which gives access to the
1400  permission for the RC role to a given RC type.
1401
1402 `defaultIndividualFdCreateType`
1403
1404  This attribute is a dict-like variable which gives access to the
1405  default RC type to use when creating object for a given RC type.
1406
1407 `bootRole`
1408
1409  This read/write property is a True if the RC role is a boot role and
1410  False otherwise.
1411
1412 `requireReauthentication`
1413
1414  This read/write property is a True if the RC role require to
1415  authenticate again when switching to another role (FIXME: or when
1416  switching to this RC role?) and False otherwise.
1417
1418 `adminType`
1419
1420  This read/write property is the type of administrator for this RC
1421  role. It's one of the constant defined by RSBAC (0 for "No Admin", 1
1422  for "Role Admin", 2 for "System Admin").
1423
1424 `defaultFdCreateType`
1425
1426 `defaultUserCreateType`
1427
1428 `defaultGroupCreateType`
1429
1430 `defaultProcessCreateType`
1431
1432 `defaultProcessChownType`
1433
1434 `defaultProcessExecuteType`
1435
1436 `defaultIpcCreateType`
1437
1438 `defaultUnixsockCreateType`
1439
1440  These eight attributes are dict-like variable which gives access to
1441  the corresponding RC type to use in the given context.
1442
1443 `copyTo(dest)`
1444
1445  Copy all the attribute of the RC role to another RC role (existing or
1446  not) of ID `dest`.
1447
1448 `clone([name])`
1449
1450  Clone the RC role with an optional new name (otherwise the original
1451  name is also copied.) Returns the new RC Role.
1452
1453 `delete()`
1454
1455  Remove the RC role from the RSBAC system.
1456
1457 The `rsbac.rc` module also provides some additionnal utility functions
1458 related to RC:
1459
1460 `grant(role, type, requests)`
1461
1462  Grant `requests` to the RC Role for the given RC Type. The TTL is
1463  kept unchanged.
1464
1465 `revoke(role, type, requests)`
1466
1467  Revoke `requests` to the RC role for the given RC type. The TTL is
1468  kept unchanged.
1469
1470 `findUnnamedRole(start=0)`
1471
1472  Search sequentially for a new unused RC role ID, starting from
1473  `start`.
1474
1475 `findUnnamedRoles(n=1, start=0)`
1476
1477  Search sequentially for a set of unused RC role ID up to `n` items,
1478  starting from `start`.
1479
1480 `findRole(name,[default])`
1481
1482  Find a role with the given name. If several roles share the same
1483  name, the one with the lowest ID is returned. If no roles is found,
1484  then default is returned if specified, otherwise an error of type
1485  `IndexError` is raised.
1486
1487 `findUnnamedType(target,start=0)`
1488
1489  Search sequentially for a new unused RC type ID, starting from
1490  `start`.
1491
1492 `findUnnamedTypes(target,n=1, start=0)`
1493
1494  Search sequentially for a set of unused RC type ID up to `n` items,
1495  starting from `start`.
1496
1497 `findType(target,name,[default])`
1498
1499  Find a type with the given name for the given target. If several
1500  types share the same name, the one with the lowest ID is returned. If
1501  no types is found, then default is returned if specified, otherwise
1502  an error of type `IndexError` is raised. See example section.
1503
1504 `newRole(name, start=0)`
1505
1506  Create a new RC role with the given name, whose ID is searched by
1507  starting from `start`.
1508
1509 === Pseudo roles and types ===
1510
1511 There are also predefined RC roles and RC types in the modules
1512 `rc.pseudoRoles` and `rc.pseudoTypes`:
1513
1514 --- RC pseudo roles ---
1515 -=-=-
1516 >>> dir( rsbac.rc.pseudoRoles )
1517 ['__doc__', '__name__',
1518  'inherit_parent', 'inherit_process',
1519  'inherit_up_mixed', 'inherit_user',
1520  'use_force_role']
1521 >>> rsbac.rc.pseudoRoles.use_force_role
1522 <RC PseudoRole [-5] use_force_role>
1523 -=-=-
1524
1525 --- RC pseudo types ---
1526 -=-=-
1527 >>> dir( rsbac.rc.pseudoTypes )
1528 ['__doc__', '__name__',
1529  'inherit_parent', 'inherit_process',
1530  'no_chown', 'no_create', 'no_execute',
1531  'use_fd', 'use_new_role_def_create']
1532 >>> rsbac.rc.pseudoTypes.use_fd
1533 <RC PseudoType [-7] use_fd>
1534 >>> rsbac.rc.findType( rsbac.objects.FD , 'foo' )
1535 <RC Type [14:99] 'foo'>
1536 >>> rsbac.rc.findType( rsbac.objects.FD , 'bar' )
1537 IndexError: Type named 'bar' not found
1538 -=-=-
1539
1540 All theses instances of `Role` and `Type` are singleton, meaning that
1541 you can compare them safely with the `is` operator.
1542
1543 == Jail ==
1544
1545 The module `rsbac.jail` contains a single function:
1546
1547 `jail(path=None, ip=None, flags=None, max_caps=None, scd_get=None, scd_modify=None)`
1548
1549  Every arguments are optional.
1550
1551  `path` is the path to set the chroot environment. If None, then no
1552  chroot is performed.
1553
1554  `ip` is either None or an IP address (as a string or a 4-tuple of
1555  integers). (FIXME: not implemented as described, the current jail
1556  function expect an integer.) If None, then no IP restriction is
1557  applied. Otherwise, the processes inside the jail can only bind to
1558  the specified IPv4 address.
1559
1560  `flags` is a `JailFlags` instance (or equivalent integer.) If None,
1561  then all flags are cleared.
1562
1563  `max_caps` is a `CapVector` instance (or equivalent integer.) If
1564  None, then all flags are cleared.
1565
1566  `scd_get` and `scd_modify` are `ScdVector` instances (or equivalent
1567  integers.) If None, then all flags are cleared.
1568
1569  The function returns the ID of the newly created jail.
1570
1571 = Examples =
1572
1573 == Module ==
1574
1575 While testing, turn off softmode, but take care to turn on AUTH
1576 softmode before.
1577
1578 -=-=-
1579 >>> rsbac.module.SOFTMODE
1580 <Module SOFTMODE [Enabled]>
1581 >>> rsbac.module.AUTH
1582 <Module AUTH [Enabled]>
1583 >>> rsbac.module.AUTH.softmode = True
1584 >>> rsbac.module.SOFTMODE.enabled = False
1585 >>> rsbac.module.SOFTMODE
1586 <Module SOFTMODE [Disabled]>
1587 >>> rsbac.module.AUTH
1588 <Module AUTH [Enabled,Softmode]>
1589 -=-=-
1590
1591 == UM ==
1592
1593 --- Starting the session ---
1594 -=-=-
1595 >>> from rsbac import um
1596 -=-=-
1597
1598 --- We start with no users and no groups ---
1599 -=-=-
1600 >>> um.users
1601 {}
1602 >>> um.groups
1603 {}
1604 -=-=-
1605
1606 --- Add an user 'secoff' with UID 400 and password 'foobar' ---
1607 -=-=-
1608 >>> secoff = um.addUser( 'secoff' , 400 , 'foobar' )
1609 >>> secoff.fullname = 'RSBAC security officer'
1610 >>> secoff
1611 <UM User [400] 'secoff'>
1612 >>> um.users
1613 {400: <UM User [400] 'secoff'>}
1614 -=-=-
1615
1616 --- Add a group 'secoff' with GID 400 and set it to the 'secoff' user ---
1617 -=-=-
1618 >>> secoffGroup = um.addGroup( 'secoff' , 400 )
1619 >>> secoff.group = secoffGroup  # or secoff.group = 400
1620 -=-=-
1621
1622 --- Add two test accounts 'foo' and 'bar' ---
1623 -=-=-
1624 >>> foo = um.addUser( 'foo' )
1625 >>> bar = um.addUser( 'bar' )
1626 >>> um.users
1627 {400: <UM User [400] 'secoff'>, 2000: <UM User [2000] 'foo'>, 2001: <UM User [2001] 'bar'>}
1628 -=-=-
1629
1630 --- Add two test groups 'g1' and 'g2' ---
1631 -=-=-
1632 >>> g1 = um.addGroup( 'g1' )
1633 >>> g2 = um.addGroup( 'g2' )
1634 -=-=-
1635
1636 --- Set group and extra groups ---
1637 -=-=-
1638 >>> foo.group = g1
1639 >>> bar.group = g2
1640 >>> bar.groups.add( g1 )
1641 >>> g1.members
1642 (<UM User [2000] 'foo'>,)
1643 >>> g1.extraMembers
1644 (<UM User [2001] 'bar'>,)
1645 -=-=-
1646
1647 --- Change user TTL ---
1648 -=-=-
1649 >>> print foo.ttl
1650 True               # unlimited TTL
1651 >>> foo.ttl = 10   # set it to 10s
1652 [..wait..]
1653 >>> foo
1654 <UM User [2000] (9s) 'foo'>
1655 [..wait..]
1656 >>> foo
1657 <UM User [2000] (2s) 'foo'>
1658 [..wait..]
1659 >>> foo
1660 <UM User [2000] (?) undefined>
1661 -=-=-
1662
1663 --- Remove the test accounts and test groups ---
1664 -=-=-
1665 # foo already deleted because of the end of TTL
1666 >>> bar.delete()
1667 >>> g1.delete()
1668 >>> g2.delete()
1669 >>> foo
1670 <UM User [2000] (?) undefined>
1671 >>> g1
1672 <UM Group [2000] (?) undefined>
1673 -=-=-
1674
1675 --- Final state ---
1676 -=-=-
1677 >>> um.users
1678 {400: <UM User [400] 'secoff'>}
1679 >>> um.groups
1680 {400: <UM Group [400] 'secoff'>}
1681 -=-=-
1682
1683 == File flags ==
1684
1685 -=-=-
1686 >>> from rsbac import FileFlags
1687 >>> from rsbac.objects import Directory
1688 >>> Directory( '/tmp/foo' ).ff_flags
1689 FileFlags('add_inherited')
1690 >>> Directory( '/tmp/foo' ).eff_ff_flags
1691 FileFlags()   # no effective flags
1692 >>> Directory( '/tmp/foo' ).ff_flags = FileFlags( 'no_delete_or_rename' )
1693 >>> Directory( '/tmp/foo' ).ff_flags
1694 FileFlags('no_delete_or_rename')  # add_inherited was removed too
1695 >>> Directory( '/tmp/foo' ).eff_ff_flags
1696 FileFlags('no_delete_or_rename')
1697 -=-=-
1698
1699 = Tools =
1700
1701 To make it easier to figure what I set in RSBAC, I started to build a
1702 tool similar to `ls` and to `find`.
1703
1704 -=-=-
1705 # sec find /tmp --rc-type 17
1706 /tmp/foo/bash
1707 # sec ls -A --rc --ff /tmp/foo
1708 !17 !17 f -------I-->----------   ????-??-?? ??:?? bash
1709   0   m f ------N--->------N--- 0 2006-10-25 23:50 baz 
1710   0   m f -------I-->---------- 8 2006-10-26 10:40 bla 
1711   0   m f ------NI-->------N--- 0 2006-10-25 20:52 foo2
1712   0   m f -------I-->---------- 0 2006-10-26 10:40 ick 
1713 -=-=-
1714
1715 The `--rc` and `--ff` specify which type of information to
1716 display. There is a flag for each RSBAC module that make sense for
1717 file objects.
1718
1719 The `--rc` option display RC attributes, while `--ff` display FF
1720 attributes (file flags.)
1721
1722 In the example above, the first 3 columns are the RC attributes:
1723
1724  * The first column is the RC type of the file. A `!` mean that it is
1725  the real value, while no `!` mean that the value is inherited.
1726
1727  * The second column is the RC forced type. Likewise, a `!` mean that
1728  it is the real value. For special role, an abbreviation is
1729  displayed. `m` is for mixed inheritance, `p` for process inheritance
1730  and `u` for user inheritance.
1731
1732  * The third column is the RC initial type. The `f` mean to use the
1733  forced type.
1734
1735 Then come a big column to represent the FF flags. The column has 2
1736 parts. The part before the `>` character is the real file flags, while
1737 the part after is the effective flags. Each flags is represented by a
1738 letter, as follow:
1739
1740 | *Letter* | *Flags*               |
1741 | `r`      | `read_only`           |
1742 | `x`      | `execute_only`        |
1743 | `s`      | `search_only`         |
1744 | `w`      | `write_only`          |
1745 | `S`      | `secure_delete`       |
1746 | `X`      | `no_execute`          |
1747 | `N`      | `no_delete_or_rename` |
1748 | `I`      | `add_inherited`       |
1749 | `a`      | `append_only`         |
1750 | `M`      | `no_mount`            |
1751
1752 So, in the example, we can see that the `bla` file have no flags
1753 except `add_inherited`, and there is effective flags.
1754
1755 FIXME: Choose only lower case letters, then represent inherited flag
1756 by an upper case, thus reducing the display of the file flags.
1757
1758 = Issues =
1759
1760  * `errno` is retrieved directly from the `libc` through ctypes. It is
1761  not portable against another libc. See the `rsbac.platform` module.
1762
1763  * MAC and PM supports are missing.
1764
1765  * Lot of things are created on module import, which render loading
1766  the rsbac module rather slow (300ms on a 1GHz machine.)
1767
1768 = Authors =
1769
1770  * Frédéric Jolliton ([pyrsbac@tuxee.net mailto:pyrsbac@tuxee.net])