Copyright (C) 2004-2005 Feitian Technologies Co.,Ltd.
http://www.ftsafe.com

EnterSafe for linux
==================

This package is EnterSafe with Cryptoki(PKCS#11) for linux. Before the installation, you are recommented to read the this document carefully. This document will care about what you should pay attention to when you start(restart) you PC and the frequently asked questions about this product.

Installation Requires
=====================

These are generic installation instructions.

  1. To install EnterSafe for Linux, you must be root user.

  2. You must have pcsc-lite installed in your system and it's your responsiblity to install it as a Daemon process so the pcscd can auto-run when linux OS starts (Please refer to the pcsc-lite documents to see how to install it as a daemon process).

     You can go to visit http://www.linuxnet.com and install the lastest version of pcsc-lite. You can also install the pcsc-lite tarballs from linuxnet.com along with this package or RPM packages from Feitian.

     To check pcsc, run the following command:

          whereis pcscd

     then system will show you like this:

          pcscd: /usr/local/sbin/pcscd

     NOTE: If you have install it, do not reinstall.

  3. Before you install this package, please install the Token Driver. For example the ePass2000 hardware driver if you use the ePass2000 token. Please refer to the driver's documents to see how to install and uninstall it.

     NOTE: If you have install it before, you can go directly to install the EnterSafe package with skipping this step.

Basic Installations
===================

Take the following steps to complete the installation:

  1. Install the product:
 
       If you install the package with tarball-format, then:
       a) untar/unzip the package to $PACKAGE_ROOT.
       b) 'cd' to the directory $PACKAGE_ROOT.
       c) type `./install' to install the package to your system.
       
       if you install the RPM-format package:
       only install it with 'rpm -ivh EnterSafe-epXX-x.y.z-os.x86.rpm".
       (here, XX is the token support, x.y.z is the version number, and os is the operating system support of this RPM package, such as mdk, rh ,suse and etc.)

  2. Start the ngslotd to enable the ePass's midlle-ware:
       If you have installed another product with EnterSafe middle-ware and ngslotd service has been started successfully, you should restart it with:
	/etc/init.d/ngslotd restart
else you can start it with:
        /etc/init.d/ngslotd start
        the ngslotd service will start up automatically when you reboot you machine.

  3. Start mozilla, open `instpk.html' which localated at $PACKAGE_ROOT/lib, this will install EnterSafe PKCS#11 module for mozilla, click "Yes" button when prompt to install a new module.
  
      If you install the EnterSafe in RPM format, you can find the 'instpk.html' in '/usr/local/ngsrv/docs' directory.
      
      The other method to use EnterSafe with mozilla is:
      Run mozilla, open the menu "Edit"--->"Preferences"--->"Privace & Security" ---->"Certificates" ---> "Manage Security Devices", and then add our "/usr/lib/libepsng_p11.so" to mozilla.
      
   Now you should attach a initialized token to your PC, and use mozilla to request certificate, establish SSL connection, and so on.
   NOTE: Tokens from other companies must be initialized by Feitian PKI Init tool to use with EnterSafe.

Platform tested
===============

This package has been tested in the follwing platform:
   RedHat 9 with
   kernel version: 2.4.20-8
   gcc version:    3.2(20030222)
   mozilla:        1.2.1

   Other platforms are not tested.

FAQ(frequently asked questions)
===============================

EnterSafe:
================

1. What's the meaning of "EnterSafe" ?
   The EnterSafe is ePass product of (N)ext (G)eneration. it is a framework, ePass1000, ePass2000 and the other tokens from Feitian (or other companies) can all be used within this framework.

2. What's happened when my mozilla or netscape stop but no errors and warnings are showed?
   First, perhaps the driver of ePass1000 or ePass2000 are not installed perfectly, input the command '/sbin/lsmod' to see whether the 'epass'(for ePass1000) or 'ftcard'(for ePass2000) module is in the list. If 'epass'(or 'ftcard') is not in the list, you must reinstall the drivers.
   second, perhaps the driver of ePass1000 or ePass2000 have error occured sometime. Restart your pcscd as this document says and then run your PKI application to see whether the question is still on show.

3. What's the length of key pair supported by the EnterSafe?
   To ePass1000 token, it supports 2048 and 512 bits key length in the future. But to ePass2000 token, it only supports 1024 bits key lenth.

4. How to initialize the ePass token under linux enviroment?
   We will provide the release version of "token manager tool" in the future, but now it is beta version. 
   To initialize the token, You can use the tools under windows, this is compatible, or you can write a simple PKCS#11 program to call the function -- C_InitToken && C_SetPin. Our PKCS#11 lib's name is -- "libepsng_p11.so" (Be sure that nsglotd is running).

5. What does the name of package "EnterSafe-ZZZZ-XXXX-YYYY" mean?
   "EnterSafe" means ePass product package for NG framework.
   "XXXX" means the version of this package, for example, 1.2b means version 1.2 Beta(This is only for test purpose) and 1.4.0 means release version of 1.4.0.
   "ZZZZ" perhaps is ePass2000(only for ePass2000), ePass1000(only for ePass1000), pboc(only for PBOC token), ePass(only for ePass1000 and ePass2000), full(can be used with ePass1000, ePass2000, and the other known token from Feitian).
   "YYYY" support platform,perhaps is rh8(only for redhat 8),fc2(only for edora Core release 2),deb3.1(only for Debian 3.1).

