Interface BioMatcher
-
- All Known Subinterfaces:
OwnerBioMatcher
,SharedBioMatcher
public interface BioMatcher
TheBioMatcher
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 sameBioMatcher
.BioMatcher
is supporting both 1 to 1 matching and 1 to N matching when NBioTemplateData
instances are enrolled.- Since:
- 3.0.5
-
-
Field Summary
Fields Modifier and Type Field 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description BioTemplateData
getBioTemplateData(short index)
Get theBioTemplateData
enrolled at the specified index.byte
getBioType()
Gets the biometric type.short
getIndexOfLastMatchingBioTemplateData()
Gets the index of the last matchingBioTemplateData
.short
getMaxNbOfBioTemplateData()
Gets the maximum number ofBioTemplateData
that can be enrolled in thisBioMatcher
.byte
getTriesRemaining()
Gets the number of times remaining that an incorrect candidate can be presented before theBioMatcher
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 thisBioMatcher
has been loaded with at least oneBioTemplateData
and is ready for matching functions.boolean
isValidated()
Indicates whether a matching session was successfully since the last card reset or last call toreset()
.short
match(byte[] candidate, short offset, short length)
Continues a biometric matching session.void
reset()
Resets thevalidated
flag associated with thisBioMatcher
.
-
-
-
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 thisBioMatcher
has been loaded with at least oneBioTemplateData
and is ready for matching functions. This is independent of whether or not the match process has been initialized (seeinitMatch
).- Returns:
true
if initialized,false
otherwise.
-
isValidated
boolean isValidated()
Indicates whether a matching session was successfully since the last card reset or last call toreset()
.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 theSensitiveResult
class, if supported by the platform.- Returns:
true
if validated,false
otherwise.
-
reset
void reset()
Resets thevalidated
flag associated with thisBioMatcher
. 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 theBioMatcher
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 theSensitiveResult
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 noBioTemplateData
has been enrolled.
-
getBioType
byte getBioType()
Gets the biometric type. Valid types are described inBio1toNBuilder
.- 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 thisBioMatcher
is not blocked, a matching session starts and, before any other processing, thevalidated
flag is reset, the internal match state is set toMATCH_NEEDS_MORE_DATA
, and the try counter is decremented. If the try counter has reached zero, the thisBioMatcher
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 thisBioMatcher
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 thisBioMatcher
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
]. CallinginitMatch
is mandatory, callingmatch
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 theSensitiveResult
class, if supported by the platform.
The following code sample illustrates the use ofSensitiveResult
: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 noBioTemplateData
has been enrolled.
- The matching session ends with success state if at least one of the
-
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 thisBioMatcher
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
BioTemplateData
s enrolled in thisBioMatcher
are matching. - The matching session continues if the matching needs more data. The
match
method has to be called to continue the matching session.
- A correct matching sequence is:
initMatch
,[match
]. CallinginitMatch
is mandatory, callingmatch
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 theSensitiveResult
class, if supported by the platform.
The following code sample illustrates the use ofSensitiveResult
: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 noBioTemplateData
have been enrolled.
- The matching session ends with success state if at least one of the
-
getMaxNbOfBioTemplateData
short getMaxNbOfBioTemplateData()
Gets the maximum number ofBioTemplateData
that can be enrolled in thisBioMatcher
.- Returns:
- the maximum number of
BioTemplateData
that can be enrolled.
-
getIndexOfLastMatchingBioTemplateData
short getIndexOfLastMatchingBioTemplateData()
Gets the index of the last matchingBioTemplateData
.- 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 theBioTemplateData
enrolled at the specified index. This method is used to retrieve theBioTemplateData
for readonly use.- Parameters:
index
- the index of theBioTemplateData
to retrieve.- Returns:
null
if noBioTemplateData
is available at the specified index.
-
-