Move READMEs etc back into muse2, create README link.

1 files changed, 244 insertions, 0 deletions

diff --git a/muse2/SECURITY b/muse2/SECURITY
new file mode 100644
index 00000000..e0fa68a5
--- /dev/null
+++ b/muse2/SECURITY
@@ -0,0 +1,244 @@
+MusE Security Information
+=========================
+
+In order to operate reliably at low latencies, MusE needs root privileges.
+For a stand-alone computer in a home environment, this is not a problem.
+However, on networked machines with multi-user access, there are some security
+issues to be aware of.
+
+
+Why does MusE require root privileges ?
+---------------------------------------
+
+1.
+MusE must set the real time clock (/dev/rtc/) to a higher rate in order to get 
+a more precise timing source than the standard setting would allow.
+For this task, it is *not* sufficient to alter the permissions or group of
+/dev/rtc. You need root access.
+
+2.
+The MusE audio threads must acquire real-time scheduling to perform with low
+latency and free of dropouts. Since this could be misused for a local
+denial-of-service attack (you can hog 100% cpu with a real-time task, thus
+effectively making the system unusable), only root is allowed to do that.
+
+
+Do I need to be root to run MusE ?
+----------------------------------
+
+No. You should not do normal work as root. Use the root login exclusively for
+administrative tasks. You can run MusE as a normal user, provided you have set
+the *suid bit*.
+This is done automatically when you build and install MusE.
+
+
+How does this "suid bit" thing work ?
+--------------------------------------
+
+Normally, when a program is started, it gets the user and group id of the user
+who started it, and thus has the same permissions as the user. It can read and
+write the same files and use the same devices.
+
+Some applications need higher privileges to perform certain tasks, but must be
+available to normal users. To accomplish this, UNIX-like systems have the
+concept of the "effective user id".
+
+That means you can start a process, but the effective user id will be someone
+else's, most likely that of the root user. You can recognize such programs by
+the suid (for set-user-id) bit in their permissions.
+
+For example, when you do
+
+	#ls -l /bin/ping
+
+you will see something like
+
+	-rwsr-xr-x    1 root     root        20908 Feb 27  2001 /bin/ping .
+
+This tells you it's a normal file (the first dash), it is readable and writable
+by the owner (root) and has the owner's suid bit set (the letter "s").
+You may invoke it as a normal user, but the program will have root permissions
+while it runs.
+
+(Btw, there is also an sgid (set-group-id) bit, which allows a program to be run
+with the permissions of the group it is owned by. This can be used for
+finer-grained access control to some programs but is rarely used in practice.)
+
+(Btw2, the letter "s" actually means both "executable" AND "set-{user,group}-id".
+A capital "S" stands for "set-uid" without the execution privilege, which also
+very rarely seen on real systems.)
+
+
+What is the problem with suid programs ?
+----------------------------------------
+
+suid programs are safe as long as you can be sure they do only the job they were
+written to do. For instance, you certainly want users to be able to do a ping,
+but you wouldn't want them to wipe out the system disk while doing it.
+
+Unfortunately, there is a very common vulnerability in many programs called a
+buffer overflow, which allows an attacker to spawn a shell from within a suid
+program that inherits the permissions, giving him or her root access to the
+entire system.
+This exploit is fairly easy for an experienced attacker. All that's needed is
+the compiled equivalent of the C expression execve("/bin/sh"), which can be
+inserted into the running program whenever it does not check the length of user
+input properly, by overflowing a buffer and thus overwriting a part of
+the program code with the shell exploit code.
+
+The more complex a program becomes, the more likely buffer overflow
+vulnerabilities slip in.
+
+If you are interested in details of such attacks, I recommend AlephOne's paper
+"Smashing the stack for fun and profit", to be found in Issue 49 of Phrack
+Magazine (http://www.phrack.com/show.php?p=49&a=14).
+
+
+Does MusE have buffer-overflow vulnerabilities ?
+------------------------------------------------
+
+It may. But even if it had not, it is good practice to assume it does.
+As soon as you are in a security-critical environment, you should treat all suid
+programs with extra care unless they are proven to be secure.
+
+This is a gruesome and boring task, and we all want Werner to concentrate on
+cool new features rather than digging through the code to fix loopholes that
+aren't even a problem for 99% of the MusE users.
+MusE does not need to be as secure as server daemons. It is intended for home
+use in a trusted environment.
+If you run MusE on your company's primary DNS server, it's your fault.
+
+But even home machines can become targets for intruders the moment they connect
+to the internet. Since almost all of the machines than run MusE are occasionally
+used to surf the web, it  might be worth taking a few precautions.
+
+
+What can I do to minimize the risk of a suid program ?
+------------------------------------------------------
+
+By default, Werner drops the root privileges in MusE's GUI thread - only the
+audio threads keep it. This rules out many possible exploits, since GUI code is
+usually the hardest to make secure.
+
+
+As a further very simple yet effective security precaution, you can create a
+group of trusted users, and give only this group access to critical suid
+programs. For example, you might create a group called musers, of which you and
+your best friend are members. Then you can set the muse binary as follows:
+
+	#chown root:musers muse
+	#chmod 4750 muse
+	#ls -l muse
+	-rwsr-x---    1 root     musers     20930049 Aug 28 19:34 muse
+
+Now only members of the group musers can use MusE, Joe Random Hacker can not.
+(However, if your account is hacked, MusE can then be exploited to gain root,
+but hey...)
+
+Additionally, you can use "givertcap" as described in the next section.
+
+
+What is givertcap and how do I use it ?
+---------------------------------------
+
+"givertcap" (give real-time capabilites) is a small wrapper written by Tommi
+Ilmonen.
+When enabled, it is executed by MusE and gives to it just the capabilities
+needed to set the timer and get real-time scheduling, but not the full set of 
+root privileges. This greatly reduces the amount of damage that can be done.
+
+However, it is not used by default, since it requires a kernel modification.
+
+To enable givertcap, simply call ./configure --enable-rtcap before compiling.
+(The givertcap code is part of the MusE distribution.)
+
+With current kernels, you need to apply a little patch to the kernel headers:
+Go to /usr/src/linux/include/linux (or wherever you have your kernel sources)
+and in the file capability.h change the line
+
+	#define CAP_INIT_EFF_SET    to_cap_t(~0&~CAP_TO_MASK(CAP_SETPCAP))
+to
+	#define CAP_INIT_EFF_SET    to_cap_t( ~0 )
+
+and the line
+
+	#define CAP_INIT_INH_SET    to_cap_t(0)
+to
+	#define CAP_INIT_INH_SET    to_cap_t( ~0 )
+.
+
+You must then recompile your kernel.
+
+In this setup, givertcap must be set suid root, but MusE can be run with normal
+privileges.
+Now all possible suid exploits described above apply to givertcap, but since it
+is such a tiny program, it can be checked for exploits far more easily and can
+be considered reasonably secure.
+
+Unfortunately, givertcap can be used to grant real-time privileges to *any*
+program, so it's an easy way to have the machine clogged up by a malicious user
+who might run bogus tasks at 100% system usage.
+Therefore, you *must* create an extra group for it (called "musers" in this
+example):
+	# chown root:musers givertcap
+	# chmod 4750 givertcap
+Do not forget to remove the suid bit on muse afterwards by doing
+	# chmod 755 muse
+.
+
+For more information about givertcap and kernel capabilites, see
+http://www.tml.hut.fi/~tilmonen/givertcap/
+and
+http://ftp.kernel.org/pub/linux/libs/security/linux-privs/kernel-2.4/capfaq-0.2.
+txt.
+
+
+
+Further reading:
+================
+
+General Linux system security:
+http://linuxdoc.org/HOWTO/Security-Quickstart-HOWTO/
+http://linuxdoc.org/HOWTO/Security-HOWTO.html
+
+Secure Linux programming:
+http://linuxdoc.org/HOWTO/Secure-Programs-HOWTO/
+
+Permissions:
+man chmod
+man chattr
+
+givertcap:
+http://www.tml.hut.fi/~tilmonen/givertcap/
+
+An alternative approach, using a kernel module:
+http://arctrix.com/nas/linux/capwrap.tar.gz
+
+Kernel capabilites:
+http://ftp.kernel.org/pub/linux/libs/security/linux-privs/kernel-2.4/capfaq-0.2.
+txt
+
+Adding capability flags to ELF files:
+http://atrey.karlin.mff.cuni.cz/~pavel/elfcap.html
+
+
+Buffer Overflow attacks:
+"Smashing the stack for fun and profit" by AlephOne 1996, published in
+Phrack magazine, issue 49
+http://www.phrack.com/show.php?p=49&a=14
+
+In the MusE source, app.cpp contains the invocation of givertcap and the
+dropping of the suid privileges: grep for "getCapabilities" and "setuid" to see
+how it's done.
+
+________________________________________________________________________________
+
+
+This document was written by Jörn Nettingsmeier
+<nettings@folkwang-hochschule.de>
+Corrections and improvements welcome.
+
+Thanks to Werner Schweer and Tommi Ilmonen for answering my questions.
+
+Last updated 02/22/2002.
+