6. How to uninstall the EnterSafe?
   If you install the EnterSafe with RPM format, it is very simple to uninstall it, just use "rpm -e EnterSafe-ZZZZ".
   If you install it with tarball format, then you can execute the "uninstall" script inside the tarball.
   
pcsc-lite and ngslotd:
======================

1. What does EnterSafe depend on?
   This package depends on pcsc-lite. So before the installation, you should have the pcsc-lite package installed on your machine.
   You can download the free latest pcsc-lite package on http://www.linuxnet.com and follow the steps in its documents to install it. A link on http://www.linuxnet.com are referred to http://pcsclite.alioth.debian.org/, this is the real place to download the package.

   NOTE: Please install the pcsc-lite as an Daemon Process, so it can auto-run when the OS starts. The pcsc-lite RPM can put the pcscd to auto-run list automaticlly. Installed it by tarball, you must add it to auto-run manually. Please refer to pcsc-lite documents to see how to run as pcsc-lite as a daemon process.
   Now we have packaged the pcsc-lite-1.1.2 and pcsc-lite-1.2.0 to RPMs on Redhat platforms, so you can install these RPM packages with "rpm -ivh pcsc-lite-X.Y.Z-ftsafe-rh.i386.rpm", it will become daemon automaticly.

2. How to check pcscd and start it manually?
   To check whether the pcscd(the daemon of pcsc-lite) is running, input the following command: 'ps ax | grep pcscd' in your teminal. (do not use 'ps aux | grep pcscd', this perhaps ends with nothing)
   If the result is like: ' 3859 ? S 0:00 /usr/local/sbin/pcscd' , the pcscd is already running.
   To kill(stop) the pcscd , login as root (with 'su' command and input your root password) and input: 'kill 3859' ( perhaps the PID is different from 3859 on your PC, you should use the value yours ) or 'killall pcscd'. But be sure that you have kill(stop) the ngslotd before you stop the pcscd.
   To start pcscd, you can do as Step 3 of <Basic Installations>, replace the 'ngslotd' with 'pcscd'.
   NOTE: don't kill(stop) and restart pcscd when ngslotd is running.

3. Can the pcscd and ngslotd start automaticly when my PC start?
   As our expectation, the pcscd and ngslotd will start with your machine starting.
   To check the pcscd, see the previous question.
   To check the ngslotd, input the command : 'ps ax | grep ngslotd'.
   To kill(stop) ngslotd, input the command: 'kill (PID)' or 'killall ngslotd', here (PID) is the process ID of ngslotd.
   If pcscd or ngslotd is not running when you start your PC, start them according to Step 3 of <Basic Installations>.

4. What should I do in order to see whether the ePass token driver has been installed correctly?
   To see whether the ePass token has been installed correctly, stop(kill) the pcscd, and then start it like:
   '/usr/local/sbin/pcscd -f -a -d stdout'

   You can see more detailed information when pcscd interacts with token driver.
   Remove and reinsert your ePass token. If you see the correct ATR of token showed by the pcscd debug message, the token driver is correct.

   The ePass2000's ATR is: 3B B7 94 00 81 31 FE 65 53 50 4B 32 33 90 00 D1
   or 3B F9 94 00 00 81 31 FE 65 46 54 20 56 31 30 30 90 00 83
   or 3B B9 94 00 81 31 FE 65 46 54 20 56 31 31 30 90 00 C2
   or 3B B7 11 00 81 31 FE 9F 46 54 53 50 4B 31 XX 2C
   or 3B B7 95 00 81 31 FE 9F 46 54 53 50 4B 31 XX AD
   And ePass1000's ATR is: 3B 07 46 54 55 53 42 31 4B

   If the ATR returned by tools is different with up, the pcscd is not running perfectly, you should reboot your machine.
   NOTE: Before the previous steps, the ngslotd should be killed(stopped).

5. Whether should I restart ngslotd(the daemon of EnterSafe) when I restart (or install) the pcsc-lite?
   Yes, before you stop the pcscd, you must stop ngslotd. Otherwise you must reboot your machine to restart ngslotd correctly. And before you start ngslotd, please start pcscd.

6. When should I reboot my machine?
   After installation (reinstallation) of this package, or some errors has been occured(such as the mozilla application stops with no response), you are recommended to reboot your machine.

7. Why does an error occur when I remove and reinsert the token ?
   When you remove and reinsert the token, pcscd will takes a little time to communicate with it and so does ngslotd. Please wait a few seconds after you reinsert the token.

8. How many tokens can be attached at the same time?
   Now less than 10 tokens can be attached at the same time.

9. Must I restart the pcsc-lite daemon after I install the EnterSafe ?
   No, you don't have to. But after you install the drivers of our hardware token, such as drv-ep1k-X.Y.Z.tar.gz and drv-ep2k-X.Y.Z.tar.gz, you must restart the pcsc-lite daemon or before the driver installation, stop the pcsc-lite daemon and after that start it.
