InkTools
Class CicSigCheck

java.lang.Object
  |
  +--InkTools.CicSigCheck

public class CicSigCheck

extends java.lang.Object

CIC's signature verification class. Signature verification means to compare a signature to a previously generated user template and to make a decision based on the 'verification score' if the signature is reasonable matching the template so that it can be assumed that the signature and the template are from the same person. The latter case means that the signature is verified. If signature and template are not matching, forgery is assumed.

The process to generate a user template is called 'enrollment'. The user has to create 3 (up to 6) signatures, which gets passed into the 'signatureEnrollment' method, which then creates the user template. Encryption can be used to keep this template always in an encrypted form in memory. The 'streamOut' and 'loadTemplate' functions can be used for serialization (saving and restoring of the template). It is recommendet to always use encryption for the template, so that the template can't get manipulated or replaced bu a possible indruder.

For the verification, a user template has to get loaded into the CicSigCheck class. If the template was stored as an encrypted byte stream, the correct encryption key has to get set before the loading or in the loading function, otherwise the 'loadTemplate' method will fail and verification can't be done. Use the 'hasTemplate' function to test if a valid template is loaded. The 'setThreshold' function will let you set your desired threshold for the verification process, which means how closely the signature must match the template to get verified. Note that the 'verifySignature' returns 3 verification results: verified, ambigious and forgery.

The verification process has an automated 'user template update' functinality, that means that if the signature was verified, the template may be updated in order compensate for the slow changing of a users signature over time. In this case the updated template must be saved to replace the older template. Call the 'templateIsUpdated' function to check the status.

Version:

1.0

Author:

CIC

Field Summary

static int	BASE64 specifies stabdarde Base64 encoding
static int	CIC_CONSISTENT ConsistencyCheck: all signatures are consistent (0)
static int	CIC_INCONSISTENT ConsistencyCheck: signature is inconsistent (1)
static int	CIC_NO_SIGNATURE ConsistencyCheck: no signature provided for this array element (-1)
static int	CIC_NOT_VALID ConsistencyCheck: signature is not recognized as a signaure (3)
static int	CIC_TOO_SIMPLE ConsistencyCheck: signature is too simple (2)
static int	CICNONEPRINT specifies CIC's nonPrinting encoding
static int	DES used in setEnryptionAlgorithm: DES 56 bit encryption algorithm
static int	DES40 used in setEnryptionAlgorithm: DES 40 bit encryption algorithm
static int	FAST used in setEnryptionAlgorithm: CIC's FAST encryption algorithm
static int	TRIPLEDES used in setEnryptionAlgorithm: DES 128 bit encryption algorithm

Constructor Summary

CicSigCheck()
Creates a new signature verification object.

Method Summary

CicReturn	ConsistencyCheck(CicDoodle[] pDoodle, int numDoodles, int[] consistent) With the ConsistencyCheck function you can check if the signatures, with which you want to enroll, are consistence, meaning an enrollment would succeed.
CicReturn	ConsistencyCheckEx(CicDoodle[] pDoodle, int numDoodles, int[][] consArray, int[] order, int[] val)
void	disableEncryption() Disables encryption for templates.
void	enableEncryption() Enables encryption for templates.
CicReturn	extractSignature(CicDoodle doodle, int index) Extracts from the current active template the signature with the requested index.
SigCheck.SigTemplate	getTemp() Return the current template, or null if there is none.
int	getUpdatePosition() On every call to the 'signatureVerification' function the verification algorithm will save the place where the template was updated, if any.
int	hasTemplate() Checks if a valid template is currently loaded.
CicReturn	loadEncryptTemplate(byte[] inStream) Loads an encrypted template from the byte array and makes it the active template.
CicReturn	loadEncryptTemplate(byte[] inStream, java.lang.String key) Loads an encrypted template from the byte array and makes it the active template.
CicReturn	loadEncryptTemplate(java.lang.String fileName) Loads an encrypted template from file and makes it the active template.
CicReturn	loadEncryptTemplate(java.lang.String fileName, java.lang.String key) Loads an encrypted template from file and makes it the active template.
CicReturn	loadTemplate(byte[] inStream) Loads a template from the byte array and makes it the active template.
CicReturn	loadTemplate(java.lang.String fileName) Loads a template from file and makes it the active template.
int	matchScore() On every call to the 'signatureVerification' function the verification algorithm will save the match score for the attempt.
CicReturn	setEncryptionAlgorithm(int alg) Set the encryption algorithm used for encrypting the template.
void	setEncryptionKey(java.lang.String encKey) Set the encryption key.
boolean	setStringEncodingAlg(int encoderAlgorithm) Sets the encoding algorithm if the streamOut function is called with removeNonPrinting set to true.
CicReturn	setThreshold(int threshold) Sets the threshold level for the verification process.
void	setUpdateEnabled(boolean val) Set the update enabled flag to the specified value.
CicReturn	signatureEnrollment(CicDoodle[] pDoodle, int numDoodles, boolean newEnroll) Signature enrollment function.
CicReturn	signatureVerification(CicDoodle doodle) Verifies the passed in signature against the currently loaded user template.
byte[]	streamOutTemplate(boolean bRemoveNonePrinting) Streams the currently active template out into a byte stream for serialization purposes.
CicReturn	streamOutTemplate(java.lang.String fileName, boolean bRemoveNonePrinting) Streams the currently active template out as a byte stream into a file.
boolean	templatedIsUpdated() On every call to the 'signatureVerification' function the verification algorithm will dynamically evaluate if the user template has to get updated.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DES40

