
                          ______  ______   ______  _____   
                         /_  __/ / ____/  / ____/ / ___/  
                          / /   / /      / /_     \__ \  
                         / /  _/ /___ _ / __/  _ ___/ /  
                        /_/  (_)____/(_)_/    (_)____(_) 
                     
                        TCFS v2.2.3  INSTALLATION GUIDE
                        Latest update: September 13, 1999

-------------------------------------------------------------------------------

 TCFS Installation guide
 -----------------------

Index:

- New features
- TCFS Requirements
- Installing TCFS on a client
- Installing TCFS on a server
- Mounting a TCFS filesystem on the client machine
- How to use a TCFS filesystem on a client
- Group sharing of files with TCFS

-> New Features

   This new version of TCFS features the TCFS Dynamic Encryption Module.
   For more infos on it read modules.html.

-> TCFS Requirements
 
 - Linux 2.0.x kernel
 - Module support (if you want to use TCFS as a module)
 - EXT2 filesystem (all Linux system should have it)
 - At least one NFS server and one client both running Linux 
	(client and server need not to be different machines)

-> Installing TCFS on a client
 
 1.
	Get all the packages you need. If this is the first time you install
 	TCFS, then get all the packages. You can do this by getting the file:
 		tcfs-2.2.3-distrib.tar.gz

 	1.A (only if you downloaded tcfs-2.2.3-distrib.tar.gz)
		Untar the distribution
				tar xfz tcfs-2.2.3-distrib.tar.gz
		wherever you want.

 2.
	Patch the current Linux kernel:
		gunzip path_to_tcfs_distrib/patch-linux-2.0.x.gz
		su root
		cd /usr/src
		patch -p0 < path_to_tcfs_distrib/patch-linux-2.0.x

 3.
	Untar TCFS source code:
		su root
		cd /usr/src
		tar xfz path_to_tcfs_distrib/tcfs-2.2.3.tar.gz

 4.
	Compile and install the TCFS library:
		cd  path_to_tcfs_distrib
		tar xfz tcfslib-0.3.1.tar.gz
		cd tcfslib-0.3.1
		make
		make install (as root)
	
	If you want to change the installation directory, edit and
	modify the top Makefile (tcfslib-0.3.1/Makefile).

	This step will also compile 'pam_tcfs.so'.
	To install it please refer to the directory PAMTCFS.
	
 5.
	Compile and install the TCFS utilities:
		cd  path_to_tcfs_distrib
		tar xfz tcfsutils-1.2.1.tar.gz
		cd tcfsutils-1.2.1
		make
		make install (as root)
	
	Edit the Makefiles if you have shadow password.

 6.
	Compile and install the modified mount (version 2.7g):
		cd  path_to_tcfs_distrib/contrib
		tar xfz mount-2.7l-tcfs.tar.gz
		cd mount-2.7l-tcfs
		make
		make install (as root)

	[If you downloaded only the patch, then you need to get the original
	source code of mount-2.7l and apply the patch by hand before
	compiling it.]

 7.
	Compile and install the modified e2fsprogs:
		cd  path_to_tcfs_distrib/contrib
		tar xfzv e2fsprogs-1.12-tcfs.tar.gz
		cd e2fsprogs-1.12-tcfs
		./configure
		make
		make install (as root)

	[If you downloaded only the patch, then you need to get the original
	source code of e2fsprogs-1.12 and apply the patch by hand before
	compiling it.]

 8.
 	Compile and install the modified shadow password suite
 	(version 980529):
		cd  path_to_tcfs_distrib/contrib
 		tar xfz shadow-980529-tcfs.tar.gz
 		cd shadow-980529-tcfs
 		./configure --with-libtcfs
 		make
 		make install (as root)

	[If you downloaded only the patch, then you need to get the original 
	source code of shadow-980529 and apply the patch by hand before
	compiling it. After applied the patch do a 'touch -r *'].

 9.
	Reconfigure and recompile your kernel with TCFS support.
	Remember that now the kernel is required to have the module support.

10.
	Compile and install the cipher module:
		cd path_to_tcfs_distrib/3desmodule
		make
		cp tcfs_default_module.o /lib/modules/<kernel-version>/fs

	[Here <kernel-version> is the version of the kernel just compiled
	with TCFS support e.g. 2.0.36.
	WARNING: we are assuming that the kernel sources are stored under
	/usr/src/linux. If this is not your case, please edit the Makefile
	of the module and modify the TOPDIR variable].

