Commit 6e53d966 authored by Lukas Braun's avatar Lukas Braun Committed by Simon Ruderich
Browse files

slsm: documentation

parent d1e26f6f
# SLSM #
SLSM is a simple, path-based security module.
It's main goals are to be
* distribution-independent
* straight-forward to use on desktops
* simple in implementation
Some common use-cases are
* restrict access to a file for all programs, with exceptions;
e.g. only ssh-add can read your private keys
* apply restrictions incrementally to an existing, moving system
# Overview #
In SLSM, programs are identified by their path in the filesystem (symlinks are
resolved first). This means `exec` changes permissions!
Access rules are stored in a tree structure resembling the filesystem.
At each node (corresponding to a directory entry), rules matching either all
or one specific program are specified.
To check access to a file, the tree is traversed from the root. At each node,
the last rule (in the order they were inserted) matching the executing program
is remembered. The last match determines the permissions the program has for
this file.
Rules consist of the program they apply to and a combination of UNIX-like `rwx`
bits (`x` is not neccessary to `cd`) and a set of SLSM-specific flags:
* A rule with the `exact` flag applies only if the program tries to access the
exact node at which the rule is placed.
* The `confine` flag prevents a process from gaining new permissions via `exec`.
* If a program `A` execs program `B` and the `inherit` flag applies for `A` at
`B`, the process inherits `A`s permissions. `B` is then confined to those
permissions in the above sense.
# Interface #
The securityfs file `slsm/profiles` expects rules in the format `i=content\0`,
where `i` is one of the flags listed below and `content` is its value.
Multiple rules are separated by another 0-byte.
Currently available flags are
* `p` the absolute path the rule should reside at
* `m` bit mask indicating the access mode (read is 4, write is 2, execute is 1)
* `a` the absolute path to the program this rule should apply to (optional)
* `f` SLSM-specific flags described above, `inherit` is 1, `confine` is 2,
`exact` is 4
# Examples #
## Protecting SSH private keys ##
For convenience, we store all our private keys in a separate directory
`~/.ssh/private` and want to prevent all programs except `/usr/bin/ssh-add`
from reading the files contained therein, but allow listing the keys:
1. shut everyone out:
p=/home/user/.ssh/private\0m=0\0\0
2. but allow everyone to list the directory:
p=/home/user/.ssh/private\0m=4\0f=4\0\0
3. allow `ssh-add` to read file contents:
p=/home/user/.ssh/private\0m=4\0a=/usr/bin/ssh-add\0\0
To apply this setup, run something like the following:
printf 'p=/home/user/.ssh/private\0m=0\0\0p=/home/user/.ssh/private\0m=4\0f=4\0\0p=/home/user/.ssh/private\0m=4\0a=/usr/bin/ssh-add\0\0' >/sys/kernel/security/slsm/profiles
## Restricting a media player ##
Our media player `/usr/bin/mpv` should be able to play files from `~/media`,
read its config from `~/.config/mpv` and write to `~/.config/mpv/watch_later`,
but otherwise access as few files as possible in the user's home and `/tmp`.
It should also not be able to gain further permissions by execing.
1. hands off `/tmp`
a=/usr/bin/mpv\0p=/tmp\0m=0\0\0
2. hands off `/home`
a=/usr/bin/mpv\0p=/home\0m=0\0\0
3. read `~/media`, `~/.config/mpv` and `~/.Xauthority`
a=/usr/bin/mpv\0p=/home/user/media\0m=4\0\0
a=/usr/bin/mpv\0p=/home/user/.config/mpv\0m=4\0\0
a=/usr/bin/mpv\0p=/home/user/.Xauthority\0m=4\0\0
4. read and write to `~/.config/mpv/watch_later`
a=/usr/bin/mpv\0p=/home/user/.config/mpv/watch_later\0m=6\0\0
5. set the `confine` flag
p=/usr/bin/mpv\0m=5\0f=2\0\0
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment