Package 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 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 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:

      • 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 or if an exception is thrown during the match. 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.
        • The matching session must ignore any enrolled BioTemplateData that is uninitialized.

        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 :
        Throws:
        Bio1toNException - with the following reason codes:

      • 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 BioTemplateData enrolled in this BioMatcher is matching or if an exception is thrown during the match.
        • 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.
        • The matching session must ignore any enrolled BioTemplateData that is uninitialized.

        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 :
        Throws:
        Bio1toNException - with the following reason codes:

      • 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.

        Note: indexing starts at value "1" ("0" is an invalid value).

        Returns:
        the index of the last matching BioTemplateData.
        Throws:
        Bio1toNException - with the following reason codes:

      • getBioTemplateData

        BioTemplateData getBioTemplateData​(short index)
        Get the BioTemplateData enrolled at the specified index. This method is used to retrieve the BioTemplateData for readonly use.

        Note: indexing starts at value "1" ("0" is an invalid value).

        Parameters:
        index - the index of the BioTemplateData to retrieve.
        Returns:
        null if no BioTemplateData is available at the specified index.