Release of digsig 1.3.2
======================= 

Overview
========

This kernel module checks signature of a binary before running it.
The main functionality is to insert digital signatures inside the ELF
binary and verify this signature before loading the binary. It is
based on the LSM hooks.


Our approach has been to use the existing solutions like gpg and bsign
rather than reinventing the whole thing from scratch.

However, in order to reduce the overhead in the kernel, we took only
the minimum code necessary from GPG. We took only the MPI (Multi
Precision Integer) source code and the RSA crypto source code. This
helped much to reduce the amount of code imported to the kernel in
sourc code of the original (only 1/10 of the original gnupg 1.2.2
sourc code has been imported to the kernel module). On the other hand,
we avoided OpenSSL source code for the fact that the licensing was not
clear to us. We did some tests at user level and found out that
OpenSSL is 4 times faster than GPG regarding RSA verification. As a
future direction, we plan to clarify this licensing issue and use (if
possible) OpenSSL instead of GPG.

REQUIREMENTS
=============

To compile:
	you need a Linux kernel 2.6.8 or greater
	your kernel must be compiled with:
		CONFIG_SECURITY=Y
		CONFIG_SHA1=Y (or m, but then load the sha1 module first
				before DigSig !).
	you do NOT need DSI: DigSig is an independant project
		though it historically uses DSI's CVS.

To run:
	bsign 0.4.5 - see http://packages.qa.debian.org/b/bsign.html
	
	GPG : a version that supports RSA key generation (for instance,
		greater than 1.2.2) - see http://www.gnupg.org
	
	module-init-tools: required for 2.6.x kernels. Replaces the old
		/sbin/lsmod, /sbin/insmod etc 
		- see http://www.kernel.org/pub/linuxkernel/people/rusty/modules	
	

COMPILING
=========== 

To compile Digsig from the directory you installed Digsig do: 
[root@digsig]# ./digsig.init compile

You can set different compilation arguments in Makefile: 

-DDIGSIG_DEBUG: When this variable is set Digsig will run in
debug mode.  In debug mode, DigSig lets unsigned binaries run. This
state is ideal to test DigSig, and also list the binaries you need to
sign to get a fully operational system.

 -DDSI_EXEC_ONLY: DigSig normally verifies the signatures for
 executable binaries and shared librairies. If you wish for
 performance reason or whatever other reason to only verify the
 signatures for executable binaries set this variable. This options
 have been removed du to insecurity.
 
 -DDIGSIG_LOG: This activates the logging. Be careful about the amount
 of log to be generated at run time. 

MODULE PARAMETERS
===================

Digsig currently accepts a single optional parameter.  If it is
loaded with digsig_max_cached_sigs=<int>, then it will cache up to
<int> signature validations.  The default value is 512.

To enable this parameter using digsig.init, you would change the
module insertion line from

  /sbin/insmod -f ./digsig_verif.ko || exit 1
to
  /sbin/insmod -f ./digsig_verif.ko digsig_max_cached_sigs=1024 || exit 1

Caching support 
================ 

From release 1.2, the caching of signatures at kernel level is supported. 
Once the signature of a binary is verified, its signature is cached in the 
kernel memory. Therefore, there is no need for signature verification in 
subsequent calls to this binary. 
When a binary file is modified, the corresponding cache entry in the memory 
is invalidated.   

Revocation support 
====================

As of release 1.3, revocation of signatures is supported.  If a library
or binary is found to have a vulnerability, you no longer want digsig to
allow that file to be loaded.  By revoking the signature, you tell
digsig that although the file's signature was in fact calculated with
the valid private key, it should nevertheless refuse to load this
binary.

You can revoke a signature as follows.  Assume we want to revoke the
signatures for sshd and ftpd.  Use tools/extract_sig (use a patched
version of bsign for now) to extract the signature of each file into
separate files under /etc/digsig_revoked_keys/.  For instance:

$ ./tools/extract_sig /usr/sbin/sshd /etc/digsig_revoked_keys/sshd_v3.5p1
$ ./tools/extract_sig /usr/sbin/in.ftpd /etc/digsig_revoked_keys/ftpd

Now the startup script ./digsig.init will automatically copy these files
into /sys/digsig/digsig_revoke after module insertion and before the
public key is committed.  Once digsig starts enforcing, no more
signature revocations are accepted.  Any attempts to execute the revoked
versions of /usr/sbin/sshd or /usr/sbin/in.ftpd be refused.

To DISABLE revocation, remove the "-DREVOCATION" flag from EXTRA_CFLAGS
in ./Makefile.

A Very simple scenario to show how to use it  
=======================================

