javacardx.biometry1toN

Interface BioMatcher

All Known Subinterfaces:

OwnerBioMatcher, SharedBioMatcher

public interface BioMatcher

The BioMatcher interface is the base interface for biometric matching. It provides the user interface for accessing biometric functionality.
Several Biometric Template Data containers (BioTemplateData) can be enrolled in the same BioMatcher. BioMatcher is supporting both 1 to 1 matching and 1 to N matching when N BioTemplateData instances are enrolled.

Since:

3.0.5

Field Summary

Fields

Modifier and Type	Field and Description
static short	MATCH_NEEDS_MORE_DATA This negative score value indicates that more data are needed to continue the matching session.
static short	MINIMUM_SUCCESSFUL_MATCH_SCORE The minimum successful matching score.

Method Summary

Methods

Modifier and Type	Method and Description
BioTemplateData	getBioTemplateData(short index) Get the BioTemplateData enrolled at the specified index.
byte	getBioType() Gets the biometric type.
short	getIndexOfLastMatchingBioTemplateData() Gets the index of the last matching BioTemplateData.
short	getMaxNbOfBioTemplateData() Gets the maximum number of BioTemplateData that can be enrolled in this BioMatcher.
byte	getTriesRemaining() Gets the number of times remaining that an incorrect candidate can be presented before the BioMatcher is blocked.
short	getVersion(byte[] dest, short offset) Gets the matching algorithm version and ID.
short	initMatch(byte[] candidate, short offset, short length) Initialize or re-initialize a biometric matching session.
boolean	isInitialized() Indicates whether this BioMatcher has been loaded with at least one BioTemplateData and is ready for matching functions.
boolean	isValidated() Indicates whether a matching session was successfully since the last card reset or last call to reset().
short	match(byte[] candidate, short offset, short length) Continues a biometric matching session.
void	reset() Resets the validated flag associated with this BioMatcher.

Field Detail

MINIMUM_SUCCESSFUL_MATCH_SCORE

static final short MINIMUM_SUCCESSFUL_MATCH_SCORE

The minimum successful matching score.

See Also:

Constant Field Values

MATCH_NEEDS_MORE_DATA

static final short MATCH_NEEDS_MORE_DATA

This negative score value indicates that more data are needed to continue the matching session.

See Also:

Constant Field Values

Method Detail

isInitialized

boolean isInitialized()

Indicates whether this BioMatcher has been loaded with at least one BioTemplateData and is ready for matching functions. This is independent of whether or not the match process has been initialized (see initMatch).

Returns:

true if initialized, false otherwise.

isValidated

boolean isValidated()

Indicates whether a matching session was successfully since the last card reset or last call to reset().

In addition to returning a boolean result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

Returns:

true if validated, false otherwise.

reset

void reset()

Resets the validated flag associated with this BioMatcher. This could be appropriate as a last action after an access is completed.

getTriesRemaining

byte getTriesRemaining()

Gets the number of times remaining that an incorrect candidate can be presented before the BioMatcher is blocked.

In addition to returning a byte result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

Returns:

the number of tries remaining.

Throws:

Bio1toNException - with the following reason codes:

• Bio1toNException.NO_BIO_TEMPLATE_ENROLLED if no BioTemplateData has been enrolled.

getBioType

byte getBioType()

Gets the biometric type. Valid types are described in Bio1toNBuilder.

Returns:

the biometric general type.

getVersion

short getVersion(byte[] dest,
               short offset)

Gets the matching algorithm version and ID.

Parameters:

dest - destination byte array.

offset - starting offset within the destination byte array.

Returns:

the number of bytes written in the destination byte array.

initMatch

short initMatch(byte[] candidate,
              short offset,
              short length)
                throws Bio1toNException

Initialize or re-initialize a biometric matching session. If this BioMatcher is not blocked, a matching session starts and, before any other processing, the validated flag is reset, the internal match state is set to MATCH_NEEDS_MORE_DATA, and the try counter is decremented. If the try counter has reached zero, the this BioMatcher is blocked. This method results in one of the following:

• The matching session ends with success state if at least one of the BioTemplateData enrolled with this BioMatcher is matching. The validated flag is set and the try counter is reset to its maximum.
• The matching session ends with failed state if none of the BioTemplateData enrolled with this BioMatcher is matching. The validated flag remains in the reset state.
• The matching session continues if the matching needs more data. The match method has to be called to continue the matching session.

If this BioMatcher is blocked, no matching session starts.

Notes:

