Disclaimer
THE AUTHORS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE. 

Author: Hector Ho Fuentes
e-mail: hhofuent@ccs.neu.edu

LAST UPDATED JULY 16, 2002

If you have any suggestions please write to the author.  

Description:

SSC2Lib is a Palm OS Library that implements SSC2.  SSC2 is a stream
cipher.

To use this Palm Library, you need to:

1.  Download the SSC2Lib.prc
2.  Download the SSC2Lib.h
3.  Only include the SSC2Lib.h in your project.

How to use the SSC2Lib:

1. First you need to open the Library. 
The sample code is as follows:

	err = SysLibFind("SSC2Lib", &SSC2LibRefNum);
	if (err) err = SysLibLoad('libr', 'HHSL', &SSC2LibRefNum);
	ErrFatalDisplayIf(err, "Cannot load SSC2 Library");
	err = SSC2Open(SSC2LibRefNum);

Where SSC2LibRefNum is a static UInt16, used to store where is 
the SSC2Library.

We sugest that you put this code in your StartApplication() function, or
in the function you use to initialize your application.

2.  How to use SSC2?

You need to create a variable that will contain some of the SSC2 info.  
We have created a special type:
SSC2_CTX.

Example:

SSC2_CTX key_ctx;

NOTE: We have changed the SSC2_CTX.  In the past we used to have space to 
store the key here, but for space considerations and security considerations, 
we decided to remove that field.  Please check SSC2Lib.h

Also, you need to Initialize SSC2 and then you can call the
Encryption/Decryption functions.

After you finish, you need to close the library.

3.  How to Initialize SSC2?

This is done via the function:
SSC2MasterKeyGeneration(UInt16 refNum, unsigned char * keystring, int keysize, SSC2_CTX * key) 

It has the following parameters:

UInt16 refNum:  This is the reference number of the library.
unsigned char * keystring: This is string with the key.
int keysize:  This signals the size of the key.
SSC2_CTX * key:  In this variable we will store the key and other internal
information about SSC2.

NOTE:  After running SSC2MasterKeyGeneration() check the output, if the output is SSC2ErrNone, everything went fine,
but if the output is SSC2ErrKeySize, then the keysize is of a wrong size (i.e. the key size is less than 4 Bytes!)

4. How to Encrypt/Decrypt?

To Encrypt or Decrypt, we have declared two functions:

To Encrypt we use the function:

SSC2Encrypt(UInt16 refNum, SSC2_CTX * key, unsigned char * in, unsigned char * out, unsigned long size) 

The parameters are as follows:

UInt16 refNum:  The reference number of this library.  Obtain when you
open the library.

SSC2_CTX * key:  This is the context information about SSC2.  You need to
initialize it before using it in Encrypt or Decrypt.

unsigned char * in:  This is a pointer to the input string.

unsigned char * out:  This is a pointer to where the output should be
written.  The user has to allocate this memory.

unsigned long size:  This is the size of the data to be encrypted.  This
size is denoted in number of Bytes to be encrypted.

To decrypt, the function is

SSC2Decrypt(UInt16 refNum, ARC4_CTX * key, unsigned char * in, unsigned
char * out, unsigned long size)

and the parameters are the same.

NOTE:  The user is responsible in deallocating any memory created for the
input and output strings.

5.  How to Close the Library?

You can close the library when you finished.  This is accomplished via:

	error = SSC2Close(SSC2LibRefNum, &numapps);  
	// check for erros in the Close() routine
	if (numapps == 0)
		SysLibRemove(SSC2LibRefNum);

We suggest you include this code in the StopApplication() function
or your function used to handle the case of closing the application.