Corrigendum: U051
Date: April 2001
Document: C909
CDSA/CSSM Authentication:
Human Recognition Service (HRS) API
Code: 24kbytes April 2001, C909/U051
Contents: This corrigendum comprises changes 1 through 8.
-----------------------------------------------------------------------
Change Number: U051/2001
Title: Corrections in Section 1
Qualifier: Minor technical
Rationale: Correcting errors
Change: Section 1.6, second paragraph, change from
"Enroll, Process and Update" to "Enroll and
CreateTemplate".
---------------------------------------------------------------------
Change Number: U051/2002
Title: Clarifications in Section 1
Qualifier: Minor editorial
Rationale: Improved explanation
Change: Section 1.2, first line, change from
"initial `template'" to "initial registration
`template'".
Section 1.2, third line, change from "device"
to "sensor".
Section 1.2, second paragraph, first line,
change from "samples" to "live samples".
Section 1.2, para starting "Figure 1-1", last line,
change from "H-level interface" to "API".
Section 1.3, first paragraph after Table 1-1, add
second sentence: "When present, it is calculated
on the Header + Opaque Biometric Data."
Section 1.4, penultimate sentence of second paragraph,
add "internally" after "done".
Section 1.4, paragraph after "1. Using Primitive
Functions", add "result" after "same".
Section 1.4, First sentence of "capture", change
from "execute" to "executed".
Section 1.4, third sentence of "capture", change
from "do" to "perform".
Section 1.4, third sentence of "capture",
add comma after identification.
Section 1.4, last sentence of "capture", add
"header of the" before "constructed".
Section 1.4, Figure 1-3 title, change from
"Processing using" to "Implementation Using".
Section 1.4, Figure 1-4 title, change to:
"Client/Server Implementation Using Streaming
Callback - Server Initiated Operation"
Section 1.4, Figure 1-5 title, change to:
"Client/Server Implementation Using Streaming
Callbacks - Client Initiated Operation"
Section 1.5, second paragraph, change from
"measures" to "criteria".
Section 1.5, fourth paragraph, add after "request a":
"match threshold in terms of".
Section 1.5, fifth paragraph, add after "match":
"(i.e., the score)".
Section 1.5, add paragraph at the end:
"Use of FAR/FRR values to represent match scores is
done to allow a degree of normalization and comparison
between differing technologies, and to allow a
commonly understood means of setting thresholds and
interpreting results. It is not intended to imply
strict performance measurement (that is, an absolute
measure of FAR for a specific individual matching
instance). Furthermore, the BSP vendor is responsible
for accurately mapping internal scoring structure to
the FAR values.
Section 1.8, third paragraph, second sentence,
"service providers", add: "implementing the
Application Controlled GUI option".
----------------------------------------------------------------------
Change Number: U051/2003
Title: Complement BIR definition with CBEFF
Qualifier: Minor editorial
Rationale: Useful information
Change: Add after Table 1-1:
"The BIR definition is compliant with NISTIR 6529,
Common Biometric Exchange File Format (CBEFF),
of which it is one of the CBEFF Patron Formats."
-----------------------------------------------------------------------
Change Number: U051/2004
Title: Changes to BIR Data Type Values in Section 2
Qualifier: Minor technical
Rationale: Binary mask compatibility
Change: Section 2.1.8, change the values of the first
three items from:
(0x00)
(0x01)
(0x02)
to:
(0x01)
(0x02)
(0x04)
----------------------------------------------------------------------
Change Number: U051/2005
Title: Clarifications in Section 2
Qualifier: Minor editorial
Rationale: Improved description
Change: Section 2.1.3, add sentence at end of second paragraph:
"The signature is calculated on the combined Header
and BiometricData."
Section 2.1.4, add sentence at beginning:
"An array of BIRs, generally used during identification
operations (as input to Identify or Identify_Match)."
Sections 2.1.5, 2.1.7, 2.1.8, 2.1.9, 2.1.12, add
sentence at end:
"Note: All integer values in the BIR header are
little-endian."
Section 2.1.6, add sentence at the beginning:
"This comprises the opaque data block within a BIR
containing the biometric sample(s) or template(s)."
Section 2.1.6, add sentence at the end:
"Note: The format of this data is specified by the
format i field (CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT)
in the BIR header. See Section 1.3."
Section 2.1.7, add sentence at the beginning:
"Defines the format of the data contained within the
opaque data block, CSSM_HRS_BIR_BIOMETRIC_DATA."
Section 2.1.10, change from "PurposeMask" to
"Purpose".
Section 2.1.11, add sentence at the beginning:
"A value which defines the purpose(s) or use(s) for
which the BIR is intended (when used as an input)
or suitable (when used as an output or within the
BIR header)."
Section 2.1.11, add at the end of the section:
"Note: All integer values in the BIR header are
little-endian."
"Note: The Purpose value is utilized in two ways. First,
it is used as an input parameter to allow the
application to indicate to the BSP the purpose for
which the resulting data is intended, thus allowing
the BSP to perform the appropriate capturing and/or
processing to create the proper BIR for this purpose.
Second, it is used within the BIR header to indicate
to the application (or to the BSP during subsequent
operations) what purposes the BIR is suitable for.
For example, some BSPs use different BIR formats
depending on whether the data is to be used for
verification or identification, the latter generally
including additional information to enhance speed or
accuracy. Similarly, many BSPs use different data
formats depending on whether the data is to be used
as a sample for immediate verification or as a
reference template for future matching (i.e., enrollment).
Restrictions on the use of BIR data of a particular
purpose include:
a) All purposes are valid in the BIR header.
b) Purposes of Verify and Identify are only valid as
input to the Capture function.
c) Purposes of Enroll, Enroll_for_Verification_Only,
and Enroll_for_Identification_Only are only valid
as input to the Capture, Enroll, and Import
functions.
d) The Audit purpose is not valid as input to any
function, but is only used in the BIR header.
e) The Process and Create_Template functions do not
have Purpose as an input parameter, but read the
Purpose field from the BIR header of the input
Captured_BIR.
f) The Process function may accept as input any
intermediate BIR with a Purpose including Verify
or Identify, and will output only BIRs with a
Purpose of Verify and/or Identify.
g) The Create_Template function may accept as input
any intermediate BIR with a Purpose including
Enroll, Enroll_for_Verification_Only, and/or
Enroll_for_Identification, and will output only
BIRs with a Purpose including that of the input
BIR.
h) If a BIR is suitable for enrollment for either
subsequent verification or identification, then
the Enroll Purpose is to be used in the returned
BIR header.
Section 2.1.19, add sentence at the end:
"Note: FAR is used within BioAPI as a means of setting
thresholds and returning scores (see Section 1.5)."
Section 2.1.20, add sentence at the end:
"Note: FRR is used within CDSA/HRS as an optional/alternate
means of setting thresholds and returning scores (see
Section 1.5)."
Section 2.1.29, add sentence at beginning:
"A structure used to identify the set of BIRs to be
used as input to an Identify or Identify_Match
operation."
Section 2.1.30, add sentence at the beginning:
"A value indicating the method of BIR input to an
Identify or Identify_Match operation, whether it be
via a passed-in array or a pointer to a database."
Section 2.1.34, add note after "typedef":
"Note: All integer values in the BIR header are
little-endian."
------------------------------------------------------------------
Change Number: U051/2006
Title: Update Error Codes
Qualifier: Minor technical
Rationale: Alignment with required error codes
Change: Section 2.3.3, remove the error codes 7 and 11.
Add the following error codes:
#define CSSMERR_HRS__UNABLE_TO_CREATE_DATABASE
(CSSM_HRS_BASE_BSP_ERROR+266)
BSP cannot create the database
#define CSSMERR_HRS_UNABLE_TO_CLOSE_DATABASE
(CSSM_HRS_BASE_BSP_ERROR+267)
BSP cannot close database
#define CSSMERR_HRS_UNABLE_TO_DELETE_DATABASE
(CSSM_HRS_BASE_BSP_ERROR+268)
BSP cannot delete database
---------------------------------------------------------------------
Change Number: U051/2007
Title: Changes/clarifications to functions
Qualifier: Minor technical
Rationale: Completeness of definitions
Change: HRS_Capture function, change the AuditData parameter
from "AuditData (output)" to "AuditData (output/optional)".
HRS_CreateTemplate function, add error codes:
CSSMERR_HRS_RECORD_NOT_FOUND
CSSMERR_HRS_INVALID_BIR
HRS_Process function, add error code:
CSSMERR_HRS_RECORD_NOT_FOUND
HRS_VerifyMatch function, AdaptedBIR parameter, change
from "-1" to "CSSM_HRS_UNSUPPORTED_BIR_HANDLE ".
Replace last sentence with clause:
"or a value of CSSM_HRS_INVALID_BIR_HANDLE to
indicate that adaptation was not possible."
Remove error code: CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED
Add error code: CSSMERR_HRS_RECORD_NOT_FOUND
HRS_IdentifyMatch function, add error code:
CSSMERR_HRS_RECORD_NOT_FOUND
HRS_Enroll function, add the following to the
description of the AuditData parameter:
"If the pointer is NULL on input, no audit data
is collected. Not all HRS service providers
support the collection of Audit data. An HRS
service provider may return a handle value
of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate
AuditData is not supported, or a value of
CSSM_HRS_INVALID_BIR_HANDLE to indicate that
no audit data is available."
Add error code: CSSMERR_HRS_RECORD_NOT_FOUND
HRS_Verify function, replace description of
AdaptedBIR parameter with:
"A pointer to the handle of the adapted BIR.
This parameter can be NULL if an Adapted BIR
is not desired. Not all HRS service providers
support the adaptation of BIRs. The function
may return a handle value of
CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate
that adaptation is not supported or a value
of CSSM_HRS_INVALID_BIR_HANDLE to indicate
that adaptation was not possible."
AuditData parameter, change from "AuditData (output)"
to "AuditData(output/optional)".
Replace last sentence of parameter description with:
"An HRS service provider may return a handle
value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to
indicate AuditData is not supported, or a value
of CSSM_HRS_INVALID_BIR_HANDLE to indicate that
no audit data is available."
Remove error code: CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED
Add error code: CSSMERR_HRS_RECORD_NOT_FOUND
HRS_Identify function, remove ProcessedBIR parameter from
API and SPI, and delete parameter description, and remove it
from the HRS Function Pointer Table in Section 3.1.
In the MaxFARRequested and MaxFRRRequested parameter
descriptions, change from "verification" to
"identification".
AuditData parameter, change from "(output)" to
"(output/optional)".
Add the following to the end of the AuditData
parameter description:
"Not all HRS service providers support the
collection of Audit data. A BSP may return a
handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE
to indicate AuditData is not supported, or a
value of CSSM_HRS_INVALID_BIR_HANDLE to indicate
that no audit data is available."
Add error code: CSSMERR_HRS_RECORD_NOT_FOUND
------------------------------------------------------------------
Change Number: U051/2008
Title: Correction to Appendix A (Conformance)
Qualifier: Minor editorial
Rationale: Corrections to informative Appendix
Changes: Replace sentence following Table A-2 with:
"Local functions are always executed on the
system where the API is called. Eligible
functions are executed remotely if a Streaming
Callback has been set."
Section A.4.4.1, replace first paragraph with:
"Primitive functions
Although it was originally intended that the
primitive functions (CSSM_HRS_Capture,
CSSM_HRS_CreateTemplate, CSSM_HRS_Process,
CSSM_HRS_VerifyMatch, and CSSM_HRS_IdentifyMatch)
would be mandatory, it was decided that this would
place undue burden on manufacturers of
"self-contained devices" in which the biometric
processing/matching is performed within the device
itself. Therefore, these functions have not been
specified as required for HRS service providers
to be considered "HRS compliant". However, it is
highly recommended that, if supported by the
underlying technology, these functions be included
in the service provider.
CSSM_HRS_Capture
If this function is supported, Verification BSPs
need only accept Purpose flags indicating
Verification or Enroll for Verification. If another
purpose is set by the application, an error
condition may be set as a CSSM_RETURN. Similarly,
this function need only return CapturedBIR with the
Purpose mask set to Verification or Enroll for
Verification. If this function is supported,
Identification service providers must accept all
possible Purpose flags (except Audit), even if
there is no difference in the content or format
of the returned data.
Return of raw data (AuditData) is optional.
As a default, all service providers must provide
any GUI associated with the Capture operation.
However, support for application control of the
GUI is optional.
CSSM_HRS_CreateTemplate
If this function is supported, Verification service
providers need only accept input CapturedBIRs
with the Purpose set to Enroll for Verification.
If another purpose is set, an error condition
may be set as a CSSM_RETURN.
If this function is supported, Identification
service providers must accept input CapturedBIRs
with both Enroll purposes.
Acceptance of Payload is optional.
Adaptation of an existing template is optional.
CSSM_HRS_Process
If this function is supported, Verification service
providers need only accept input CapturedBIRs
with the Purpose set to Verification. If another
purpose is set, an error condition may be set
as a CSSM_RETURN.
If this function is supported, Identification
service providers must accept input CapturedBIRs
with all possible Purpose flags (except Audit),
even if there is no difference in the content or
format of the returned data.
CSSM_HRS_VerifyMatch
If this function is supported, only input BIRs
(ProcessedBIR) with the Purpose mask including a
value of Verification, and (StoredTemplate) with
the Purpose mask including a value of Enroll for
Verification must be accepted. If another purpose
is set, an error condition may be set as a
CSSM_RETURN.
Only the nearest, better supported RequestedFAR
must be supported; however, the service provider
must return that supported value (ActualFAR).
Return of payload is required only if one is
contained within the input StoredTemplate and if
the score is better than the ActualFAR (the service
provider must post minimum FAR required to return
payload in the module registry).
Return of AdaptedBIR is optional.
BioAPI_IdentifyMatch
May be supported by Identification service providers
for BIRs whose purpose is identify.
Only the nearest, better supported RequestedFAR
must be supported; however, the service provider
must return that supported value (ActualFAR).
Support of binning is optional.
Return of matching Candidates is required; however,
the service provider may return values for the Score
field as next nearest step/increment.
Section A.4.4.1, HRS_Import, second paragraph,
replace "Enroll for Verification" with "Enroll or
Enroll for Verification".
Remove last sentence starting: "Identification only SPs ...".
Section A.4.4.1, Application-controlled GUI,
add a sentence after heading, as follows:
"The SP supports the necessary callbacks to allow
the application to control the look-and-feel of the GUI."
Section A.4.4.2, Return of Raw Data, add after second
sentence add: "(or CSSM_HRS_INVALID_BIR_HANDLE to indicate
that no audit data is available.)"
Replace "-1" with "CSSM_HRS_UNSUPPORTED_BIR_HANDLE".
Section A.4.4.2, Payload Carry, replace "HRS_Process"
with "HRS_CreateTemplate".
Replace "-1" with "a NULL pointer".
Section A.4.4.2, Return of FRR, replace "-2" with
"CSSM_HRS_FRR_NOT_SUPPORTED".
Section A.4.4.2, Template/Model Adaptation,
replace "-2" with "CSSM_HRS_UNSUPPORTED_BIR_HANDLE"
and replace "-1" with "CSSM_HRS_INVALID_BIR_HANDLE".
----------------------------------------------------------------------