public static final int DES40

used in setEnryptionAlgorithm: DES 40 bit encryption algorithm

See Also:

Constant Field Values

DES

public static final int DES

used in setEnryptionAlgorithm: DES 56 bit encryption algorithm

See Also:

Constant Field Values

TRIPLEDES

public static final int TRIPLEDES

used in setEnryptionAlgorithm: DES 128 bit encryption algorithm

See Also:

Constant Field Values

FAST

public static final int FAST

used in setEnryptionAlgorithm: CIC's FAST encryption algorithm

See Also:

Constant Field Values

CICNONEPRINT

public static final int CICNONEPRINT

specifies CIC's nonPrinting encoding

See Also:

Constant Field Values

BASE64

public static final int BASE64

specifies stabdarde Base64 encoding

See Also:

Constant Field Values

CIC_CONSISTENT

public static final int CIC_CONSISTENT

ConsistencyCheck: all signatures are consistent (0)

See Also:

Constant Field Values

CIC_INCONSISTENT

public static final int CIC_INCONSISTENT

ConsistencyCheck: signature is inconsistent (1)

See Also:

Constant Field Values

CIC_TOO_SIMPLE

public static final int CIC_TOO_SIMPLE

ConsistencyCheck: signature is too simple (2)

See Also:

Constant Field Values

CIC_NOT_VALID

public static final int CIC_NOT_VALID

ConsistencyCheck: signature is not recognized as a signaure (3)

See Also:

Constant Field Values

CIC_NO_SIGNATURE

public static final int CIC_NO_SIGNATURE

ConsistencyCheck: no signature provided for this array element (-1)

See Also:

Constant Field Values

Constructor Detail

CicSigCheck

public CicSigCheck()

Creates a new signature verification object. No template is loaded yet.

Method Detail

signatureEnrollment

public CicReturn signatureEnrollment(CicDoodle[] pDoodle,
                                     int numDoodles,
                                     boolean newEnroll)

Signature enrollment function. This function takes 3 to 6 signatures in form of a doodle and creates a signature template. This template is then active. Use the streamOut function to serialize the template.

Parameters:

pDoodle - array object of 3 to 6 doodle objects

numDoodles - number of doodles passed in