1) Generate gpg key and export your public key in order to use it for
 signature verification.
 
$gpg --gen-key 

=> careful generate RSA key 

$gpg --export >> my_public_key.pub 

2) Sign your binaries using Bsign 

Before using bsign to sign all your binaries, try out with a simple
example.

$cp `which ps` ps-test
$bsign -s ps-test // sign the binary 
$bsign -V ps-test // be sure that the signature is valid  

Provided that works, sign all your binaries and libraries using bsign.
Consult section 2 ("Usage") of the bsign README for helpful hints.

3) Make the digsig module 

From ./digsig, do make -C /usr/src/linux-2.5.66 SUBDIRS=$PWD modules. You need rw acess to /usr/src/linux-2.5.66. 

CAREFULL: we advice you to compile the module in debug mode at your
first tries (see -DDIGSIG_DEBUG in the Makefile). In
this mode, the module verifies the signatures but does not enforce the
security (if not any signature present in your binary, you'll have a
message in /var/log/messages but the execution is not
aborted.). However, the execution of the binaries with invalid
signatures is aborted. Once, you're sure of your binary signature
procedure you can recompile the whole on non-debug mode.

4) load digsig, use the public key exported in step 1 as argument 

Be sure that sysfs is mounted in /sys or the key won't be loaded.
You can mount sysfs with this command :
mount -t sysfs sysfs /sys


root@colby digsig-dev]# ./digsig.init start pubkey.pub
Loading Digsig module.
Making device for communication with the module.
Loading public key.
Done.


5) In debug mode: 

$ps 
$./ps-test 

$tail -f /var/log/messages 
Sep 16 15:49:13 colby kernel: DIGSIG MODULE - binary is /bin/ps
Sep 16 15:49:16 colby kernel: DIGSIG MODULE - binary is ./ps-makan
Sep 16 15:49:16 colby kernel: DIGSIG MODULE - dsi_bprm_compute_creds: Found signature section
Sep 16 15:49:16 colby kernel: DIGSIG MODULE - dsi_bprm_compute_creds: Signature verification successful

6) In restrictive mode, normal mode 

You need to use bsign to sign all binaries that you want to run in
normal mode. 

// signed binary 
[lmcmpou@reblochon lmcmpou]$ ps
  PID TTY          TIME CMD
 6897 pts/2    00:00:00 bash
 6941 pts/2    00:00:00 ps

// not signed binary 
[lmcmpou@reblochon lmcmpou]$ ./ps-makan-1
bash: ./ps-makan: cannot execute binary file

// binary with wrong signature 
[lmcmpou@reblochon lmcmpou]$ ./ps-makan-2 
bash: ./ps-makan-colby: Operation not permitted

7) Unload the module. 

[root@colby digsig-dev]# ./digsig.init stop
Unloading Digsig.

Performances
=============== 

We have done some benchmarks without caching. Remark that 
the performance impact is small after the first load of the binary as  
the signature of the file is cached in the memory.   

Macro tests: 

We ran lmbench on a Pentium IV, 2.4 GHz, 500 mega bytes of memory,
running Linux 2.5.66. Our benchmarks show that the execution time
(exec function call) multiplies by a factor of 4 when the module is
loaded (no changes for fork call, as the binary is not loaded into
memory).

Micro tests with gnupg: 

We present below the overhead at kernel-level for checking the
signature.

In below, we give the performances for DigSig running with the
variable DSI_EXEC_ONLY set. This means that we only measure the time
for verifying the signature of the executable binary and do not take
into accoubt the time necessary to verify the signatures for the
shared libraries. 

Always on a Pentium IV, 2.4 GHz, 500 mega bytes of memory, running
Linux 2.5.66: 

+-----------+---------+----------+
| Binaries  |   Size  |  GnuPG   |
+-----------+---------+----------+
|        ls |   68230 |  1.61765 |
|        ps |   70337 |  1.67742 |
|   busybox |  248801 |  4.66666 |
|       cvs |  672532 | 11.53571 |
|       vim | 1894305 | 31.25000 |
|     emacs | 4093614 | 67.41176 |
+-----------+---------+----------+

Time is in jiffies -> 1 jiffies = 1ms


Linear regression
time = 1.393899E-5 * size + 0.815081 

Acknowledgements
================= 

This work has been done by (alphabetical order) 

A Apvrille ([email protected]),
D Gordon ([email protected]),  
S Hallyn ([email protected]),
M Pourzandi ([email protected]),
V Roy ([email protected]).

Thanks to Radu Filip who has done the initial analysis. 
Thanks to Marc Springer who helped us with the use of Bsign. 
Thanks to Chris Wright for his helpful input and comments on DigSig.