Update NEWS and initscript/README.stap-server with details of changes

due to recent commits.

2 files changed, 142 insertions, 1 deletions

diff --git a/NEWS b/NEWS
index ef3481fd..efa3542c 100644
--- a/NEWS
+++ b/NEWS
@@ -1,8 +1,56 @@
 * What's new
 
+- If NSS is available, the uprobes module
+  (<prefix>/share/systemtap/runtime/uprobes.ko where <prefix> is the location
+  where systemtap is installed), is now digitally signed
+  when it is built. For root, the signing certificate used is
+  <prefix>/etc/systemtap/ssl/server/stap.cert. For other users, the certificate
+  used is ~<user>/.systemtap/ssl/server/stap.cert. If the signing certificate
+  does not exist, one will be automatically created first.
+
+  EFFECT: Members of the group stapusr will be unable to load the uprobes
+        module unless the builder's certificate has been authorized as a
+	trusted signer. To do this the sysadmin must run the following command
+	as root:
+
+		<prefix>/bin/stap-authorize-signing-cert <certfile>
+
+	where <certfile> is the signing certificate of the builder, as
+	described above. This need be done only once for each trusted
+	builder and can be done even before the uprobes module is built,
+	provided the builder already has a signing certificate. Any user,
+	including root, can create their signing certificate by running the
+	command
+
+		<prefix>/bin/stap-gen-cert
+
+  IN PARTICULAR: Sysadmins should authorize the certificates of root. If
+	the stap-server service (see below) is enabled, sysadmins should
+	authorize the certificate of the stap-server service
+	(see initscript/README.stap-server for details).
+
+- When the systemtap-server rpm is installed, the build directory for the
+  uprobes module (/usr/share/systemtap/runtime) is now writable by the
+  'stap-server' group. All of the files generated when building the uprobes
+  module are also writable by members of stap-server. This allows systemtap 
+  compile servers started by the stap-server initscript (see below) to build
+  or rebuild the uprobes module, if necessary.
+
+- The loading of signed modules by staprun is no longer allowed for ordinary,
+  unprivileged users. This means that only root, members of the group 'stadev'
+  and members of the group 'staprun' can load systemtap modules using staprun,
+  stap or stap-client. Previously other users could load the uprobes
+  module and systemtap script modules which were signed by a trusted signer.
+
+  IN PARTICULAR: Ordinary, unprivileged users can no longer load the signed
+	modules generated using stap-client with the --unprivileged option.
+	Users must now be root or a member of stapusr or stapdev in order to
+	use this feature.
+
 - The stap-server initscript is available. This initscript allows you to
   start systemtap compile servers as a system service and to manage
-  these servers as a group or individually.
+  these servers as a group or individually. The stap-server initscript is
+  installed by the systemtap-server rpm.
   See initscript/README.stap-server for details.
 
 - Any output line that starts with "ERROR", as in error("foo"), will
diff --git a/initscript/README.systemtap b/initscript/README.systemtap
index 5c6cac15..ebce285e 100644
--- a/initscript/README.systemtap
+++ b/initscript/README.systemtap
@@ -9,6 +9,7 @@ INDEX
 3. Files
 4. Configuration Format
 5. How to use
+6. Authentication and Authorization
 
 1. Introduction
 ===============
@@ -353,3 +354,95 @@ script2_REQ=script1
  # vi /etc/systemtap/config
  AUTOCOMPILE=no
  ALLOW_CACHEONLY=yes
+
+6. Authentication and Authorization
+===================================
+
+6.1 Authentication
+6.1.1 SSL
+  The stap-server service must authenticate itself to each client using SSL
+  before it can be trusted.
+
+6.1.2 Unprivileged Users (Module Signing)
+  If the stap-server service will be used to service requests for unprivileged
+  users (the --unprivileged option) it must also sign compiled modules using
+  a trusted signing certificate.
+
+6.1.3 Certification
+  The same certificate is used for both of these purposes. It resides in the
+  file /var/lib/stap-server/.systemtap/ssl/server/stap.cert on the host which
+  is running the stap-server service.
+
+6.2 Authorization
+6.2.1 SSL
+  After starting the stap-server service for the first time, the sysadmin
+  must authorize the stap-server service as a trusted ssl. To
+  do this, on each host from which a client will access the stap-server service
+  (including localhost) run the following command as root
+
+	stap-authorize-server-cert <certfile>
+
+  where <certfile> is the stap-server certificate file from the host running the
+  stap-server service (see section 6.1.3).
+
+  This need only be done once on each client host for each stap-server service
+  to be accessed.
+
+  A client on a compatible host (or the same host) can now access the server
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }'
+
+  This should print 'Hello', provided the user has the authority to load the
+  resulting module on the client host.
+
+6.1.2 Unprivileged Users (Module Signing)
+  If the user on the client host is a an ordinary unprivileged user or a member
+  of the group stapusr, he will get an error when running the example above,
+  since he does not have authority to load the unsigned module returned by the
+  server. Howeverm if he is a member of the group stapusr and if he can get the
+  module signed by a trusted signer, he will be able to load it.
+
+  The server will sign the module if the --unprivileged option is specified by
+  the client:
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' --unprivileged
+
+  The server will now check that the script is safe for use by members of
+  stapusr (i.e. it doesn't do anything "dangerous") and, if so, will compile it
+  and sign it. However we will still get an error saying that the module
+  could not be loaded. This time it is because the server is not a trusted
+  signer.
+
+  In order to authorize the server as a trusted signer, on each host from which
+  a client will access the stap-server service (including localhost), run the
+  following command as root
+
+	stap-authorize-signing-cert <certfile>
+
+  where <certfile> is the stap-server certificate file from the host running the
+  stap-server service (see section 6.1.3).
+
+  This need only be done once on each client host for each stap-server service
+  to be accessed.
+  
+  The example above should now work as expected.   
+
+6.1.3 Ordinary Users
+  Ordinary users are users who are not root and not a member of either of the
+  groups stapdev or stapusr.
+
+  These users can still use the stap-server service to compile their scripts
+  but they can not load the resulting modules, even if the module is signed
+  by a trusted signer (server). The following will ask the server to compile
+  the script and return the resulting unsigned module.
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' -p4
+
+  The following will ask the server to check that the script is safe for use by
+  members of stapusr (i.e. it doesn't do anything "dangerous") and, if so, to
+  compile it and sign it.
+
+	stap-client -e 'probe begin { printf ("Hello\n"); exit (); }' -p4 --unprivileged
+
+  In both cases the name of the resulting module will be printed, but it will
+  not be loaded.