newEnroll - true if this is a new enrollment, false if signatures are added in the case of an priviously error (for example, the signatures where not consistend and a signature has to get replaced

Returns:

CicReturn object

ConsistencyCheck

public CicReturn ConsistencyCheck(CicDoodle[] pDoodle,
                                  int numDoodles,
                                  int[] consistent)

With the ConsistencyCheck function you can check if the signatures, with which you want to enroll, are consistence, meaning an enrollment would succeed. If there are inconsistence signatures, these signatures will be identified and can be replaced with new ones, until all signatures are consistent, at which time the enroll function can be called whith the garantie to succeed then. The caller has to allocate an array of 6 int's for the consistent return value. If enrollment is done with say just 3 signatures, array element 4,5,6 will have the CIC_NO_SIGNATURE values, since they don't matter. In general, check for each signature if the consistent flag is set to CIC_Consistence, otherwise collect a new signature for this signature array element. The function returns CicReturn.OK if all signatures are consistent, CicReturn.ENROLL_TOO_DIFFERENT if some signatures are inconsistent or CicReturn.ENROLL_TOO_SIMPLE if all signatures are too simple.

Parameters:

pDoodle - array object of 3 to 6 doodle objects

numDoodles - number of doodles passed in

consistent - array object of 6 ints, returning the status of the single signature:

• CIC_CONSISTENT (0) Signature is OK
• CIC_INCONSISTENT (1) Signature is not consistent with the other signatures.
• CIC_TOO_SIMPLE (2) This Signaure is to simple
• CIC_NOT_VALID (3) This Signature was not recognized as a signature
• CIC_NO_SIGNATURE (-1) No signature was passed in for this array element

Returns:

CicReturn object

ConsistencyCheckEx

public CicReturn ConsistencyCheckEx(CicDoodle[] pDoodle,
                                    int numDoodles,
                                    int[][] consArray,
                                    int[] order,
                                    int[] val)

signatureVerification

public CicReturn signatureVerification(CicDoodle doodle)

Verifies the passed in signature against the currently loaded user template. Previous to a call to this function, a template has to get loaded (or created). This method can return a status of 'verified', 'ambigious' or forgery. Use the 'setThreshold' fucntion to set your desired threshold values. Use the 'templateIsUpdated' function to check if the template was updated in the verification process (only if signature was verified). If the signature has no ink or the template was or couldn't get loaded, an appropriate error return will be generated.

Parameters:

doodle - signature in form of a doodle

Returns:

CicReturn object

setThreshold

public CicReturn setThreshold(int threshold)

Sets the threshold level for the verification process. Level 1 to level 5 is supported, where level 1 has the least threshold and level 5 the heighest.

Parameters:

threshold - the threshold level

Returns:

CicReturn object

matchScore

public int matchScore()

On every call to the 'signatureVerification' function the verification algorithm will save the match score for the attempt.

Returns:

the match score from the last verification

templatedIsUpdated

public boolean templatedIsUpdated()

On every call to the 'signatureVerification' function the verification algorithm will dynamically evaluate if the user template has to get updated. If so, the user template will actually change and has to get saved. After a call to 'signatureVerification', programmers should call this function in order to determin if the stored template has to get replaced with the updated new one, if that is desired.

Returns:

true if the last signature verification actually updated the template, false if no update took place

getUpdatePosition

public int getUpdatePosition()

On every call to the 'signatureVerification' function the verification algorithm will save the place where the template was updated, if any. This information is needed in diagnostic programs which want to keep track of which signatures the template contains.

Returns:

The most recently updated template position

hasTemplate

public int hasTemplate()

Checks if a valid template is currently loaded. It returns:

• 1: unencrypted template is loaded
• 2: encrypted template is loaded
• 0: no template is loaded

Returns:

the template status

getTemp

public SigCheck.SigTemplate getTemp()

Return the current template, or null if there is none.

Returns:

the template

setUpdateEnabled

public void setUpdateEnabled(boolean val)

Set the update enabled flag to the specified value.

extractSignature

public CicReturn extractSignature(CicDoodle doodle,
                                  int index)

Extracts from the current active template the signature with the requested index. The signature is scrambled to make it useless for verification purposes, but it's image will look the same as the original. If the index is invalid, NO_SIGNATURE will be returned.

Parameters:

doodle - contains the new CicDoodle object with the signature

index - the index of the signature requested.

Returns:

CicReturn object

streamOutTemplate

public byte[] streamOutTemplate(boolean bRemoveNonePrinting)

Streams the currently active template out into a byte stream for serialization purposes. If encryption is enabled, the byte stream will have the encrypted template. If no template is active, a null will be returned. Set the bRemoveNonePrinting flag to true if the byte stream should consist only of printable ASCII characters.

Parameters:

bRemoveNonePrinting - true if all none printable bytes should be replaced with printable ASCII characters (increases template size), otherwise false

Returns:

a byte stream containing the template or null

streamOutTemplate

public CicReturn streamOutTemplate(java.lang.String fileName,
                                   boolean bRemoveNonePrinting)

Streams the currently active template out as a byte stream into a file. If encryption is enabled, the byte stream will have the encrypted template. If no template is active, a null will be returned. Set the bRemoveNonePrinting flag to true if the byte stream should consist only of printable ASCII characters.

Parameters:

fileName - the file name of the template

bRemoveNonePrinting - true if all none printable bytes should be replaced with printable ASCII characters (increases template size), otherwise false

Returns:

CicReturn object

loadTemplate

public CicReturn loadTemplate(byte[] inStream)

Loads a template from the byte array and makes it the active template. If the load fails, an appropriate return error code will be generated.

Parameters:

inStream - the template byte array

Returns:

CicReturn object

loadTemplate

public CicReturn loadTemplate(java.lang.String fileName)

Loads a template from file and makes it the active template. If the load fails, an appropriate return error code will be generated.

Parameters:

fileName - the file containing the template

Returns:

CicReturn object

loadEncryptTemplate

public CicReturn loadEncryptTemplate(byte[] inStream)

Loads an encrypted template from the byte array and makes it the active template. Make sure that the correct encryption key was set before calling this function. Generates an appropriate error return if load or decryption fails.

Parameters:

inStream - the template byte array

Returns:

CicReturn object

loadEncryptTemplate

public CicReturn loadEncryptTemplate(byte[] inStream,
                                     java.lang.String key)

Loads an encrypted template from the byte array and makes it the active template. Uses the passed in encryption key to decrypting the template. Generates an appropriate error return if load or decryption fails.

Parameters:

inStream - the template byte array

key - the 8 or 24 byte encryption key

Returns:

CicReturn object

loadEncryptTemplate

public CicReturn loadEncryptTemplate(java.lang.String fileName)

Loads an encrypted template from file and makes it the active template. Make sure that the correct encryption key was set before calling this function. Generates an appropriate error return if load or decryption fails.

Parameters:

fileName - the name of the template file

Returns:

CicReturn object

loadEncryptTemplate

public CicReturn loadEncryptTemplate(java.lang.String fileName,
                                     java.lang.String key)

Loads an encrypted template from file and makes it the active template. Uses the passed in encryption key to decrypt the template. Generates an appropriate error return if load or decryption fails.

Parameters:

fileName - the template file name

key - the 8 or 24 byte encryption key

Returns:

CicReturn object

enableEncryption

public void enableEncryption()

Enables encryption for templates. The encryption has to get enabled and the encryption key set before generating a template, otherwise the template was generated unencrypted.

disableEncryption

public void disableEncryption()

Disables encryption for templates.

setEncryptionKey

public void setEncryptionKey(java.lang.String encKey)

Set the encryption key. The key must be 8 bytes long for FAST, DES and DES40 encryption algorithm and 24 bytes for TripleDES. No error check is done here. If key has wrong length, the verification will fail with an appropriate error message.

Parameters:

encKey - the encryption key

setEncryptionAlgorithm

public CicReturn setEncryptionAlgorithm(int alg)

Set the encryption algorithm used for encrypting the template.

• 1 is DES40 - 40 bit DES encryption
• 2 is DES - 56 bit DES encryption
• 3 is TripleDES - 128 bit DES encryption
• 4 is FAST - CIC's FAST encryption

Parameters:

alg - The used encryption algorithm

Returns:

CicReturn object

setStringEncodingAlg

public boolean setStringEncodingAlg(int encoderAlgorithm)

Sets the encoding algorithm if the streamOut function is called with removeNonPrinting set to true. Supportes at this time are only CIC_PRINTABLE and BASE64. The default value is CIC_PRINTABLE

Parameters:

encoderAlgorithm - either CIC_PRINTABLE or BASE64

Returns:

false if none supported Algorithm was specified