11.
	Reboot with the new kernel.

12.
	If you've compiled TCFS as a module, you can load it by saying 
		modprobe tcfs

	[The cipher module will be automatically loaded].


-> Installing TCFS on a server
 
 0.     Get the distribution file and untar it wherever you want.

 1.
	Compile and install the xattrd daemon:
		tar xfzv xattrd-2.1.tar.gz
		cd xattrd
		make
		make install (as root) 

 2.
	Run xattrd (and add it to your rc files):
		xattrd
 

-> Mounting a TCFS filesystem on the client machine
 
Suppose your server exports the  /exports dir, and suppose your client
wants to mount your_server_name:/exports on /mnt/your_mount_point.
Mount /mnt/your_mount_point using the following command:
 
	mount -t tcfs your_server_name:/exports /mnt/your_mount_point
            

-> How to use a TCFS filesystem on a client
 
 1. First make sure that /mnt/your_mount_point is mounted as described above. 
    If not, ask your superuser to mount it.
 2. Ask your superuser to create an entry for you in the TCFS key database
    (by executing the command '/usr/local/sbin/tcfsadduser').
 3. Generate a key for yourself by executing 'tcfsgenkey'.
 4. Execute the following steps for each non PAM session:
	- at the beginning execute 'tcfsputkey';
	  this pushes your key into the TCFS kernel module.
	  A good idea would be to add this command to your shell initialization
	  file.
	- at the end of the session execute 'tcfsrmkey';
	  this removes your key from the TCFS kernel module
	  (unless there are other active sessions using TCFS).
 5. Utilities lsattr and chattr list and set secure flags.


-> Group sharing of files with TCFS

Release 2.2 of TCFS includes the possibility of threshold sharing files
among users. Threshold sharing consists in specifying a minimum number of
members (the threshold) that need to be ``active'' for the files owned by
the group to become available. TCFS enforces the threshold sharing by
generating an encryption key for each group and giving each member of the
group a share using a Threshold Secret Sharing Scheme (see [1]). The group
encryption key can be reconstructed by any set of at least threshold keys.
A member of the group that intends to become active does so by pushing
her/his share of the group key into the kernel. The TCFS module checks if
the number of shares available is above the threshold and, if it is so, it
attempts to reconstruct the group encryption key. By the properties of the
Threshold Secret Sharing Scheme, it is guaranteed that, if enough shares are
available, the group encryption key is correctly reconstructed.
Once the group encryption key has been reconstructed, the files owned by the
group become accessible. Each time a member decides to become inactive, her
share of the group encryption key is removed. The TCFS module checks if the
number of shares available has gone under the threshold. In this case, the
group encryption key is removed from the TCFS module and files owned by the
group become unaccessible.
The current TCFS implementation of the group sharing facility requires each
memeber to trust the kernel of the machine that reconstructs the key to
actually remove the key once the number of active users goes below the
threshold. Future implementations will remove this requirement by performing
the reconstruction of the key in a distributed manner.

Setting up a TCFS group requires the following steps to be executed:

  1. The superuser creates a normal unix group; 
     editing /etc/group should be sufficient.

  2. The superuser creates a TCFS group executing the command:
           tcfsaddgroup -g group -m <number of members> -t <threshold>

     This utility asks for the usernames of the members of the TCFS group.
     For each member a share is created and encrypted with the user passwd
     and then is saved in the TCFS group key database.

  3. Create a directory on a TCFS filesystem owned by the group. Usual
     permission restrictions apply to the files in the directory. For
     example, the directory should be writeable if users are to create
     files.

  4. To become active, a member of a TCFS group pushes her share into the
     kernel. This can be accomplished by executing the command:
                              tcfsputkey -g <group>

     This utility asks for the user login passwd, decrypts the user's share
     from the TCFS group key database, and passes the share to the TCFS
     module.
     Shares of a group are treated by the utilities tcfsputkey, tcfsrmkey,
     tcfsviewkey similarly to user's keys. For examples, the user share of a
     group key can be made permanent by using the flag -p.

  5. If a user wants to become inactive, she removes her share of the key
     from the TCFS module. This can be accomplished by executing the
     command:
                              tcfsrmkey -g <group>



[1] A. Shamir, How to Share a Secret, Comm. ACM, v. 24, n. 11, Nov. 1979.
