<!DOCTYPE LINUXDOC SYSTEM>
<linuxdoc>
<article>
	<titlepag><title>GNU POC</title>
	<author>
	<name>Henning Koester, <tt>henning@crackinghacking.de</tt></name>
      	</author>
      	<date>V1.2, Wed May 16 16:06:46 CEST 2001</date>
      	<abstract>
	This document describes how to use GNU POC (Passwords On Card). 
      	</abstract></titlepag>

	<toc>

	<sect>Introduction

        <p>With GNU POC you can manage passwords on smartcards (only I2C memory 
        cards at the moment). Every entry on the card consits of a password 
        and a description, which gives information about the password. All 
        data is stored encrypted on the card. Thus it's impossible for someone
        to get the passwords, when he/she finds/steals the card. 
 
	poc makes use of the CT-API library 
	<it>(http://www.linuxnet.com/smartcard/ctapi/ctapi.html)</it>
	to access cards.
	So you'll need a CT-API library to use poc. I use the CT-API library
	by Carlos Prados <it>(http://www.geocities.com/cprados)</it> 
	for TOWITOKO readers.

	poc was developed under Debian GNU/Linux. It migh work on other
	*IX systems as well.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	General Public License for more details.

	POC is free software and distributed under the terms of the
	GNU General Public License.


	<sect>Installation
			   
	<p>Installing poc is easy. Unpack the archive, change to
	the correct directory and type:
	<tscreen>
		<verb>./configure
make
		</verb>
	</tscreen>

	If everything works fine, you can execute
	<tscreen>
		<verb>make install
make install-docs (optional)
		</verb>
	</tscreen>

	to install the binary and poc's manpage.

	Note: Normally only root can access com-ports. So you have to
	explicit allow people to read and write to the ports, by adding them to
	the appropiate group.

	<sect>Invocation
	
	<p>COMMANDS

	<descrip>
	<tag><tt>[-s | --save-password]</tt></tag>
	
	<it>Save a password:</it>
	First you will be asked for a password and a description of the 
	password. After that you have to enter the card's key. You'll
	see "<tt>Password saved.</tt>", if everything worked. Otherwise
	an error message will be printed.

	<tag><tt>[-r DESCRIPTION | --remove-password=DESCRIPTION]</tt></tag>
	
	<it>Remove a password:</it>	
	You'll be asked to enter the card's key. If everything worked and
	poc removed a password you'll see "<tt>Password removed.</tt>"

	<tag><tt>[-l DESCRIPTION | --list-password=DESCRIPTION]</tt></tag>

	<it>List a password:</it>
	You'll be asked to enter the card's key. If a description is found,
	which matches the given one, poc will print the password and the
	corresponding description.

	<tag><tt>[-f | --format-card]</tt></tag>
	
	<it>Format a card:</it>
	You have to enter the size of the card and confirm the card's
	formatting.

	<tag><tt>[-c | --change-cardkey]</tt></tag>

	<it>Change the card's key:</it>
	You'll be asked for the current key and then for the new key.

	<tag><tt>[--backup=FILE]</tt></tag>

	<it>Backup a card:</it>
	A backup of the card's memory will be made to "FILE".

	<tag><tt>[--restore=FILE]</tt></tag>
	
	<it>Restore a backuped card:</it>
	"FILE" is an image of a backuped card. It will be written to the
	card. You are responsible for a card with enough size to hold the
	backuped image. poc does not check whether the card has sufficient
	size or not. 
	
	</descrip>

        <p>OPTIONS

        <descrip>
        <tag><tt>[--cipher=CHIPER]</tt></tag>

	<it>Selecting a cipher:</it>
	This option allows you to change the cipher which will be used for
	encryption. You can choose between "AES" and "BLOWFISH". By default
	poc will use AES for encryption. If you want to use BLOWFISH
	instead of AES, but don't want to specify it every time you invoke
	poc, you can set the environment variable "POC_CIPHER" to avoid it.
	(if you are using the bash: "export POC_CIPHER=BLOWFISH")

	<tag><tt>[--security=LEVEL]</tt></tag>

	<it>Selecting the security level:</it>
	You can choose which security level to use. There are two available
	"1" and "2". If you select "1" a 192 bit key will be used for
	encryption. And if you select "2" a 256 bit key will be used.
	As well as for the cipher selection you can set an environment 
	variable for the security level selection. The variable is "POC_SL"
	and must be set to "1" or "2".

	<tag><tt>[-p NUM | --port=NUM]</tt></tag>
	
	<it>Set the comport where the card reader is installed:</it>
	This let's you specify where to find the card reader. NUM can
	be 1...4.

	</descrip>

	<sect>Upgrade from 1.0 to 1.1

	<p><em>*** You cannot use cards which have been made with <bf>1.0</bf> with
	<bf>1.1</bf> ***</em> 

	List all passwords:	
	<tscreen>
		<verb>poc -l all > FILE</verb>
	</tscreen>
	
	NOTE: FILE should be not readable by other users!

	Format the card:
	<tscreen>
		<verb>poc -f</verb>
	</tscreen>

	And then add all password again.

	<sect>How does POC work?

	<p>
	<descrip>
	<tag>Format of the card's memory</tag>
	The first 2 byte of the card contain the card's size. Byte 3 and 4
	contain the data size (the data size is the number of bytes of the
	data area which are used.) From the 5'th byte starts the data area,  
	which is the area of the card where the passwords+descriptions are
	stored. The data area is encrypted.

	<tag>Encryption</tag>
	The encryption key entered by the user is hashed using Tiger
	(192 bit key), or SHA-2 (256 bit key). In the next step
	this hashed key is passed to the ciphers key-scheduleing function.
	And finally the data area is encrypted using one of the ciphers
	in OFB mode.

	(Take a look at 
	<em>http://home.ecn.ab.ca/~jsavard/crypto/co0409.htm</em> for a
	description of different block cipher modes.)	

	</descrip>

	<sect>Contact
	
	<p>If you have suggestions or want to report bugs mail to 
	<tt>bug-poc@gnu.org</tt> .
	
	If you want to contact me, you can mail to 
	<tt>henning@crackinghacking.de</tt> .
	

</article>
</linuxdoc>