• A correct matching sequence is : initMatch,[match]. Calling initMatch is mandatory, calling match is optional.
• If a matching session is in progress (case needs more data), a call to initMatch makes the current session to be discarded and starts a new matching session.
• Even if a transaction is in progress, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated.

In addition to returning a short result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.
The following code sample illustrates the use of SensitiveResult:

try {
     short matchResult = bioMatcher.initMatch( ...);
     SensitiveResult.assertEquals(matchResult);  // recheck for security
     while (matchResult == MATCH_NEEDS_MORE_DATA) {
          matchResult = bioMatcher.match(...);
     }
     SensitiveResult.assertEquals(matchResult);  // recheck for security
     if ((matchResult >= MINIMUM_SUCCESSFUL_MATCH_SCORE) {
        // grant service - user authenticated
     } else {
        // deny service - Bio Template mismatch
     }
  } finally {
     SensitiveResult.reset();
  }
 

Parameters:

candidate - the data or part of the data of the candidate.

offset - the starting offset into the candidate array where the candidate data is to be found.

length - the number of bytes to be taken from the candidate array.

Returns:

the matching score with the following meaning :

• >= MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session is successful.
• >= 0 and < MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session has failed.
• = MATCH_NEEDS_MORE_DATA : the matching session needs more data.

Throws:

Bio1toNException - with the following reason codes:

• Bio1toNException.INVALID_DATA if the submitted candidate data does not have the required format.
• Bio1toNException.NO_BIO_TEMPLATE_ENROLLED if no BioTemplateData has been enrolled.

match

short match(byte[] candidate,
          short offset,
          short length)
            throws Bio1toNException

Continues a biometric matching session. The exact return score value is implementation dependent and can be used, for example, to code a confidence rate. If a matching session is in progress, this method results in one of the following:

• The matching session ends with success state if at least one of the BioTemplateData enrolled in this BioMatcher matches. The validated flag is set and the try counter is reset to its maximum.
• The matching session ends with failed state if none of the BioTemplateDatas enrolled in this BioMatcher are matching.
• The matching session continues if the matching needs more data. The match method has to be called to continue the matching session.

Notes:

• A correct matching sequence is: initMatch,[match]. Calling initMatch is mandatory, calling match is optional.
• Even if a transaction is in progress, internal state such as the try counter, the validated flag and the blocking state must not be conditionally updated.

In addition to returning a short result, platform-implementations of this method set the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.
The following code sample illustrates the use of SensitiveResult:

try {
     short matchResult = bioMatcher.initMatch( ...);
     SensitiveResult.assertEquals(matchResult);  // recheck for security
     while (matchResult == MATCH_NEEDS_MORE_DATA) {
          matchResult = bioMatcher.match(...);
     }
     SensitiveResult.assertEquals(matchResult);  // recheck for security
     if ((matchResult >= MINIMUM_SUCCESSFUL_MATCH_SCORE) {
        // grant service - user authenticated
     } else {
        // deny service - Bio Template mismatch
     }
  } finally {
     SensitiveResult.reset();
  }
 

Parameters:

candidate - the data or part of the data of the candidate.

offset - the starting offset into the candidate array where the candidate data is to be found.

length - number of bytes to be taken from the candidate array.

Returns:

the matching score with the following meaning :

• >= MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session is successful.
• >= 0 and < MINIMUM_SUCCESSFUL_MATCH_SCORE : the matching session has failed.
• = MATCH_NEEDS_MORE_DATA : the matching session needs more data.

Throws:

Bio1toNException - with the following reason codes:

• Bio1toNException.ILLEGAL_USE if used outside a matching session.
• Bio1toNException.INVALID_DATA if the submitted candidate data does not have the required format.
• Bio1toNException.NO_BIO_TEMPLATE_ENROLLED if no BioTemplateData have been enrolled.

getMaxNbOfBioTemplateData

short getMaxNbOfBioTemplateData()

Gets the maximum number of BioTemplateData that can be enrolled in this BioMatcher.

Returns:

the maximum number of BioTemplateData that can be enrolled.

getIndexOfLastMatchingBioTemplateData

short getIndexOfLastMatchingBioTemplateData()

Gets the index of the last matching BioTemplateData.

Returns:

the index of the last matching BioTemplateData.

Throws:

Bio1toNException - with the following reason codes:

• Bio1toNException.ILLEGAL_USE if no successful match occurred since last reset.

getBioTemplateData

BioTemplateData getBioTemplateData(short index)

Get the BioTemplateData enrolled at the specified index. This method is used to retrieve the BioTemplateData for readonly use.

Parameters:

index - the index of the BioTemplateData to retrieve.

Returns:

null if no BioTemplateData is available at the specified index.