ࡱ > t u v w x y z { | } ~ y { bjbj z { { " j
M
M dZ dZ dZ dZ dZ $ Z Z Z P Z i Z f LT , d ^ t% d d d d d d d $ j Hm
e dZ Ж Ж Ж
e dZ dZ 4 e F F F Ж 1 dZ dZ d F Ж d F F fR ] [ Ez W X d e 0 f X dn n + dn [ [ dn dZ ^ Ж Ж F Ж Ж Ж Ж Ж
e
e F Ж Ж Ж f Ж Ж Ж Ж dn Ж Ж Ж Ж Ж Ж Ж Ж Ж
M *Y :
WS-Biometric Devices Version 1.0
Committee Specification Draft 02
12 November 2014
Specification URIs
This version:
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.pdf" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.pdf (Authoritative)
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.html" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.html
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.doc" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.doc
Previous version:
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.doc" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.doc (Authoritative)
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.html" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.html
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.pdf" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csprd01/WS-BD-v1.0-csprd01.pdf
Latest version:
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.pdf"http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.pdf (Authoritative)
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.html"http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.html
HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.doc"http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.doc
Technical Committee:
HYPERLINK "https://www.oasis-open.org/committees/biometrics/"OASIS Biometrics TC
Chair:
Kevin Mangold ( HYPERLINK "mailto:kevin.mangold@nist.gov" kevin.mangold@nist.gov), HYPERLINK "http://www.nist.gov/" NIST
Editors:
Kevin Mangold ( HYPERLINK "mailto:kevin.mangold@nist.gov" kevin.mangold@nist.gov), HYPERLINK "http://www.nist.gov/" NIST
Ross J. Micheals ( HYPERLINK "mailto:ross.micheals@nist.gov" ross.micheals@nist.gov), HYPERLINK "http://www.nist.gov/" NIST
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
XML schemas: HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/schemas/" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/schemas/
Related work:
This specification replaces or supersedes:
Specification for WS-Biometric Devices (WS-BD) Version 1. HYPERLINK "http://www.nist.gov/itl/iad/ig/upload/NIST-SP-500-288-v1.pdf" http://www.nist.gov/itl/iad/ig/upload/NIST-SP-500-288-v1.pdf
Declared XML namespaces:
HYPERLINK "http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0" http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0
Abstract:
WS-Biometric Devices is a protocol for the command and control of biometric sensors using the same protocols that underlie the Web.
Status:
This document was last revised or approved by the OASIS Biometrics TC on the above date. The level of approval is also listed above. Check the Latest version location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at HYPERLINK "https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=biometrics" \l "technical"https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=biometrics#technical.
TC members should send comments on this specification to the TCs email list. Others should send comments to the TCs public comment list, after subscribing to it by following the instructions at the HYPERLINK "https://www.oasis-open.org/committees/comments/index.php?wg_abbrev=biometrics"Send A Comment button on the TCs web page at HYPERLINK "https://www.oasis-open.org/committees/biometrics/"https://www.oasis-open.org/committees/biometrics/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (HYPERLINK "https://www.oasis-open.org/committees/biometrics/ipr.php"https://www.oasis-open.org/committees/biometrics/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[WS-BD-v1.0]
WS-Biometric Devices Version 1.0. Edited by Kevin Mangold and Ross J. Micheals. 12 November 2014. OASIS Committee Specification Draft 02. HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.html" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/csd02/WS-BD-v1.0-csd02.html. Latest version: HYPERLINK "http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.html" http://docs.oasis-open.org/biometrics/WS-BD/v1.0/WS-BD-v1.0.html.
Notices
Copyright OASIS Open 2014. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full HYPERLINK "https://www.oasis-open.org/policies-guidelines/ipr"Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of HYPERLINK "https://www.oasis-open.org/"OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see HYPERLINK "https://www.oasis-open.org/policies-guidelines/trademark"https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Table of Contents
TOC \o "1-3" \h \z \u HYPERLINK \l "_Toc405561695" 1 Introduction PAGEREF _Toc405561695 \h 10
HYPERLINK \l "_Toc405561696" 1.1 Motivation PAGEREF _Toc405561696 \h 10
HYPERLINK \l "_Toc405561697" 1.2 Terminology PAGEREF _Toc405561697 \h 10
HYPERLINK \l "_Toc405561698" 1.3 Documentation Conventions PAGEREF _Toc405561698 \h 11
HYPERLINK \l "_Toc405561699" 1.3.1 About PAGEREF _Toc405561699 \h 11
HYPERLINK \l "_Toc405561700" 1.3.2 Key Words PAGEREF _Toc405561700 \h 11
HYPERLINK \l "_Toc405561701" 1.3.3 Quotations PAGEREF _Toc405561701 \h 11
HYPERLINK \l "_Toc405561702" 1.3.4 Machine-Readable Code PAGEREF _Toc405561702 \h 12
HYPERLINK \l "_Toc405561703" 1.3.5 Sequence Diagrams PAGEREF _Toc405561703 \h 12
HYPERLINK \l "_Toc405561704" 1.4 References PAGEREF _Toc405561704 \h 13
HYPERLINK \l "_Toc405561705" 2 Design Concepts and Architecture PAGEREF _Toc405561705 \h 17
HYPERLINK \l "_Toc405561706" 2.1 About PAGEREF _Toc405561706 \h 17
HYPERLINK \l "_Toc405561707" 2.2 Interoperability PAGEREF _Toc405561707 \h 17
HYPERLINK \l "_Toc405561708" 2.3 Architectural Components PAGEREF _Toc405561708 \h 17
HYPERLINK \l "_Toc405561709" 2.3.1 Overview PAGEREF _Toc405561709 \h 17
HYPERLINK \l "_Toc405561710" 2.3.2 Client PAGEREF _Toc405561710 \h 17
HYPERLINK \l "_Toc405561711" 2.3.3 Sensor PAGEREF _Toc405561711 \h 18
HYPERLINK \l "_Toc405561712" 2.3.4 Sensor Service PAGEREF _Toc405561712 \h 18
HYPERLINK \l "_Toc405561713" 2.4 Intended Use PAGEREF _Toc405561713 \h 18
HYPERLINK \l "_Toc405561714" 2.5 General Service Behavior PAGEREF _Toc405561714 \h 19
HYPERLINK \l "_Toc405561715" 2.5.1 About PAGEREF _Toc405561715 \h 19
HYPERLINK \l "_Toc405561716" 2.5.2 Security Model PAGEREF _Toc405561716 \h 19
HYPERLINK \l "_Toc405561717" 2.5.3 HTTP Request-Response Usage PAGEREF _Toc405561717 \h 19
HYPERLINK \l "_Toc405561718" 2.5.4 Client Identity PAGEREF _Toc405561718 \h 20
HYPERLINK \l "_Toc405561719" 2.5.5 Sensor Identity PAGEREF _Toc405561719 \h 21
HYPERLINK \l "_Toc405561720" 2.5.6 Locking PAGEREF _Toc405561720 \h 22
HYPERLINK \l "_Toc405561721" 2.5.7 Operations Summary PAGEREF _Toc405561721 \h 23
HYPERLINK \l "_Toc405561722" 2.5.8 Idempotency PAGEREF _Toc405561722 \h 24
HYPERLINK \l "_Toc405561723" 2.5.9 Service Lifecycle Behavior PAGEREF _Toc405561723 \h 24
HYPERLINK \l "_Toc405561724" 3 Data Dictionary PAGEREF _Toc405561724 \h 26
HYPERLINK \l "_Toc405561725" 3.1 About PAGEREF _Toc405561725 \h 26
HYPERLINK \l "_Toc405561726" 3.2 Namespaces PAGEREF _Toc405561726 \h 26
HYPERLINK \l "_Toc405561727" 3.3 UUID PAGEREF _Toc405561727 \h 26
HYPERLINK \l "_Toc405561728" 3.4 Dictionary PAGEREF _Toc405561728 \h 27
HYPERLINK \l "_Toc405561729" 3.5 Parameter PAGEREF _Toc405561729 \h 27
HYPERLINK \l "_Toc405561730" 3.5.1 Overview PAGEREF _Toc405561730 \h 27
HYPERLINK \l "_Toc405561731" 3.5.2 Element Summary PAGEREF _Toc405561731 \h 28
HYPERLINK \l "_Toc405561732" 3.6 Range PAGEREF _Toc405561732 \h 30
HYPERLINK \l "_Toc405561733" 3.7 Array PAGEREF _Toc405561733 \h 30
HYPERLINK \l "_Toc405561734" 3.8 StringArray PAGEREF _Toc405561734 \h 31
HYPERLINK \l "_Toc405561735" 3.9 UuidArray PAGEREF _Toc405561735 \h 31
HYPERLINK \l "_Toc405561736" 3.10 ResourceArray PAGEREF _Toc405561736 \h 31
HYPERLINK \l "_Toc405561737" 3.11 Resource PAGEREF _Toc405561737 \h 32
HYPERLINK \l "_Toc405561738" 3.12 Resolution PAGEREF _Toc405561738 \h 32
HYPERLINK \l "_Toc405561739" 3.13 Status PAGEREF _Toc405561739 \h 32
HYPERLINK \l "_Toc405561740" 3.14 Result PAGEREF _Toc405561740 \h 34
HYPERLINK \l "_Toc405561741" 3.14.1 Overview PAGEREF _Toc405561741 \h 34
HYPERLINK \l "_Toc405561742" 3.14.2 Terminology Shorthand PAGEREF _Toc405561742 \h 35
HYPERLINK \l "_Toc405561743" 3.14.3 Required Elements PAGEREF _Toc405561743 \h 35
HYPERLINK \l "_Toc405561744" 3.14.4 Element Summary PAGEREF _Toc405561744 \h 35
HYPERLINK \l "_Toc405561745" 3.15 Validation PAGEREF _Toc405561745 \h 36
HYPERLINK \l "_Toc405561746" 4 Metadata PAGEREF _Toc405561746 \h 37
HYPERLINK \l "_Toc405561747" 4.1 About PAGEREF _Toc405561747 \h 37
HYPERLINK \l "_Toc405561748" 4.2 Service Information PAGEREF _Toc405561748 \h 37
HYPERLINK \l "_Toc405561749" 4.3 Configuration PAGEREF _Toc405561749 \h 38
HYPERLINK \l "_Toc405561750" 4.4 Captured Data PAGEREF _Toc405561750 \h 38
HYPERLINK \l "_Toc405561751" 4.4.1 Overview PAGEREF _Toc405561751 \h 38
HYPERLINK \l "_Toc405561752" 4.4.2 Minimal Metadata PAGEREF _Toc405561752 \h 39
HYPERLINK \l "_Toc405561753" 5 Live Preview PAGEREF _Toc405561753 \h 41
HYPERLINK \l "_Toc405561754" 5.1 About PAGEREF _Toc405561754 \h 41
HYPERLINK \l "_Toc405561755" 5.2 Endpoints PAGEREF _Toc405561755 \h 41
HYPERLINK \l "_Toc405561756" 5.3 Heartbeat PAGEREF _Toc405561756 \h 42
HYPERLINK \l "_Toc405561757" 6 Operations PAGEREF _Toc405561757 \h 44
HYPERLINK \l "_Toc405561758" 6.1 About PAGEREF _Toc405561758 \h 44
HYPERLINK \l "_Toc405561759" 6.2 General Usage PAGEREF _Toc405561759 \h 44
HYPERLINK \l "_Toc405561760" 6.2.1 Overview PAGEREF _Toc405561760 \h 44
HYPERLINK \l "_Toc405561761" 6.2.2 Precedence of Status Enumerations PAGEREF _Toc405561761 \h 44
HYPERLINK \l "_Toc405561762" 6.2.3 Parameter Failures PAGEREF _Toc405561762 \h 46
HYPERLINK \l "_Toc405561763" 6.2.4 Visual Summaries (Informative) PAGEREF _Toc405561763 \h 46
HYPERLINK \l "_Toc405561764" 6.3 Documentation Conventions PAGEREF _Toc405561764 \h 48
HYPERLINK \l "_Toc405561765" 6.3.1 About PAGEREF _Toc405561765 \h 48
HYPERLINK \l "_Toc405561766" 6.3.2 General Information PAGEREF _Toc405561766 \h 48
HYPERLINK \l "_Toc405561767" 6.3.3 Result Summary PAGEREF _Toc405561767 \h 49
HYPERLINK \l "_Toc405561768" 6.3.4 Usage PAGEREF _Toc405561768 \h 50
HYPERLINK \l "_Toc405561769" 6.3.5 Unique Knowledge PAGEREF _Toc405561769 \h 50
HYPERLINK \l "_Toc405561770" 6.3.6 Return Values Detail PAGEREF _Toc405561770 \h 50
HYPERLINK \l "_Toc405561771" 6.4 Register PAGEREF _Toc405561771 \h 51
HYPERLINK \l "_Toc405561772" 6.4.1 Overview PAGEREF _Toc405561772 \h 51
HYPERLINK \l "_Toc405561773" 6.4.2 Result Summary PAGEREF _Toc405561773 \h 51
HYPERLINK \l "_Toc405561774" 6.4.3 Usage PAGEREF _Toc405561774 \h 51
HYPERLINK \l "_Toc405561775" 6.4.4 Unique Knowledge PAGEREF _Toc405561775 \h 51
HYPERLINK \l "_Toc405561776" 6.4.5 Return Values Detail PAGEREF _Toc405561776 \h 51
HYPERLINK \l "_Toc405561777" 6.5 Unregister PAGEREF _Toc405561777 \h 53
HYPERLINK \l "_Toc405561778" 6.5.1 Overview PAGEREF _Toc405561778 \h 53
HYPERLINK \l "_Toc405561779" 6.5.2 Result Summary PAGEREF _Toc405561779 \h 53
HYPERLINK \l "_Toc405561780" 6.5.3 Usage PAGEREF _Toc405561780 \h 53
HYPERLINK \l "_Toc405561781" 6.5.4 Unique Knowledge PAGEREF _Toc405561781 \h 54
HYPERLINK \l "_Toc405561782" 6.5.5 Return Values Detail PAGEREF _Toc405561782 \h 54
HYPERLINK \l "_Toc405561783" 6.6 Try Lock PAGEREF _Toc405561783 \h 56
HYPERLINK \l "_Toc405561784" 6.6.1 Overview PAGEREF _Toc405561784 \h 56
HYPERLINK \l "_Toc405561785" 6.6.2 Result Summary PAGEREF _Toc405561785 \h 56
HYPERLINK \l "_Toc405561786" 6.6.3 Usage PAGEREF _Toc405561786 \h 56
HYPERLINK \l "_Toc405561787" 6.6.4 Unique Knowledge PAGEREF _Toc405561787 \h 56
HYPERLINK \l "_Toc405561788" 6.6.5 Return Values Detail PAGEREF _Toc405561788 \h 56
HYPERLINK \l "_Toc405561789" 6.7 Steal Lock PAGEREF _Toc405561789 \h 59
HYPERLINK \l "_Toc405561790" 6.7.1 Overview PAGEREF _Toc405561790 \h 59
HYPERLINK \l "_Toc405561791" 6.7.2 Result Summary PAGEREF _Toc405561791 \h 59
HYPERLINK \l "_Toc405561792" 6.7.3 Usage PAGEREF _Toc405561792 \h 59
HYPERLINK \l "_Toc405561793" 6.7.4 Unique Knowledge PAGEREF _Toc405561793 \h 60
HYPERLINK \l "_Toc405561794" 6.7.5 Return Values Detail PAGEREF _Toc405561794 \h 60
HYPERLINK \l "_Toc405561795" 6.8 Unlock PAGEREF _Toc405561795 \h 62
HYPERLINK \l "_Toc405561796" 6.8.1 Overview PAGEREF _Toc405561796 \h 62
HYPERLINK \l "_Toc405561797" 6.8.2 Result Summary PAGEREF _Toc405561797 \h 62
HYPERLINK \l "_Toc405561798" 6.8.3 Usage PAGEREF _Toc405561798 \h 62
HYPERLINK \l "_Toc405561799" 6.8.4 Unique Knowledge PAGEREF _Toc405561799 \h 62
HYPERLINK \l "_Toc405561800" 6.8.5 Return Values Detail PAGEREF _Toc405561800 \h 62
HYPERLINK \l "_Toc405561801" 6.9 Get Service Info PAGEREF _Toc405561801 \h 64
HYPERLINK \l "_Toc405561802" 6.9.1 Overview PAGEREF _Toc405561802 \h 64
HYPERLINK \l "_Toc405561803" 6.9.2 Result Summary PAGEREF _Toc405561803 \h 64
HYPERLINK \l "_Toc405561804" 6.9.3 Usage PAGEREF _Toc405561804 \h 64
HYPERLINK \l "_Toc405561805" 6.9.4 Unique Knowledge PAGEREF _Toc405561805 \h 66
HYPERLINK \l "_Toc405561806" 6.9.5 Return Values Detail PAGEREF _Toc405561806 \h 66
HYPERLINK \l "_Toc405561807" 6.10 Initialize PAGEREF _Toc405561807 \h 67
HYPERLINK \l "_Toc405561808" 6.10.1 Overview PAGEREF _Toc405561808 \h 67
HYPERLINK \l "_Toc405561809" 6.10.2 Result Summary PAGEREF _Toc405561809 \h 67
HYPERLINK \l "_Toc405561810" 6.10.3 Usage PAGEREF _Toc405561810 \h 67
HYPERLINK \l "_Toc405561811" 6.10.4 Unique Knowledge PAGEREF _Toc405561811 \h 68
HYPERLINK \l "_Toc405561812" 6.10.5 Return Values Detail PAGEREF _Toc405561812 \h 68
HYPERLINK \l "_Toc405561813" 6.11 Get Configuration PAGEREF _Toc405561813 \h 71
HYPERLINK \l "_Toc405561814" 6.11.1 Overview PAGEREF _Toc405561814 \h 71
HYPERLINK \l "_Toc405561815" 6.11.2 Result Summary PAGEREF _Toc405561815 \h 71
HYPERLINK \l "_Toc405561816" 6.11.3 Usage PAGEREF _Toc405561816 \h 71
HYPERLINK \l "_Toc405561817" 6.11.4 Unique Knowledge PAGEREF _Toc405561817 \h 72
HYPERLINK \l "_Toc405561818" 6.11.5 Return Values Detail PAGEREF _Toc405561818 \h 72
HYPERLINK \l "_Toc405561819" 6.12 Set Configuration PAGEREF _Toc405561819 \h 77
HYPERLINK \l "_Toc405561820" 6.12.1 Overview PAGEREF _Toc405561820 \h 77
HYPERLINK \l "_Toc405561821" 6.12.2 Result Summary PAGEREF _Toc405561821 \h 77
HYPERLINK \l "_Toc405561822" 6.12.3 Usage PAGEREF _Toc405561822 \h 78
HYPERLINK \l "_Toc405561823" 6.12.4 Unique Knowledge PAGEREF _Toc405561823 \h 78
HYPERLINK \l "_Toc405561824" 6.12.5 Return Values Detail PAGEREF _Toc405561824 \h 78
HYPERLINK \l "_Toc405561825" 6.13 Capture PAGEREF _Toc405561825 \h 84
HYPERLINK \l "_Toc405561826" 6.13.1 Overview PAGEREF _Toc405561826 \h 84
HYPERLINK \l "_Toc405561827" 6.13.2 Result Summary PAGEREF _Toc405561827 \h 84
HYPERLINK \l "_Toc405561828" 6.13.3 Usage PAGEREF _Toc405561828 \h 84
HYPERLINK \l "_Toc405561829" 6.13.4 Unique Knowledge PAGEREF _Toc405561829 \h 85
HYPERLINK \l "_Toc405561830" 6.13.5 Return Values Detail PAGEREF _Toc405561830 \h 85
HYPERLINK \l "_Toc405561831" 6.14 Download PAGEREF _Toc405561831 \h 90
HYPERLINK \l "_Toc405561832" 6.14.1 Overview PAGEREF _Toc405561832 \h 90
HYPERLINK \l "_Toc405561833" 6.14.2 Result Summary PAGEREF _Toc405561833 \h 90
HYPERLINK \l "_Toc405561834" 6.14.3 Usage PAGEREF _Toc405561834 \h 90
HYPERLINK \l "_Toc405561835" 6.14.4 Unique Knowledge PAGEREF _Toc405561835 \h 94
HYPERLINK \l "_Toc405561836" 6.14.5 Return Values Detail PAGEREF _Toc405561836 \h 94
HYPERLINK \l "_Toc405561837" 6.15 Get Download Info PAGEREF _Toc405561837 \h 96
HYPERLINK \l "_Toc405561838" 6.15.1 Overview PAGEREF _Toc405561838 \h 96
HYPERLINK \l "_Toc405561839" 6.15.2 Result Summary PAGEREF _Toc405561839 \h 96
HYPERLINK \l "_Toc405561840" 6.15.3 Usage PAGEREF _Toc405561840 \h 96
HYPERLINK \l "_Toc405561841" 6.15.4 Unique Knowledge PAGEREF _Toc405561841 \h 96
HYPERLINK \l "_Toc405561842" 6.15.5 Return Values Detail PAGEREF _Toc405561842 \h 96
HYPERLINK \l "_Toc405561843" 6.16 Thrifty Download PAGEREF _Toc405561843 \h 99
HYPERLINK \l "_Toc405561844" 6.16.1 Overview PAGEREF _Toc405561844 \h 99
HYPERLINK \l "_Toc405561845" 6.16.2 Result Summary PAGEREF _Toc405561845 \h 99
HYPERLINK \l "_Toc405561846" 6.16.3 Usage PAGEREF _Toc405561846 \h 99
HYPERLINK \l "_Toc405561847" 6.16.4 Unique Knowledge PAGEREF _Toc405561847 \h 100
HYPERLINK \l "_Toc405561848" 6.16.5 Return Values Detail PAGEREF _Toc405561848 \h 100
HYPERLINK \l "_Toc405561849" 6.17 Cancel PAGEREF _Toc405561849 \h 103
HYPERLINK \l "_Toc405561850" 6.17.1 Overview PAGEREF _Toc405561850 \h 103
HYPERLINK \l "_Toc405561851" 6.17.2 Result Summary PAGEREF _Toc405561851 \h 103
HYPERLINK \l "_Toc405561852" 6.17.3 Usage PAGEREF _Toc405561852 \h 103
HYPERLINK \l "_Toc405561853" 6.17.4 Unique Knowledge PAGEREF _Toc405561853 \h 105
HYPERLINK \l "_Toc405561854" 6.17.5 Return Values Detail PAGEREF _Toc405561854 \h 105
HYPERLINK \l "_Toc405561855" 7 Conformance Profiles PAGEREF _Toc405561855 \h 107
HYPERLINK \l "_Toc405561856" 7.1 About PAGEREF _Toc405561856 \h 107
HYPERLINK \l "_Toc405561857" 7.2 Conformance Requirements PAGEREF _Toc405561857 \h 107
HYPERLINK \l "_Toc405561858" 7.3 Claims of Conformance PAGEREF _Toc405561858 \h 107
HYPERLINK \l "_Toc405561859" 7.4 Language PAGEREF _Toc405561859 \h 107
HYPERLINK \l "_Toc405561860" 7.5 Operations & Conformance Levels PAGEREF _Toc405561860 \h 108
HYPERLINK \l "_Toc405561861" 7.6 Fingerprint Service Information PAGEREF _Toc405561861 \h 109
HYPERLINK \l "_Toc405561862" 7.6.1 Submodality PAGEREF _Toc405561862 \h 109
HYPERLINK \l "_Toc405561863" 7.6.2 Image Size PAGEREF _Toc405561863 \h 109
HYPERLINK \l "_Toc405561864" 7.6.3 Image Content Type PAGEREF _Toc405561864 \h 110
HYPERLINK \l "_Toc405561865" 7.6.4 Image Density PAGEREF _Toc405561865 \h 110
HYPERLINK \l "_Toc405561866" 7.7 Face Service Information PAGEREF _Toc405561866 \h 110
HYPERLINK \l "_Toc405561867" 7.7.1 Submodality PAGEREF _Toc405561867 \h 110
HYPERLINK \l "_Toc405561868" 7.7.2 Image Size PAGEREF _Toc405561868 \h 110
HYPERLINK \l "_Toc405561869" 7.7.3 Image Content Type PAGEREF _Toc405561869 \h 111
HYPERLINK \l "_Toc405561870" 7.8 Iris Service Information PAGEREF _Toc405561870 \h 111
HYPERLINK \l "_Toc405561871" 7.8.1 Submodality PAGEREF _Toc405561871 \h 111
HYPERLINK \l "_Toc405561872" 7.8.2 Image Size PAGEREF _Toc405561872 \h 111
HYPERLINK \l "_Toc405561873" 7.8.3 Image Content Type PAGEREF _Toc405561873 \h 112
HYPERLINK \l "_Toc405561874" Appendix A. Parameter Details (Normative) PAGEREF _Toc405561874 \h 113
HYPERLINK \l "_Toc405561875" A.1 About PAGEREF _Toc405561875 \h 113
HYPERLINK \l "_Toc405561876" A.2 Connection Parameters PAGEREF _Toc405561876 \h 113
HYPERLINK \l "_Toc405561877" A.2.1 Last Updated PAGEREF _Toc405561877 \h 113
HYPERLINK \l "_Toc405561878" A.2.2 Inactivity Timeout PAGEREF _Toc405561878 \h 113
HYPERLINK \l "_Toc405561879" A.2.3 Maximum Concurrent Sessions PAGEREF _Toc405561879 \h 113
HYPERLINK \l "_Toc405561880" A.2.4 Least Recently Used (LRU) Sessions Automatically Dropped PAGEREF _Toc405561880 \h 114
HYPERLINK \l "_Toc405561881" A.3 Timeout Parameters PAGEREF _Toc405561881 \h 114
HYPERLINK \l "_Toc405561882" A.3.1 About PAGEREF _Toc405561882 \h 114
HYPERLINK \l "_Toc405561883" A.3.2 Initialization Timeout PAGEREF _Toc405561883 \h 114
HYPERLINK \l "_Toc405561884" A.3.3 Get Configuration Timeout PAGEREF _Toc405561884 \h 114
HYPERLINK \l "_Toc405561885" A.3.4 Set Configuration Timeout PAGEREF _Toc405561885 \h 115
HYPERLINK \l "_Toc405561886" A.3.5 Capture Timeout PAGEREF _Toc405561886 \h 115
HYPERLINK \l "_Toc405561887" A.3.6 Post-Acquisition Processing Time PAGEREF _Toc405561887 \h 115
HYPERLINK \l "_Toc405561888" A.3.7 Lock Stealing Prevention Period PAGEREF _Toc405561888 \h 115
HYPERLINK \l "_Toc405561889" A.4 Storage Parameters PAGEREF _Toc405561889 \h 116
HYPERLINK \l "_Toc405561890" A.4.1 About PAGEREF _Toc405561890 \h 116
HYPERLINK \l "_Toc405561891" A.4.2 Maximum Storage Capacity PAGEREF _Toc405561891 \h 116
HYPERLINK \l "_Toc405561892" A.4.3 Least-Recently Used Capture Data Automatically Dropped PAGEREF _Toc405561892 \h 116
HYPERLINK \l "_Toc405561893" A.5 Sensor Parameters PAGEREF _Toc405561893 \h 116
HYPERLINK \l "_Toc405561894" A.5.1 Modality PAGEREF _Toc405561894 \h 116
HYPERLINK \l "_Toc405561895" A.5.2 Submodality PAGEREF _Toc405561895 \h 117
HYPERLINK \l "_Toc405561896" Appendix B. Content Type Data (Normative) PAGEREF _Toc405561896 \h 118
HYPERLINK \l "_Toc405561897" B.1 About PAGEREF _Toc405561897 \h 118
HYPERLINK \l "_Toc405561898" B.2 General Type PAGEREF _Toc405561898 \h 118
HYPERLINK \l "_Toc405561899" B.3 Image Formats PAGEREF _Toc405561899 \h 118
HYPERLINK \l "_Toc405561900" B.4 Video Formats PAGEREF _Toc405561900 \h 118
HYPERLINK \l "_Toc405561901" B.5 Audio Formats PAGEREF _Toc405561901 \h 118
HYPERLINK \l "_Toc405561902" B.6 General Biometric Formats PAGEREF _Toc405561902 \h 119
HYPERLINK \l "_Toc405561903" B.7 ISO / Modality-Specific Formats PAGEREF _Toc405561903 \h 119
HYPERLINK \l "_Toc405561904" Appendix C. XML Schema (Informative) PAGEREF _Toc405561904 \h 120
HYPERLINK \l "_Toc405561905" Appendix D. Security (Informative) PAGEREF _Toc405561905 \h 122
HYPERLINK \l "_Toc405561906" D.1 About PAGEREF _Toc405561906 \h 122
HYPERLINK \l "_Toc405561907" D.2 References PAGEREF _Toc405561907 \h 122
HYPERLINK \l "_Toc405561908" D.3 Overview PAGEREF _Toc405561908 \h 123
HYPERLINK \l "_Toc405561909" D.4 Control Set Determination PAGEREF _Toc405561909 \h 123
HYPERLINK \l "_Toc405561910" D.4.1 L Security Controls Criteria PAGEREF _Toc405561910 \h 123
HYPERLINK \l "_Toc405561911" D.4.2 M Security Controls Criteria PAGEREF _Toc405561911 \h 123
HYPERLINK \l "_Toc405561912" D.4.3 H Security Controls Criteria PAGEREF _Toc405561912 \h 124
HYPERLINK \l "_Toc405561913" D.5 Recommended & Candidate Security Controls PAGEREF _Toc405561913 \h 124
HYPERLINK \l "_Toc405561914" D.5.1 L Security Controls PAGEREF _Toc405561914 \h 124
HYPERLINK \l "_Toc405561915" D.5.2 M Security Controls PAGEREF _Toc405561915 \h 125
HYPERLINK \l "_Toc405561916" D.5.3 H Security Controls PAGEREF _Toc405561916 \h 125
HYPERLINK \l "_Toc405561917" Appendix E. Acknowledgments (Informative) PAGEREF _Toc405561917 \h 126
HYPERLINK \l "_Toc405561918" Appendix F. Revision History (Informative) PAGEREF _Toc405561918 \h 128
Introduction
Motivation
The web services framework, has, in essence, begun to create a standard software communications bus in support of service-oriented architecture. Applications and services can plug in to the bus and begin communicating using standards tools. The emergence of this bus has profound implications for identity exchange.
Jamie Lewis, Burton Group, February 2005Forward to Digital Identity by Phillip J. Windley
As noted by Jamie Lewis, the emergence of web services as a common communications bus has profound implications. The next generation of biometric devices will not only need to be intelligent, secure, tamper-proof, and spoof resistant, but first, they will need to be interoperable.
These envisioned devices will require a communications protocol that is secure, globally connected, and free from requirements on operating systems, device drivers, form factors, and low-level communications protocols. WS-Biometric Devices is a protocol designed in the interest of furthering this goal, with a specific focus on the single process shared by all biometric systemsacquisition.
Terminology
This section contains terms and definitions used throughout this document. First time readers may desire to skip this section and revisit it as needed.
biometric capture device
a system component capable of capturing biometric data in digital form
client
a logical endpoint that originates operation requests
HTTP
Hypertext Transfer Protocol. Unless specified, the term HTTP refers to either HTTP as defined in [ REF RFCHTTP \h RFC-HTTP] or HTTPS as defined in [ REF RFC2660 \h RFC2660].
ISO
International Organization for Standardization
modality
a distinct biometric category or type of biometrictypically a short, high-level description of a human feature or behavioral characteristic (e.g., fingerprint, iris, face, or gait)
payload
the content of an HTTP request or response. An input payload refers to the XML content of an HTTP request. An output payload refers to the XML content of an HTTP response.
payload parameter
an operation parameter that is passed to a service within an input payload
profile
a list of assertions that a service must support
REST
Representational State Transfer
RESTful
a web service which employs REST techniques
sensor or biometric sensor
a single biometric capture device or a logical collection of biometric capture devices
sensor service
a middleware software component that exposes a biometric sensor to a client through web services
submodality
a distinct category or subtype within a biometric modality
target sensor or target biometric sensor
the biometric sensor made available by a particular service
URL parameter
a parameter passed to a web service by embedding it in the URL
Web service or service or WS
a software system designed to support interoperable machine-to-machine interaction over a network [ REF WSGloss \h \* MERGEFORMAT WSGloss]
XML
Extensible Markup Language [ REF XML \h XML]
Documentation Conventions
About
This section ( REF _Ref401904154 \w \h 1.3) describes the style and usage conventions used throughout this document.
Key Words
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in [ REF RFC2119 \h RFC2119].
Quotations
If the inclusion of a period within a quotation might lead to ambiguity as to whether or not the period should be included in the quoted material, the period will be placed outside the trailing quotation mark. For example, a sentence that ends in a quotation would have the trailing period inside the quotation, like this quotation punctuated like this. However, a sentence that ends in a URL would have the trailing period outside the quotation mark, such as http://example.com.
Machine-Readable Code
With the exception of some reference URLs, machine-readable information will typically be depicted with a mono-spaced font, such as this.
Sequence Diagrams
Throughout this document, sequence diagrams are used to help explain various scenarios. These diagrams are informative simplifications and are intended to help explain core specification concepts. Operations are depicted in a functional, remote procedure call style.
REF _Ref401902025 \h Figure 1 is an annotated sequence diagram that shows how an example sequence of HTTP request-responses is typically illustrated. The level of abstraction presented in the diagrams, and the details that are shown (or not shown) will vary according to the particular information being illustrated. First time readers may wish to skip this section and return to it as needed.
Figure SEQ Figure \* ARABIC 1. Example of a sequence diagram used in this document.
Each actor in the sequence diagram (i.e., a client or a server) has a swimlane that chronicles their interactions over time. Communication among the actors is depicted with arrows. In this diagram, there are three actors: Client A, a WS-BD Service, and Client B.
State information notable to the example is depicted in an elongated diamond shape within the swimlane of the relevant actor. In this example, it is significant that the initial lock owner for the Service actor is (none) and that the lock owner changes to {A1234567} after a communication from Client A.
Unless otherwise noted, a solid arrow represents the request (initiation) of an HTTP request; the opening of an HTTP socket connection and the transfer of information from a source to its destination. The arrow begins on the swimlane of the originator and ends on the swimlane of the destination. The order of the request and the operation name ( REF _Ref311027437 \r \h \* MERGEFORMAT 6.4 through REF _Ref311027456 \r \h \* MERGEFORMAT 6.17) are shown above the arrow. URL and/or payload parameters significant to the example are shown below the arrow. In this example, the first communication occurs when Client A opens a connection to the Service, initiating a lock request, where the sessionId parameter is {A1234567}.
Unless otherwise noted, a dotted arrow represents the response (completion) of a particular HTTP request; the closing of an HTTP socket connection and the transfer of information back from the destination to the source. The arrow starts on the originating requests destination and ends on the swimlane of actor that originated the request. The order of the request, and the name of the operation that being replied to is shown above the arrow. Significant data returned to the source is shown below the arrow ( REF _Ref311029050 \r \h \* MERGEFORMAT 3.14.2). Notice that the source, destination, and operation name provide the means to match the response corresponds to a particular requestthere is no other visual indicator. In this example, the second communication is the response to the lock request, where the service returns a status of success.
In general, {A1234567} and {B890B123} are used to represent session ids ( REF _Ref283989051 \r \h 2.5.4, REF _Ref311029483 \r \h 3.14.4, REF _Ref311029562 \r \h 6.4); {C1D10123...} and {D2E21234...} represent capture ids ( REF _Ref311029483 \r \h 3.14.4, REF _Ref311029498 \r \h 6.13).
References
[3GPP]3GPP, 3GPP TS 26.244 Transparent end-to-end packet switched streaming service (PSS) 3GPP file format (3GP), HYPERLINK "http://www.3gpp.org/DynaReport/26244.htm" http://www.3gpp.org/DynaReport/26244.htm, Retrieved 12 August 2014[3GPP2]3GPP2, C.S0050-B Version 1.0 3GPP2 File Formats for Multimedia Services, HYPERLINK "http://www.3gpp2.org/Public_html/specs/C.S0050-B_v1.0_070521.pdf" http://www.3gpp2.org/Public_html/specs/C.S0050-B_v1.0_070521.pdf, 18 May 2007[AIFF]Apple Computer, Inc., Audio Interchange File Format: "AIFF". A Standard for Sampled Sound Files Version 1.3, HYPERLINK "http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/AIFF/Docs/AIFF-1.3.pdf" http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/AIFF/Docs/AIFF-1.3.pdf, January 4, 1989[AN2K]Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Scar Mark & Tattoo (SMT) Information, HYPERLINK "http://www.nist.gov/customcf/get_pdf.cfm?pub_id=151453" http://www.nist.gov/customcf/get_pdf.cfm?pub_id=151453, 27 July 2000.[AN2K11]B. Wing, Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial & Other Biometric Information, HYPERLINK "http://www.nist.gov/customcf/get_pdf.cfm?pub_id=910136" http://www.nist.gov/customcf/get_pdf.cfm?pub_id=910136, November 2011.[AN2K7]R. McCabe, E. Newton, Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Other Biometric Information Part 1, HYPERLINK "http://www.nist.gov/customcf/get_pdf.cfm?pub_id=51174" http://www.nist.gov/customcf/get_pdf.cfm?pub_id=51174, 20 April 2007.[AN2K8]E. Newton et al., Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Other Biometric Information Part 2: XML Version, HYPERLINK "http://www.nist.gov/customcf/get_pdf.cfm?pub_id=890062" http://www.nist.gov/customcf/get_pdf.cfm?pub_id=890062, 12 August 2008.[ASF]Overview of the ASF Format, HYPERLINK "http://msdn.microsoft.com/en-us/library/windows/desktop/dd757562%28v=vs.85%29.aspx" http://msdn.microsoft.com/en-us/library/windows/desktop/dd757562%28v=vs.85%29.aspx, Retrieved 13 August 2014[ASX]Windows Media Metafile Elements Reference, HYPERLINK "http://msdn.microsoft.com/en-us/library/dd564668%28VS.85%29.aspx" http://msdn.microsoft.com/en-us/library/dd564668%28VS.85%29.aspx, Retrieved 13 August 2014[AVI]AVI RIFF File Format, HYPERLINK "http://msdn.microsoft.com/en-us/library/ms779636.aspx" http://msdn.microsoft.com/en-us/library/ms779636.aspx, Retrieved 12 August 2014[BDIF1007]ISO/IEC 19794-10:2007: Information technology Biometric data interchange formats Part 10: Hand geometry silhouette data[BDIF205]ISO/IEC 19794-2:2005/Cor 1:2009/Amd 1:2010: Information technology Biometric data interchange formats Part 2: Finger minutia data[BDIF306]ISO/IEC 19794-3:2006: Information technology Biometric data interchange formats Part 3: Finger pattern spectral data[BDIF405]
ISO/IEC 19794-4:2005: Information technology Biometric data interchange formats Part 4: Finger image data[BDIF505]ISO/IEC 19794-5:2005: Information technology Biometric data interchange formats Part 5: Face image data[BDIF605]ISO/IEC 19794-6:2005: Information technology Biometric data interchange formats Part 6: Iris image data[BDIF611]ISO/IEC 19794-6:2011: Information technology Biometric data interchange formats Part 6: Iris image data[BDIF707]ISO/IEC 19794-7:2007/Cor 1:2009: Information technology Biometric data interchange formats Part 7: Signature/sign time series data[BDIF806]ISO/IEC 19794-8:2006/Cor 1:2011: Information technology Biometric data interchange formats Part 8: Finger pattern skeletal data[BDIF907]ISO/IEC 19794-9:2007: Information technology Biometric data interchange formats Part 9: Vascular image data[BMP]BMP File Format, HYPERLINK "http://www.digicamsoft.com/bmp/bmp.html" http://www.digicamsoft.com/bmp/bmp.html[CBEFF2010]ISO/IEC 19785-3:2007/Amd 1:2010: Information technology Common Biometric Exchange Formats Framework Part 3: Patron format specifications with Support for Additional Data Elements[CMediaType]Media Types, HYPERLINK "http://www.iana.org/assignments/media-types/media-types.xhtml" http://www.iana.org/assignments/media-types/media-types.xhtml, 8 August 2014[H264]Y.-K. Wang et al., RTP Payload Format for H.264 Video, HYPERLINK "http://www.ietf.org/rfc/rfc6184.txt" http://www.ietf.org/rfc/rfc6184.txt, IETF RFC 6184, May 2011.[HTML5] HYPERLINK "http://www.w3.org/TR/2014/PR-html5-20140916/" HTML5 , R. Berjon, S. Faulkner, T. Leithead, E. Doyle Navara, E. O'Connor, S. Pfeiffer, Editors, W3C (work in progress), 16 September 2014, HYPERLINK "http://www.w3.org/TR/2014/PR-html5-20140916/" http://www.w3.org/TR/2014/PR-html5-20140916/. HYPERLINK "http://www.w3.org/TR/html5/" \o "Latest version of HTML5" Latest version available at HYPERLINK "http://www.w3.org/TR/html5/" http://www.w3.org/TR/html5/[JPEG]E. Hamilton, JPEG File Interchange Format, HYPERLINK "http://www.w3.org/Graphics/JPEG/jfif3.pdf" http://www.w3.org/Graphics/JPEG/jfif3.pdf, 1 September 1992.[MPEG]ISO/IEC 14496: Information technology Coding of audio-visual objects[MPEG1]ISO/IEC 11172-3:1993/Cor 1:1996 Information technology Coding of moving pictures and associated audio for digital storage media at up to about 1.5 Mbit/s -- Part 3: Audio[OGG]Xiph.org, HYPERLINK "http://xiph.org/ogg/" http://xiph.org/ogg/, Retrieved 12 August 2014[PNG] HYPERLINK "http://www.w3.org/TR/2003/REC-PNG-20031110" Portable Network Graphics (PNG) Specification (Second Edition) , D. Duce, Editor, W3C, 10 November 2003, HYPERLINK "http://www.w3.org/TR/2003/REC-PNG-20031110" http://www.w3.org/TR/2003/REC-PNG-20031110. HYPERLINK "http://www.w3.org/TR/PNG" \o "Latest version of Portable Network Graphics (PNG) Specification (Second Edition)" Latest version available at HYPERLINK "http://www.w3.org/TR/PNG" http://www.w3.org/TR/PNG[QTFF]Introduction to Quicktime File Format Specification, HYPERLINK "https://developer.apple.com/library/mac/documentation/QuickTime/QTFF/QTFFPreface/qtffPreface.html" https://developer.apple.com/library/mac/documentation/QuickTime/QTFF/QTFFPreface/qtffPreface.html, Retrieved 12 August 2014 [RFC1737]Sollins, K. and L. Masinter, "Functional Requirements for Uniform Resource Names", RFC 1737, December 1994, HYPERLINK "http://www.rfc-editor.org/info/rfc1737" http://www.rfc-editor.org/info/rfc1737.[RFC2045]Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996, HYPERLINK "http://www.rfc-editor.org/info/rfc2045" http://www.rfc-editor.org/info/rfc2045.[RFC2046]Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996, HYPERLINK "http://www.rfc-editor.org/info/rfc2046" http://www.rfc-editor.org/info/rfc2046.[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, HYPERLINK "http://www.rfc-editor.org/info/rfc2119" http://www.rfc-editor.org/info/rfc2119.[RFC2141]Moats, R., "URN Syntax", RFC 2141, May 1997, HYPERLINK "http://www.rfc-editor.org/info/rfc2141" http://www.rfc-editor.org/info/rfc2141.[RFC-HTTP]Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 2014, HYPERLINK "http://www.rfc-editor.org/info/rfc7230" http://www.rfc-editor.org/info/rfc7230.
Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, June 2014, HYPERLINK "http://www.rfc-editor.org/info/rfc7231" http://www.rfc-editor.org/info/rfc7231.
Fielding, R., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, June 2014, HYPERLINK "http://www.rfc-editor.org/info/rfc7232" http://www.rfc-editor.org/info/rfc7232.
Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, June 2014, HYPERLINK "http://www.rfc-editor.org/info/rfc7233" http://www.rfc-editor.org/info/rfc7233.
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 2014, HYPERLINK "http://www.rfc-editor.org/info/rfc7234" http://www.rfc-editor.org/info/rfc7234.[RFC2660]Rescorla, E. and A. Schiffman, "The Secure HyperText Transfer Protocol", RFC 2660, August 1999, HYPERLINK "http://www.rfc-editor.org/info/rfc2660" http://www.rfc-editor.org/info/rfc2660.[RFC3061]Mealling, M., "A URN Namespace of Object Identifiers", RFC 3061, February 2001, HYPERLINK "http://www.rfc-editor.org/info/rfc3061" http://www.rfc-editor.org/info/rfc3061.[RFC4122]Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2005, HYPERLINK "http://www.rfc-editor.org/info/rfc4122" http://www.rfc-editor.org/info/rfc4122.[SPHERE]National Institute of Standards and Technology, NIST Speech Header Resources, HYPERLINK "http://www.nist.gov/itl/iad/mig/tools.cfm" http://www.nist.gov/itl/iad/mig/tools.cfm, Retrieved 12 August 2014[TIFF]TIFF Revision 6.0, HYPERLINK "http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf" http://partners.adobe.com/public/developer/en/tiff/TIFF6.pdf, 3 June 1992.[WAVE]IBM Corporation and Microsoft Corporation, Multimedia Programming Interface and Data Specifications 1.0, HYPERLINK "http://www.tactilemedia.com/info/MCI_Control_Info.html" http://www.tactilemedia.com/info/MCI_Control_Info.html, August 1991[WSGloss]H. Haas, A. Brown, Web Services Glossary, HYPERLINK "http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/" http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/, February 11, 2004.[WSQ]WSQ Gray-Scale Fingerprint Image Compression Specification Version 3.1, HYPERLINK "https://fbibiospecs.org/docs/WSQ_Gray-scale_Specification_Version_3_1_Final.pdf" https://fbibiospecs.org/docs/WSQ_Gray-scale_Specification_Version_3_1_Final.pdf, 4 October 2010.[XML] HYPERLINK "http://www.w3.org/TR/2008/REC-xml-20081126/" Extensible Markup Language (XML) 1.0 (Fifth Edition) , T. Bray, J. Paoli, M., E. Maler, F. Yergeau, Editors, W3C, 26 November 2008, HYPERLINK "http://www.w3.org/TR/2008/REC-xml-20081126/" http://www.w3.org/TR/2008/REC-xml-20081126/. HYPERLINK "http://www.w3.org/TR/xml" \o "Latest version of Extensible Markup Language (XML) 1.0 (Fifth Edition)" Latest version available at HYPERLINK "http://www.w3.org/TR/xml" http://www.w3.org/TR/xml .[XML-NAMES] HYPERLINK "http://www.w3.org/TR/2009/REC-xml-names-20091208/" Namespaces in XML 1.0 (Third Edition) , T. Bray, D. Hollander, A. Layman, R. Tobin, H. S. Thompson, Editors, W3C , 8 December 2009, HYPERLINK "http://www.w3.org/TR/2009/REC-xml-names-20091208/" http://www.w3.org/TR/2009/REC-xml-names-20091208/. HYPERLINK "http://www.w3.org/TR/xml-names" \o "Latest version of Namespaces in XML 1.0 (Third Edition)" Latest version available at HYPERLINK "http://www.w3.org/TR/xml-names" http://www.w3.org/TR/xml-names[XMSCHEMA-1] HYPERLINK "http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/" XML Schema Part 1: Structures Second Edition, H. S. Thompson, D. Beech, M. Maloney, N. Mendelsohn, Editors, W3C, 28 October 2004, HYPERLINK "http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/" http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ HYPERLINK "http://www.w3.org/TR/xmlschema-1/" \o "Latest version of XML Schema Part 1: Structures Second Edition" Latest version available at HYPERLINK "http://www.w3.org/TR/xmlschema-1/" http://www.w3.org/TR/xmlschema-1/ .[XMSCHEMA-2]P. Biron, A. Malhotra, XML Schema Part 2: Datatypes Second Edition, HYPERLINK "http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/" http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/, W3C Recommendation. 28 October 2004.
Design Concepts and Architecture
About
This section describes the major design concepts and overall architecture of WS-BD. The main purpose of a WS-BD service is to expose a target biometric sensor to clients via web services.
This specification provides a framework for deploying and invoking core synchronous operations via lightweight web service protocols for the command and control of biometric sensors. The design of this specification is influenced heavily by the REST architecture; deviations and tradeoffs were made to accommodate the inherent mismatches between the REST design goals and the limitations of devices that are (typically) oriented for a single-user.
Interoperability
HYPERLINK "http://en.wikipedia.org/w/index.php?title=ISO/IEC_2382&action=edit&redlink=1" \o "ISO/IEC 2382 (page does not exist)" ISO/IEC 2382-1 (1993) defines interoperability as the capability to communicate, execute programs, or transfer data among various functional units in a manner that requires the user to have little to no knowledge of the unique characteristics of those units.
Conformance to a standard does not necessarily guarantee interoperability. An example is conformance to an HTML specification. A HTML page may be fully conformant to the HTML 4.0 specification, but it is not interoperable between web browsers. Each browser has its own interpretation of how the content should be displayed. To overcome this, web developers add a note suggesting which web browsers are compatible for viewing. Interoperable web pages need to have the same visual outcome independent of which browser is used.
A major design goal of WS-BD is to maximize interoperability, by minimizing the required knowledge of the unique characteristics of a component that supports WS-BD. The technical committee recognizes that conformance to this specification alone cannot guarantee interoperability; although a minimum degree of functionality is implied. Sensor profiles and accompanying conformance tests will need to be developed to provide better guarantees of interoperability, and will be released in the future.
Architectural Components
Overview
Before discussing the envisioned use of WS-BD, it is useful to distinguish between the various components that comprise a WS-BD implementation. These are logical components that may or may not correspond to particular physical boundaries. This distinction becomes vital in understanding WS-BDs operational models.
Client
A client is any software component that originates WS-BD operation requests. A client can be one of many hosted in a parent (logical or physical) component, and that a client can send requests to a variety of destinations.
This icon is used to depict an arbitrary WS-BD client. A personal digital assistant (PDA) is used to serve as a reminder that a client might be hosted on a non-traditional computer.
Sensor
A biometric sensor is any component that is capable of acquiring a digital biometric sample. Most sensor components are hosted within a dedicated hardware component, but this is not necessarily globally true. For example, a keyboard is a general input device, but can also be used for a keystroke dynamics biometric.
This icon is used to depict a biometric sensor. The icon has a vague similarity to a fingerprint scanner, but should be thought of as an arbitrary biometric sensor.The term sensor is used in this document in a singular sense, but may in fact be referring to multiple biometric capture devices. Because the term sensor may have different interpretations, practitioners are encouraged to detail the physical and logical boundaries that define a sensor for their given context.
Sensor Service
The sensor service is the middleware software component that exposes a biometric sensor to a client through web services. The sensor service adapts HTTP request-response operations to biometric sensor command & control.
This icon is used to depict a sensor service. The icon is abstract and has no meaningful form, just as a sensor service is a piece of software that has no physical form.Intended Use
Each implementation of WS-BD will be realized via a mapping of logical to physical components. A distinguishing characteristic of an implementation will be the physical location of the sensor service component. WS-BD is designed to support two scenarios:
Physically separated. The sensor service and biometric sensor are hosted by different physical components. A physically separated service is one where there is both a physical and logical separation between the biometric sensor and the service that provides access to it.
Physically integrated. The sensor service and biometric sensor are hosted within the same physical component. A physically integrated service is one where the biometric sensor and the service that provides access to it reside within the same physical component.
REF _Ref279652587 \h \* MERGEFORMAT Figure 2 depicts a physically separated service. In this scenario, a biometric sensor is tethered to a personal computer, workstation, or server. The web service, hosted on the computer, listens for communication requests from clients. An example of such an implementation would be a USB fingerprint scanner attached to a personal computer. A lightweight web service, running on that computer could listen to requests from local (or remote) clientstranslating WS-BD requests to and from biometric sensor commands.
Figure SEQ Figure \* ARABIC 2. A physically separated WS-Biometric Devices (WS-BD) implementation.
REF _Ref316298382 \h \* MERGEFORMAT Figure 3 depicts a physically integrated service. In this scenario, a single hardware device has an embedded biometric sensor, as well as a web service. Analogous (but not identical) functionality is seen in many network printers; it is possible to point a web browser to a local network address, and obtain a web page that displays information about the state of the printer, such as toner and paper levels (WS-BD enabled devices do not provide web pages to a browser). Clients make requests directly to the integrated device; and a web service running within an embedded system translates the WS-BD requests to and from biometric sensor commands.
Figure SEQ Figure \* ARABIC 3. A physically integrated WS-Biometric Devices (WS-BD) implementation.
The separated versus integrated distinction is a simplification with a potential for ambiguity. For example, one can imagine putting a hardware shell around a USB fingerprint sensor connected to a small form-factor computer. Inside the shell, the sensor service and sensor are on different physical components. Outside the shell, the sensor service and sensor appear integrated. Logical encapsulations, i.e., layers of abstraction, can facilitate analogous hiding. The definition of what constitutes the same physical component depends on the particular implementation and the intended level of abstraction. Regardless, it is a useful distinction in that it illustrates the flexibility afforded by leveraging highly interoperable communications protocols. As suggested in REF _Ref363506931 \r \h 2.3.3 practitioners may need to clearly define appropriate logical and physical boundaries for their own context of use.
General Service Behavior
About
This section ( REF _Ref286223445 \w \h 2.5) describes the general behavior of WS-BD clients and services.
Security Model
In this version of the specification, it is assumed that if a client is able to establish a connection with the sensor service, then the client is fully authorized to use the service. This implies that all successfully connected clients have equivalent access to the same service. Clients might be required to connect through various HTTP protocols, such as HTTPS with client-side certificates, or a more sophisticated protocol such as Open Id (http://openid.net/) and/or OAuth.
Specific security measures are out of scope of this specification, but should be carefully considered when implementing a WS-BD service. Some recommended solutions to general scenarios are outlined REF _Ref394318137 \r \h Appendix D.
HTTP Request-Response Usage
Most biometrics devices are inherently single useri.e., they are designed to sample the biometrics from a single user at a given time. Web services, on the other hand, are intended for stateless and multiuser use. A biometric device exposed via web services must therefore provide a mechanism to reconcile these competing viewpoints.
Notwithstanding the native limits of the underlying web server, WS-BD services must be capable of handling multiple, concurrent requests. Services must respond to requests for operations that do not require exclusive control of the biometric sensor and must do so without waiting until the biometric sensor is in a particular state.
Because there is no well-accepted mechanism for providing asynchronous notification via REST, each individual operation must block until completion. That is, the web server does not reply to an individual HTTP request until the operation that is triggered by that request is finished.
Individual clients are not expected to pollrather they make a single HTTP request and block for the corresponding result. Because of this, it is expected that a client would perform WS-BD operations on an independent thread, so not to interfere with the general responsiveness of the client application. WS-BD clients therefore must be configured in such a manner such that individual HTTP operations have timeouts that are compatible with a particular implementation.
WS-BD operations may be longer than typical REST services. Consequently, there is a clear need to differentiate between service level errors and HTTP communication errors. WS-BD services must pass-through the status codes underlying a particular request. In other words, services must not use (or otherwise piggyback) HTTP status codes to indicate failures that occur within the service. If a service successfully receives a well-formed request, then the service must return the HTTP status code 200299 indicating such. Failures are described within the contents of the XML data returned to the client for any given operation. The exception to this is when the service receives a poorly-formed request (i.e., the XML payload is not valid), then the service may return the HTTP status code 400, indicating a bad request.
This is deliberately different from REST services that override HTTP status codes to provide service-specific error messages. Avoiding the overloading of status codes is a pattern that facilitates the debugging and troubleshooting of communication versus client & service failures.
Design Note SEQ DesignNote \* MERGEFORMAT 1 (Informative): Overriding HTTP status codes is just one example of the rich set of features afforded by HTTP; content negotiation, entity tags (e-tags), and preconditions are other features that could be leveraged instead of recreated (to some degree) within this specification. However, the technical commitee avoided the use of these advanced HTTP features in this version of the specification for several reasons:
To reduce the overall complexity required for implementation.
To ease the requirements on clients and servers (particularly since the HTTP capabilities on embedded systems may be limited).
To avoid dependencies on any HTTP feature that is not required (such as entity tags).
In summary, the goal for this initial version of the specification is to provide common functionality across the broadest set of platforms. As this standard evolves, the technical committee will continue to evaluate the integration of more advanced HTTP features, as well as welcome feedback on their use from users and/or implementers of the specification.
Client Identity
Before discussing how WS-BD balances single-user vs. multi-user needs, it is necessary to understand the WS-BD model for how an individual client can easily and consistently identify itself to a service.
HTTP is, by design, a stateless protocol. Therefore, any persistence about the originator of a sequence of requests must be built in (somewhat) artificially to the layer of abstraction above HTTP itself. This is accomplished in WS-BD via a sessiona collection of operations that originate from the same logical endpoint. To initiate a session, a client performs a registration operation and obtains a session identifier (or session id). During subsequent operations, a client uses this identifier as a parameter to uniquely identify itself to a server. When the client is finished, it is expected to close a session with an unregistration operation. To conserve resources, services may automatically unregister clients that do not explicitly unregister after a period of inactivity (see REF _Ref280249726 \n \h \* MERGEFORMAT 6.5.3.2).
This use of a session id directly implies that the particular sequences that constitute a session are entirely the responsibility of the client. A client may opt to create a single session for its entire lifetime, or, may open (and close) a session for a limited sequence of operations. WS-BD supports both scenarios.
It is possible, but discouraged, to implement a client with multiple sessions with the same service simultaneously. For simplicity, and unless otherwise stated, this specification is written in a manner that assumes that a single client maintains a single session id. (This can be assumed without loss of generality, since a client with multiple sessions to a service could be decomposed into sub-clientsone sub- client per session id.)
Just as a client may maintain multiple session ids, a single session id may be shared among a collection of clients. By sharing the session id, a biometric sensor may then be put in a particular state by one client, and then handed-off to another client. This specification does not provide guidance on how to perform multi-client collaboration. However, session id sharing is certainly permitted, and a deliberate artifact of the convention of using of the session id as the client identifier. Likewise, many-to-many relationships (i.e., multiple session ids being shared among multiple clients) are also possible, but should be avoided.
Sensor Identity
A WS-BD service must be exposed to potential clients by a unique URI that serves as entry point for that service.
Implementers should map each target biometric sensor to a single service; that is, independent sensors should be exposed via different URIs. However, just as it is possible for a client to communicate with multiple services, a host can be responsible for controlling multiple target biometric sensors.
Example SEQ Example \* MERGEFORMAT 1: REF _Ref284835287 \h \* MERGEFORMAT Figure 4 shows a physically separate implementation where a single host machine controls two biometric sensorsone fingerprint scanner and one digital camera. The devices act independently and are therefore exposed via two different servicesone at the URL http://wsbd/fingerprint and one at http://wsbd/camera.
Figure SEQ Figure \* ARABIC 4. Independent sensors controlled by separate services.
A service that controls multiple biometric devices simultaneously (e.g., an array of cameras with synchronized capture) should be exposed via the same endpoint; this SHOULD NOT be the preferred architecture if the sensors would need to be addressed or controlled separately.
Figure SEQ Figure \* ARABIC 5. A sensor array controlled by a single service.
Example SEQ Example \* MERGEFORMAT 2: REF _Ref284835452 \h \* MERGEFORMAT Figure 5 shows a physically separate implementation where a single host machine controls a pair of cameras used for stereo vision. The cameras act together as a single logical sensor and are both exposed via the same service, http://wsbd/camera_array. The left and right camera are not individually addressable because the service is exposing both by a single endpoint. If the left and right camera needed to be separately addressable, then the host should expose two servicesone for each camerahttp://wsbd/left_camera and http://wsbd/right_camera.
A biometric sensor should not be exposed by more than one service at a time as it can significantly increase the complexity of implementation.
Locking
Overview and General Behavior
WS-BD uses a lock to satisfy two complementary requirements:
A service must have exclusive, sovereign control over biometric sensor hardware to perform a particular sensor operation such as initialization, configuration, or capture.
A client needs to perform an sequence of sensor operations and not be interrupted by another client
Each WS-BD service exposes a single lock (one per service) that controls access to the sensor. Clients obtain the lock in order to perform a sequence of operations that should not be interrupted. Obtaining the lock is an indication to the server (and indirectly to peer clients) that (1) a series of sensor operations is about to be initiated and (2) that server may assume sovereign control of the biometric sensor. There must only be a single lock per serviceregardless of the number of underlying biometric sensors under the services control. (This is one of the reasons why implementers should map each target biometric sensor to a single endpoint.)
A client releases the lock upon completion of its desired sequence of tasks. This indicates to the server (and indirectly to peer clients) that the uninterruptable sequence of operations is finished. A client may obtain and release the lock many times within the same session or a client may open and close a session for each pair of lock/unlock operations. This decision is entirely dependent on a particular client.
The statement that a client may own or hold a lock is a convenient simplification that makes it easier to understand the client-server interaction. In reality, each sensor service maintains a unique global variable that contains a session id. The originator of that session id can be thought of as the client that holds the lock to the service. Clients are expected to release the lock after completing their required sensor operations, but there is lock stealinga mechanism for forcefully releasing locks. This feature is necessary to ensure that one client cannot hold a lock indefinitely, denying its peers access to the biometric sensor.
As stated previously (see REF _Ref283989051 \r \h 2.5.4), it is implied that all successfully connected clients enjoy the same access privileges. Each client is treated the same and are expected to work cooperatively with each other. This is critically important, because it is this implied equivalence of trust that affords a lock stealing operation.
Design Note SEQ DesignNote \* MERGEFORMAT 2 (Informative): In the early development states of this specification, the specification designers considered having a single, atomic sensor operation that performed initialization, configuration and capture. This would avoid the need for locks entirely, since a client could then be ensured (if successful), the desired operation completed as requested. However, given the high degree of variability of sensor operations across different sensors and modalities, the explicit locking was selected so that clients could have a higher degree of control over a service and a more reliable way to predict timing. Regardless of the enforcement mechanism, it is undesirable if once a well-behaved client started an operation and a rogue client changed the internal state of the sensor midstream.
WS-BD only offers the core locking, unlocking, and lock stealing operations. Any other lock coordination is outside of scope of this specification and is the clients responsibility.
Pending Operations
Changing the state of the lock must have no effect on pending (i.e., currently running) sensor operations. That is, a service must not interrupt ongoing sensor operations even if a client unlocks, steals, or re-obtains a service lock. In this case, overlapping sensor operations are prevented by sensor operations returning sensorBusy.
Operations Summary
All WS-BD operations fall into one of eight categories:
Registration
Locking
Information
Initialization
Configuration
Capture
Download
Cancellation
Of these, the initialization, configuration, capture, and cancellation operations are all sensor operations (i.e., they require exclusive sensor control) and require locking. Registration, locking, and download are all non-sensor operations. They do not require locking and (as stated earlier) must be available to clients regardless of the status of the biometric sensor.
Download is not a sensor operation as this allows for a collection of clients to dynamically share acquired biometric data. One client could perform the capture and hand off the download responsibility to a peer.
The following is a brief summary of each type of operation:
Registration operations open and close (unregister) a session.
Locking operations are used by a client to obtain the lock, release the lock, and steal the lock.
Information operations query the service for information about the service itself, such as the supported biometric modalities, and service configuration parameters.
The initialization operation prepares the biometric sensor for operation.
Configuration operations get or set sensor parameters.
The capture operation signals to the sensor to acquire a biometric.
Download operations transfer the captured biometric data from the service to the client.
Sensor operations can be stopped by the cancellation operation.
Idempotency
The W3C Web Services glossary [ REF WSGloss \h WSGloss] defines idempotency as:
[the] property of an interaction whose results and side-effects are the same whether it is done one or multiple times.
When regarding an operations idempotence, it should be assumed no other operations occur in between successive operations, and that each operation is successful. Notice that idempotent operations may have side-effectsbut the final state of the service must be the same over multiple (uninterrupted) invocations.
The following example illustrates idempotency using an imaginary web service.
Example SEQ Example \* MERGEFORMAT 3: A REST-based web service allows clients to create, read, update, and delete customer records from a database. A client executes an operation to update a customers address from 123 Main St to 100 Broad Way.
Suppose the operation is idempotent. Before the operation, the address is 123 Main St. After one execution of the update, the server returns success, and the address is 100 Broad Way. If the operation is executed a second time, the server again returns success, and the address remains 100 Broad Way.
Now suppose that when the operation is executed a second time, instead of returning success, the server returns no update made, since the address was already 100 Broad Way. Such an operation is not idempotent, because executing the operation a second time yielded a different result than the first execution.
The following is an example in the context of WS-BD.
Example SEQ Example \* MERGEFORMAT 4: A service has an available lock. A client invokes the lock operation and obtains a success result. A subsequent invocation of the operation also returns a success result. The operation being idempotent means that the results (success) and side-effects (a locked service) of the two sequential operations are identical.
To best support robust communications, WS-BD is designed to offer idempotent services whenever possible.
Service Lifecycle Behavior
The lifecycle of a service (i.e., when the service starts responding to requests, stops, or is otherwise unavailable) must be modeled after an integrated implementation. This is because it is significantly easier for a physically separated implementation to emulate the behavior of a fully integrated implementation than it is the other way around. This requirement has a direct effect on the expected behavior of how a physically separated service would handle a change in the target biometric sensor.
Consequently, this specification does NOT make any specific recommendations on how a WS-BD service should be started, stopped, or reset. This (a) reflects the connectionless nature of HTTP but also (b) allows the host environment maximum flexibility on how to implement service availability. For example, a manufacturer of an embedded device might elect to have the device run a service as long as the device is powered on.
Specifically, on a desktop computer, hot-swapping the target biometric sensor is possible through an operating systems plug-and-play architecture. By design, this specification does not assume that it is possible to replace a biometric sensor within an integrated device. Therefore, having a physically separated implementation emulate an integrated implementation provides a simple means of providing a common level of functionality.
By virtue of the stateless nature of the HTTP protocol, a client has no simple means of detecting if a web service has been restarted. For most web communications, a client should not require thisit is a core capability that constitutes the robustness of the web. Between successive web requests, a web server might be restarted on its host any number of times. In the case of WS-BD, replacing an integrated device with another (configured to respond on the same endpoint) is an effective restart of the service. Therefore, by the emulation requirement, replacing the device within a physically separated implementation must behave similarly.
If the service is written in a robust manner, then a client SHOULD NOT be directly affected by a service restart, For example, upon detecting a new target biometric sensor, a robust server could quiesce (refuse all new requests until pending requests are completed) and automatically restart.
Upon restarting, services should return to a fully reset statei.e., all sessions should be dropped, and the lock should not have an owner. However, a high-availability service may have a mechanism to preserve state across restarts, but is significantly more complex to implement (particularly when using integrated implementations!). A client that communicated with a service that was restarted would lose both its session and the service lock (if held). With the exception of the get service info operation, through various fault statuses a client would receive indirect notification of a service restart. If needed, a client could use the services common info timestamp ( REF _Ref284933767 \r \h A.2.1) to detect potential changes in the get service info operation.
Data Dictionary
About
This section contains descriptions of the data elements that are contained within the WS-BD data model. Each data type is described via an accompanying XML Schema type definition [ REF XMSCHEMA1 \h XMSCHEMA-1, REF XMSCHEMA2 \h XMSCHEMA-2].
Refer to REF _Ref363507062 \r \h Appendix A for a complete XML schema containing all types defined in this specification.
important: XML Schema (and fragments) are used throughout this section and this document for the convenience of the reader so that the document may be self-contained. However, in the event that there is a discrepancy between this document and the electronic version of the schema that accompanies this specification, the electronic version shall be the authoritative source.
Namespaces
REF _Ref401924137 \h Table 1 lists the namespaces and corresponding namespace prefixes are used throughout this document.
Table SEQ Table \* ARABIC 1. Namespaces
PrefixNamespaceRemarksxs HYPERLINK "http://www.w3.org/2001/XMLSchema" http://www.w3.org/2001/XMLSchemaThe xs namespace refers to the XML Schema specification. Definitions for the xs data types (i.e., those not explicitly defined here) can be found in [ REF XMSCHEMA2 \h XMSCHEMA-2].xsihttp://www.w3.org/2001/XMLSchema-instanceThe xsi namespace allows the schema to refer to other XML schemas in a qualified way.wsbdhttp://docs.oasis-open.org/biometrics/ns/ws-bd-1.0The wsbd namespace is a uniform resource name [ REF RFC1737 \h RFC1737, REF RFC2141 \h RFC2141] consisting of an object identifier [ REF RFC3061 \h RFC3061] reserved for this specifications schema. This namespace can be written in ASN.1 notation as {joint-iso-ccitt(2) country(16) us(840) organization(1) gov(101) csor(3) biometrics(9) wsbd(3) version1(1)}.All of the datatypes defined in this section (3) belong to the wsbd namespace defined in the above table. If a datatype is described in the document without a namespace prefix, the wsbd prefix is assumed.
UUID
A UUID is a unique identifier as defined in [RFC4122]. A service must use UUIDs that conform to the following XML Schema type definition.
Example SEQ Example \* MERGEFORMAT 5: Each of the following is a well-formed UUID.
E47991C3-CA4F-406A-8167-53121C0237BA
10fa0553-9b59-4D9e-bbcd-8D209e8d6818
161FdBf5-047F-456a-8373-D5A410aE4595
Dictionary
A Dictionary is a generic container used to hold an arbitrary collection of name-value pairs.
EXAMPLE SEQ Example \* MERGEFORMAT 6: A query to get the metadata of a capture returns a dictionary of supported settings and the values at the time of capture. Enclosing tags (which may vary) are omitted.
-
imageWidth
640
-
imageHeight
640
-
captureDate
2011-01-01T01:23:45Z
Dictionary instances are nestablei.e., the value element of one Dictionary can contain another Dictionary. The use of xs:anyType allows for an XML element of any structure or definition to be used. Using types not defined in this document or types defined in W3s XML Schema recommendations [ REF XMSCHEMA1 \h XMSCHEMA-1, REF XMSCHEMA2 \h XMSCHEMA-2] might require a client to have unique knowledge about the service. Because the requirement of unique knowledge negatively impacts interoperability, using such elements is discouraged.
Parameter
Overview
A Parameter is a container used to describe the parameters or settings of a service or sensor.
See REF _Ref363507289 \r \h 4 for more information on metadata and the use of Parameter.
Element Summary
REF _Ref401924240 \h Table 2 contains a description of each Parameter element.
Table SEQ Table \* ARABIC 2. Parameterelement summary
ElementDescriptionnameThe name of the parameter.typeThe fully qualified type of the parameter.readOnlyWhether or not this parameter is read-only.supportsMultipleWhether or not this parameter can support multiple values for this parameter ( REF _Ref301439007 \r \h \* MERGEFORMAT 3.5.2.1).defaultValueThe default value of this parameter.allowedValuesA list of allowed values for this parameter ( REF _Ref301439032 \r \h \* MERGEFORMAT 3.5.2.2).Supports Multiple Element
In some cases, a parameter MAY require multiple values. This flag specifies whether the parameter is capable of multiple values.
When supportsMultiple is true, communicating values must be done through a defined array type. If a type-specialized array is defined in this specification, such as a StringArray ( REF _Ref310585938 \r \h 3.8) for xs:string, such type should be used. The generic Array ( REF _Ref310844662 \r \h 3.7) type must be used in all other cases.
The parameters type element must be the qualified name of a single value. For example, if the parameter expects multiple strings during configuration, then the type must be xs:string and not StringArray.
Example SEQ Example \* MERGEFORMAT 7: An iris scanner might have the ability to capture a left iris, right iris, and/or frontal face image simultaneously. This example configures the scanner to capture left and right iris images together.
The first code block is what the service exposes to the clients:
submodality
xs:string
false
true
leftIris
rightIris
leftIris
rightIris
frontalFace
The second code block is how a client would configure this parameter for simultaneous left and right iris capture.
-
submodality
leftIris
rightIris
The client configures the submodality by supplying a StringArray with two elements: left and rightthis tells the service to capture both the left and right iris.
The resulting captured data must specify the respective submodality for each captured item in its metadata.
In both code blocks, enclosing tags (which may vary) are omitted.
Allowed Values
For parameters that are not read-only and have restrictions on what values it may have, this allows the service to dynamically expose it to its clients.
Example SEQ Example \* MERGEFORMAT 8: The following code block demonstrates a parameter, CameraFlash, with only three valid values. Enclosing tags (which may vary) are omitted.
cameraFlash
xs:string
false
false
auto
on
off
auto
Parameters requiring a range of values should be described by using Range ( REF _Ref302380026 \r \h \* MERGEFORMAT 3.6). Because the allowed type is not the same as its parameter type, a service must have logic to check for a Range and any appropriate validation.
Example SEQ Example \* MERGEFORMAT 9: The following code block demonstrates a parameter, CameraZoom, where the allowed value is of type Range and consists of integers. Enclosing tags (which may vary) are omitted.
cameraZoom
xs:integer
false
false
0
0
100
If a configurable parameter has no restrictions on its value then the parameter must not include the allowedValues element.
Range
A Range is a container used to describe a range of data, and whether the upper and lower bounds are exclusive. The upper and lower bounds must be inclusive by default.
Example SEQ Example \* MERGEFORMAT 10: An example range of numbers from 0 to 100. The minimum is exclusive while the maximum is inclusive. Enclosing tags (which may vary) are omitted.
0
100
true
false
REF _Ref401924269 \h Table 3 provides a description of each Range element.
Table SEQ Table \* ARABIC 3. Rangeelement summary
ElementDescriptionminimumThe lower bound of the range.maximumThe upper bound of the range.minimumIsExclusiveBoolean indicating whether the lower bound is exclusive or not. This is true by default.maximumIsExclusiveBoolean indicating whether the upper bound is exclusive or not. This is true by default.Array
An Array is a generic container used to hold a collection of elements.
Example SEQ Example \* MERGEFORMAT 11: In the following fragment the values flatLeftThumb and flatRightThumb are of type xs:anyType, and are likely to be deserialized as a generic object.
flatLeftThumbflatRightThumb
Example SEQ Example \* MERGEFORMAT 12: In the following fragment, the two values are of different types.
false1024
Example SEQ Example \* MERGEFORMAT 13: In the following fragment, the array contains a single element.
2.0
StringArray
A StringArray is a generic container used to hold a collection of strings.
Example SEQ Example \* MERGEFORMAT 14: Each line below is an example of a valid StringArray. Enclosing tags (which may vary) are omitted.
flatLeftThumbflatRightThumb
value1value2
sessionId
UuidArray
A UuidArray is a generic container used to hold a collection of UUIDs.
Example SEQ Example \* MERGEFORMAT 15: The following code fragment is an example of a single UuidArray with three elements. Enclosing tags (which may vary) are omitted.
E47991C3-CA4F-406A-8167-53121C0237BA
10fa0553-9b59-4D9e-bbcd-8D209e8d6818
161FdBf5-047F-456a-8373-D5A410aE4595
ResourceArray
A ResourceArray is a generic container used to hold a collection of Resources ( REF _Ref401923954 \w \h 3.11).
EXAMPLE SEQ Example \* MERGEFORMAT 16: The following code fragment is an example of a single ResourceArray with two elements. Enclosing tags (which may vary) are omitted.
file:///tmp/test.pngimage/png
http://192.168.1.1/robots.txttext/plain
Resource
Resource is a container to describe a resource at a specified URI.
Resolution
Resolution is a generic container to describe values for a width and height and optionally a description of the unit.
REF _Ref401924394 \h Table 4 provides a description of each Size element.
Table SEQ Table \* ARABIC 4. Resolutionelement summary
ElementDescriptionwidthThe decimal value of the widthheightThe decimal value of the heightunitA string describing the units of the width and height valuesStatus
The Status represents a common enumeration for communicating state information about a service.
REF _Ref401910123 \h Table 5 defines all of the potential values for the Status enumeration.
Table SEQ Table \* ARABIC 5. Potential values for the Status enumeration.
ValueDescriptionsuccessThe operation completed successfully.failureThe operation failed. The failure was due to a web service (as opposed to a sensor error).invalidIdThe provided id is not valid. This can occur if the client provides a (session or capture) id that is either:
unknown to the server (i.e., does not correspond to a known registration or capture result), or
the session has been closed by the service ( REF _Ref280249726 \r \h \* MERGEFORMAT 6.5.3.2)
(See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for information on parameter failures.)canceledThe operation was canceled.
A sensor service may cancel its own operation, for example, if an operation is taking too long. This can happen if a service maintains its own internal timeout that is shorter than a sensor timeout.canceledWithSensorFailureThe operation was canceled, but during (and perhaps because of) cancellation, a sensor failure occurred.
This particular status accommodates for hardware that may not natively support cancellation. sensorFailureThe operation could not be performed because of a biometric sensor (as opposed to web service) failure.
NOTE: Clients that receive a status of sensorFailure should assume that the sensor will need to be reinitialized in order to restore normal operation. lockNotHeldThe operation could not be performed because the client does not hold the lock.
This status implies that at the time the lock was queried, no other client currently held the lock. However, this is not a guarantee that any subsequent attempts to obtain the lock will succeed.lockHeldByAnotherThe operation could not be performed because another client currently holds the lock.initializationNeededThe operation could not be performed because the sensor requires initialization.configurationNeededThe operation could not be performed because the sensor requires configuration.sensorBusyThe operation could not be performed because the sensor is currently performing another task that prohibits the request.
Services may self-initiate an activity that triggers a sensorBusy result. That is, it may not be possible for a client to trace back a sensorBusy status to any particular operation. An automated self-check, heartbeat, or other activity such as a data transfer may place the target biometric sensor into a busy mode. (See REF _Ref284591070 \r \h \* MERGEFORMAT 6.14.3.3 for information about post-acquisition processing.)sensorTimeoutThe operation was not performed because the biometric sensor experienced a timeout.
The most common cause of a sensor timeout would be a lack of interaction with a sensor within an expected timeframe. unsupportedThe service does not support the requested operation. (See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for information on parameter failures.)badValueThe operation could not be performed because a value provided for a particular parameter was either (a) an incompatible type or (b) outside of an acceptable range. (See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for information on parameter failures.)noSuchParameterThe operation could not be performed because the service did not recognize the name of a provided parameter. (See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for information on parameter failures.)preparingDownloadThe operation could not be performed because the service is currently preparing captured data for download. (See REF _Ref284591070 \r \h \* MERGEFORMAT 6.14.3.3)Many of the permitted status values have been designed specifically to support physically separate implementationsa scenario where it is easier to distinguish between failures in the web service and failures in the biometric sensor. This is not to say that within an integrated implementation such a distinction is not possible, only that some of the status values are more relevant for physically separate versions.
For example, a robust service would allow all sensor operations to be canceled with no threat of a failure. Unfortunately, not all commercial, off-the-shelf (COTS) sensors natively support cancellation. Therefore, the canceledWithSensorFailure status is offered to accommodate this. Implementers can still offer cancellation, but have a mechanism to communicate back to the client that sensor initialization may be required.
Result
Overview
Unless a service returns with an HTTP error, all WS-BD operations must reply with an HTTP message that contains an element of a Result type that conforms to the following XML Schema snippet.
Terminology Shorthand
Since a Result is the intended outcome of all requests, this document may state that an operation returns a particular status value. This is shorthand for a Result output payload with a status element containing that value.
Example SEQ Example \* MERGEFORMAT 17: The following result payload returns success. A result might contain other child elements depending on the specific operation and result statussee REF _Ref363507582 \r \h 5 for operations and their respective details.
success
Likewise, the same shorthand is implied by a client receiving a status, or an operation yielding a status.
Required Elements
Notice that from a XML Schema validation perspective [XMSCHEMA-1], a schema-valid Result must contain a status element, and may contain any of the remaining elements.
The specific permitted elements of a Result are determined via a combination of (a) the operation, and (b) the results status. That is, different operations will have different requirements on which elements are permitted or forbidden, depending on that operations status.
Example SEQ Example \* MERGEFORMAT 18: As will be detailed later ( REF _Ref284403689 \r \h 6.4.5.2 and REF _Ref284403698 \r \h 6.6.5.2), a register operation returning a status of success must also populate the sessionId element. However, a try lock operation that returns a status of success cannot populate any element other than status.
Design note SEQ DesignNote \* MERGEFORMAT 3 (Informative): An XML inheritance hierarchy could have been used to help enforce which elements are permitted under which circumstances. However, a de-normalized representation (in which all of the possible elements are valid with respect to a schema) was used to simplify client and server implementation. Further, this reduces the burden of managing an object hierarchy for the sake of enforcing simple constraints.
Element Summary
REF _Ref401910158 \h Table 6 provides a brief description of each element of a Result.
Table SEQ Table \* ARABIC 6. Result element summary
ElementDescriptionstatusThe disposition of the operation. All Result elements must contain a status element. (Used in all operations.)badFieldsThe list of fields that contain invalid or ill-formed values. (Used in almost all operations.)captureIdsIdentifiers that may be used to obtain data acquired from a capture operation ( REF _Ref281902895 \r \h \* MERGEFORMAT 6.13, REF _Ref281902896 \r \h \* MERGEFORMAT 6.14).metadataThis field may hold
metadata for the service ( REF _Ref310253605 \r \h \* MERGEFORMAT 6.9), or
a service and sensors configuration ( REF _Ref281306284 \r \h \* MERGEFORMAT 6.11, REF _Ref281306288 \r \h \* MERGEFORMAT 6.12), or
metadata relating to a particular capture ( REF _Ref310253632 \r \h \* MERGEFORMAT 6.14, REF _Ref310253637 \r \h \* MERGEFORMAT 6.15, REF _Ref310253640 \r \h \* MERGEFORMAT 6.16)
(See REF _Ref363507689 \r \h 4 for more information regarding metadata)messageA string providing informative detail regarding the output of an operation. (Used in almost all operations.)sensorDataThe biometric data corresponding to a particular capture identifier ( REF _Ref281903122 \r \h \* MERGEFORMAT 6.14, REF _Ref281902544 \r \h \* MERGEFORMAT 6.16).sessionIdA unique session identifier ( REF _Ref281814772 \r \h \* MERGEFORMAT 6.4).Validation
The provided XML schemas may be used for initial XML validation. It should be noted that these are not strict schema definitions and were designed for easy consumption of web service/code generation tools. Additional logic should be used to evaluate the contents and validity of the data where the schema falls short. For example, additional logic will be necessary to verify the contents of a Result are accurate as there is not a different schema definition for every combination of optional and mandatory fields.
A service must have separate logic validating parameters and their values during configuration. For example, if the type of the parameter is an integer and an allowed value is a Range, the service must handle this within the service as it cannot be appropriately validated using XML schema.
Metadata
About
Metadata can be broken down into three smaller categories: service information, sensor information or configuration, and capture information. Metadata can be returned in two forms: as a key/value pair within a Dictionary or a Dictionary of Parameter types.
Service Information
Service information includes read-only parameters unrelated to the sensor as well as parameters that can be set. Updating the values of a parameter should be done in the set configuration operation.
Service information must include the required parameters listed in REF _Ref363507739 \r \h Appendix A; including the optional parameters is highly recommended. Each parameter must be exposed as a Parameter ( REF _Ref302122254 \r \h 3.5).
Parameters listed in REF _Ref281911758 \r \h A.2, REF _Ref284581851 \r \h A.3, and REF _Ref284598798 \r \h A.4 must be exposed as read-only parameters.
Read-only parameters must specify its current value by populating the default value field with the value. Additionally, read-only parameters must not provide any allowed values. Allowed values are reserved to specify acceptable information which may be passed to the service for configuration.
Example SEQ Example \* MERGEFORMAT 19: An example snippet from a get service info call demonstrating a read-only parameter. Enclosing tags (which may vary) are omitted.
inactivityTimeout
xs:nonNegativeInteger
true
false
600
Configurable parameters, or those which are not read only, must provide information for the default value as well as allowed values. To specify that an allowed value is within range of numbers, refer to Range ( REF _Ref302123382 \r \h 3.6).
Example SEQ Example \* MERGEFORMAT 20: An example snippet from a get service info call. The target service supports a configurable parameter called ImageWidth. Enclosing tags (which may vary) are omitted.
imageWidth
xs:positiveInteger
false
false
800
640
800
1024
In many cases, an exposed parameter will support multiple values (see REF _Ref301439007 \r \h 3.5.2.1). When a parameter allows this capability, it must use a type-specific array, if defined in this specification, or the generic Array ( REF _Ref310844662 \r \h 3.7) type. The type element within a parameter must be the qualified name of a single values type (see REF _Ref301439007 \r \h 3.5.2.1 for an example).
Configuration
A configuration consists of parameters specific to the sensor or post-processing related to the final capture result. This must only consist of key/value pairs. It must not include other information about the parameters, such as allowed values or read-only status.
Restrictions for each configuration parameter can be discovered through the get service info operation.
Example SEQ Example \* MERGEFORMAT 21: The following is an example payload to set configuration consisting of three parameters.
-
imageHeight
480
-
imageWidth
640
-
frameRate
20
Captured Data
Overview
Metadata related to a particular capture operation must include the configuration of the sensor at the time of capture. Static parameters related to the service should not be included in the metadata for a capture result.
A service may perform post-processing steps on any captured information. This information should be added to the particular capture results metadata.
Example SEQ Example \* MERGEFORMAT 22: Example metadata for a particular capture. Note that this includes parameters related to the sensor. Enclosing tags (which may vary) are omitted.
-
serialNumber
98A8N830LP332-V244
-
imageHeight
600
-
imageWidth
800
-
captureTime
2011-12-02T09:39:10.935-05:00
-
contentType
image/jpeg
-
modality
Finger
-
submodality
LeftIndex
Example SEQ Example \* MERGEFORMAT 23: A service computes the quality score of a captured fingerprint (see previous example). This score is added to the results metadata to allow other clients to take advantage of previously completed processes. Enclosing tags (which may vary) are omitted.
-
quality
78
-
serialNumber
98A8N830LP332-V244
-
captureDate
2011-01-01T15:30:00Z
-
modality
Finger
-
submodality
leftIndex
-
imageHeight
600
-
imageWidth
800
-
contentType
image/bmp
Minimal Metadata
General
At a minimum, a sensor or service must maintain the following ( REF _Ref401903965 \w \h 4.4.2.2 REF _Ref401903966 \w \h 4.4.2.5) metadata fields for each captured result.
Capture Date
Formal NamecaptureDateData Typexs:dateTime [ REF XMSCHEMA2 \h XMSCHEMA-2]This value represents the date and time at which the capture occurred.
Modality
Formal NamemodalityData Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]The value of this field must be present in the list of available modalities exposed by the get service info operation ( REF _Ref302380203 \r \h 6.9) as defined in REF _Ref309808861 \r \h A.5.1. This value represents the modality of the captured result.
Submodality
Formal NamesubmodalityData Typexs:anyType [ REF XMSCHEMA2 \h XMSCHEMA-2]The value of this field must be present in the list of available submodalities exposed by the get service info operation ( REF _Ref302380203 \r \h 6.9) as defined in REF _Ref309806257 \r \h A.5.2. This value represents the submodality of the captured result. If this parameter supports multiple, then the data type must be a StringArray ( REF _Ref310519522 \r \h \* MERGEFORMAT 3.8) of values. If submodality does not support multiple, the data type must be xs:string [XMSCHEMA-2].
Content Type
Formal NamecontentType [ REF RFC2045 \h RFC2045, REF RFC2046 \h RFC2046]Data Typexs:stringThe value of this field represents the content type of the captured data. See REF _Ref363507814 \r \h Appendix B for which content types are supported.
Live Preview
About
If a service implements live preview, than the service MUST implement it as described in this section ( REF _Ref371506648 \r \h 5). Live preview is be used to provide feedback to the client to, when applicable, signal capture and/or what is occurring during a capture.
Endpoints
Exposing endpoint information to a client is done through the service information. If live preview is implemented, the service information MUST contain key/value where the key is livePreview and the value is of type Parameter ( REF _Ref364420061 \r \h 3.5). This must be a read-only parameter. The default value MUST be of type ResourceArray ( REF _Ref401922350 \r \h 3.10). An implementation may expose one or more Resources ( REF _Ref401922361 \r \h 3.11) in the ResourceArray. For the stream parameter, each instance of a Resource MUST contain the uri, contentType, and the relationship elements.
The content type of the stream and the value of each Resources contentType element should be listed as it appears in REF _Ref363507814 \r \h Appendix B.
The value of the relationship field must begin with livePreview and there must be at least one entry where the elements value consists of only livePreview. An implementer may provide additional endpoints with a modified relationship. This may be done by appending a forward slash immediately after livePreview and before any additional content; any additional content must not occur before the forward slash. The relationship field must only contain base-64 characters.
Example SEQ Example \* MERGEFORMAT 24: The follow snippet is a skeleton service information entry for a stream parameter. Enclosing tags have been omitted.
-
livePreview
livePreview
Resource
true
...
...
Example SEQ Example \* MERGEFORMAT 25: The following snippet is an example service information entry that exposes a Parameter ( REF _Ref364420061 \r \h 3.5) for live preview resources. This example exposes two different endpoints, each offering a live preview with different content types. Enclosing tags (which may vary) are omitted.
-
livePreview
livePreview
Resource
true
http://192.168.1.1/stream
video/h264
livePreview
http://192.168.1.1:81/stream
video/mpeg
livePreview
Example SEQ Example \* MERGEFORMAT 26: The following snippet is an example service information entry that exposes a Parameter ( REF _Ref364420061 \r \h 3.5) for live preview resources. This example exposes two different endpoints, one with a modified relationship value. For example, the second entry may be describing an endpoint that has live preview of a face at 30 frames per second. Enclosing tags (which may vary) are omitted.
-
livePreview
livePreview
Resource
true
http://192.168.1.1/stream
video/h264
livePreview
http://192.168.1.1:81/stream
video/mpeg
livePreview/face+fps=30
To begin receiving live preview data, the client SHALL establish a connection to the desired live preview endpoint/URI. Closing the connection to an endpoint/URI SHALL terminate the transmission of all live preview data to establishing client. A client SHALL signal a capture using the capture operation ( REF _Ref402349343 \r \h 6.13).
Heartbeat
In many cases, live preview may not be ready to provide actual images until a certain point in a session or the lifetime of a service (e.g., after initialization). The service has two options on how to proceed when streaming is called before it is ready.
Immediately close the live preview connection. This is only recommended if live preview is not available for the service. It MUST NOT be expected that a client will make additional calls to the live preview endpoint after a closed connection.
Send a heartbeat to the client upon a live preview request. The heartbeat MUST consist of minimal null information and MUST be sent to all clients on a fixed time interval.
Example SEQ Example \* MERGEFORMAT 27: The following is an example heartbeat frame sent over a multipart/x-mixed-replace stream. For this example, the boundary indicator is boundaryString. A service may send this null frame as a heartbeat to all connected clients every, for example, 10 seconds to alert the client that live preview data is available, but not at the current state of the service, sensor, or session.
--boundaryString
Content-Type: multipart/x-heartbeat
0
Operations
About
This section, REF _Ref401904664 \w \h 6, provides detailed information regarding each WS-BD operation.
General Usage
Overview
The following usage requirements apply to all operations, unless the detailed documentation for a particular operation conflicts with these general requirements, in which case the detailed documentation takes precedence.
Failure messages are informative. If an operation fails, then the message element may contain an informative message regarding the nature of that failure. The message is for informational purposes onlythe functionality of a client must not depend on the contents of the message.
Results must only contain required and optional elements. Services must only return elements that are either required or optional. All other elements must not be contained in the result, even if they are empty elements. Likewise, to maintain robustness in the face of a non-conformant service, clients should ignore any element that is not in the list of permitted Result elements for a particular operation call.
Sensor operations must not occur within a non-sensor operation. Services should only perform any sensor control within the operations:
initialize,
get configuration,
set configuration,
capture, and
cancel.
Sensor operations must require locking. Even if a service implements a sensor operation without controlling the target biometric sensor, the service must require that a locked service for the operation to be performed.
Content Type. Clients must make HTTP requests using a content type of application/xml [ REF RFCHTTP \h RFC-HTTP].
Namespace. A data type without an explicit namespace or namespace prefix implies it is a member of the wsbd namespace as defined in REF _Ref310251511 \r \h 3.2.
Precedence of Status Enumerations
To maximize the amount of information given to a client when an error is obtained, and to prevent different implementations from exhibiting different behaviors, all WS-BD services must return status values according to a fixed priority. In other words, when multiple status messages might apply, a higher-priority status must always be returned in favor of a lower-priority status.
The status priority, listed from highest priority (invalidId) to lowest priority (success) is as follows:
invalidId
noSuchParameter
badValue
unsupported
canceledWithSensorFailure
canceled
lockHeldByAnother
lockNotHeld
sensorBusy
sensorFailure
sensorTimeout
initializationNeeded
configurationNeeded
preparingDownload
failure
success
Notice that success is the lowest priorityan operation must only be deemed successful if no other kinds of (non-successful) statuses apply.
The following example illustrates how this ordering affects the status returned in a situation in which multiple clients are performing operations.
EXAMPLE SEQ Example \* MERGEFORMAT 28: REF _Ref280268402 \h \* MERGEFORMAT Figure 6 illustrates that client cannot receive a sensorBusy status if it does not hold the lock, even if a sensor operation is in progress (recall from REF _Ref280082456 \r \h 2.5.6 that sensor operations require holding the lock). Suppose there are two clients; Client A and Client B. Client A holds the lock and starts initialization on (Step 13). Immediately after Client A initiates capture, Client B (Step 4) tries to obtain the lock while Client A is still capturing. In this situation, the valid statuses that could be returned to Client B are sensorBusy (since the sensor is busy performing a capture and can only perform one capture at time) and lockHeldByAnother (since Client A holds the lock). In this case, the service returns lockHeldByAnother (Step 5) since lockHeldByAnother is higher priority than sensorBusy.
Figure SEQ Figure \* ARABIC 6. Example illustrating why a client cannot receive a "sensorBusy" status if it does not hold the lock.
Parameter Failures
Services must distinguish among badValue, invalidId, noSuchParameter, and unsupported according to the following rules. These rules are presented here in the order of precedence that matches the previous subsection.
Is a recognizable UUID provided? If the operation requires a UUID as an input URL parameter, and provided value is not an UUID (i.e., the UUID is not parseable), then the service must return badValue. Additionally, the Results badFields list must contain the name of the offending parameter (sessionId or captureId).
otherwise
Is the UUID understood? If an operation requires an UUID as an input URL parameter, and the provided value is a UUID, but service cannot accept the provided value, then the service must return invalidId. Additionally, the Results badFields list must contain the name of the offending parameter (sessionId or captureId).
otherwise
Are the parameter names understood? If an operation does not recognize a provided input parameter name, then the service must return noSuchParameter. This behavior may differ from service to service, as different services may recognize (or not recognize) different parameters. The unrecognized parameter(s) must be listed in the Results badFields list. otherwise
Are the parameter values acceptable? If an operation recognizes all of the provided parameter names, but cannot accept a provided value because it is (a) and inappropriate type, or (b) outside the range advertised by the service ( REF _Ref301256253 \r \h 4.2), the then service must return badValue. The parameter names associated with the unacceptable values must be listed in the Results badFields list. Clients are expected to recover the bad values themselves by reconciling the Result corresponding to the offending request.otherwise
Is the request supported? If an operation accepts the parameter names and values, but the particular request is not supported by the service or the target biometric sensor, then the service must return unsupported. The parameter names that triggered this determination must be listed in the Results badFields list. By returning multiple fields, a service is able to imply that a particular combination of provided values is unsupported.
NOTE: It may be helpful to think of invalidId as a special case of badValue reserved for URL parameters of type UUID.
Visual Summaries (Informative)
Overview
The two tables in this subsection provide informative visual summaries of WS-BD operations. These visual summaries are an overview; they are not authoritative. ( REF _Ref281904658 \r \h 6.4 REF _Ref281902545 \r \h 6.17 are authoritative.)
Input & Output (Informative)
REF _Ref401924505 \h Table 7 represents a visual summary of the inputs and outputs corresponding to each operation.
Operation inputs are indicated in the URL Fragment and Input Payload columns. Operation inputs take the form of either (a) a URL parameter, with the parameter name shown in curly brackets ({ and }) within the URL fragment (first column), and/or, (b) a input payload (defined in REF _Ref363508022 \r \h 1.2).
Operation outputs are provided via Result, which is contained in the body of an operations HTTP response.
Table SEQ Table \* ARABIC 7. Summary of Operations Input/Output (informative)
OperationURL Fragment
(Includes inputs)MethodInput
payloadIdempotentSensor OperationPermitted Result Elements (within output payload)Detailed Documentation statusbadFieldssessionIdmetadatacaptureIdssensorDataregister/registerPOSTnone l l R E F _ R e f 2 8 1 3 0 6 2 1 9 \ r \ h \ * M E R G E F O R M A T 6 . 4 u n r e g i s t e r / r e g i s t e r / { s e s s i o n I d } D E L E T E n o n e u l l R E F _ R e f 2 8 1 3 0 6 2 6 5 \ r \ h \ * M E R G E F O R M A T 6 . 5 t r y l o c k / l o c k / { s e s s i o n I d } P O S T n o n e u l l R E F _ R e f 2 8 4 8 4 6 4 6 6 \ r \ h \ * M E R G E F O R M A T 6 . 6 s t e a l l o c k P U T n o n e u l l R E F _ R e f 2 8 4 8 4 6 4 7 2 \ r \ h \ * M E R G E F O R M A T 6 . 7 u n l o c k D E L E T E n o n e u l l R E F _ R e f 2 8 1 3 0 6 9 0 2 \ r \ h \ * M E R G E F O R M A T 6 . 8 g e t s e r v i c e i n f o / i n f o G E T n o n e u l l R E F _ R e f 3 0 2 3 8 0 2 0 3 \ r \ h \ * M E R G E F O R M A T 6 . 9 i n i t i a l i z e / i n i t i a l i z e / { s e s s i o n I d } P O S T n o n e u n l l R E F _ R e f 2 8 1 3 0 6 2 8 0 \ r \ h \ * M E R G E F O R M A T 6 . 1 0 g e t c o n f i g u r a t i o n / c o n f i g u r e / { s e s s i o n I d } G E T n o n e u n l l l R E F _ R e f 2 8 1 3 0 6 2 8 4 \ r \ h \ * M E R G E F O R M A T 6 . 1 1 s e t c o n f i g u r a t i o n P O S T c o n f i g u n l l R E F _ R e f 2 8 1 3 0 6 2 8 8 \ r \ h \ * M E R G E F O R M A T 6 . 1 2 c a p t u r e / c a p t u r e / { s e s s i o n I d } P O S T n o n e n l l l R E F _ R e f 2 8 1 9 0 2 5 2 1 \ r \ h \ * M E R G E F O R M A T 6 . 1 3 d o w n l o a d / d o w n l o a d / { c a p t u r e i d } G E T n o n e u l l l l R E F _ R e f 2 8 1 9 0 2 5 4 1 \ r \ h \ * M E R G E F O R M A T 6 . 1 4 g e t d o w n l o a d i n f o / d o w n l o a d / { c a p t u r e i d } / i n f o G E T n o n e u l R E F _ R e f 2 8 6 3 0 6 7 1 6 \ r \ h \ * M E R G E F O R M A T 6 . 1 5 t h r i f t y d o w n l o a d / d o w n l o a d / { c a p t u r e i d } / { m a x S i z e } G E T n o n e u l l l l R E F _ R e f 2 8 1 9 0 2 5 4 4 \ r \ h \ * M E R G E F O R M A T 6 . 1 6 c a n c e l o p e r a t i o n / c a n c e l / { s e s s i o n I d } P O S T n o n e u n l l R E F _ R e f 2 8 1 9 0 2 5 4 5 \ r \ h \ * M E R G E F O R M A T 6 . 1 7 P r e s e n c e o f a s y m b o l i n a t a b l e c e l l i n d i c a t e s t h a t o p e r a t i o n i s i d e m p o t e n t ( u) , a s e n s o r o p e r a t i o n ( n) , a n d w h i c h e l e m e n t s m a y b e p r e s e n t i n t h e o p e r a t i o n ' s R e s u l t ( l) . L i k e w i s e , t h e l a c k o f a s y m b o l i n a t a b l e c e l l i n d i c a t e s t h e o p e r a t i o n i s n o t i d e m p o t e n t , n o t a s e n s o r o p e r a t i o n , a n d w h i c h e l e m e n t s o f t h e o p e r a t i o n ' s R e s u l t a r e f o r b i d d e n .
E x a m p l e S E Q E x a m p l e \ * M E R G E F O R M A T 2 9 : T h e c a p t u r e o p e r a tion (fifth row from the bottom) is not idempotent, but is a sensor operation. The output may contain the elements status, badFields, and/or captureIds in its Result. The detailed information regarding the Result for capture, (i.e., which elements are specifically permitted under what circumstances) is found in REF _Ref281902521 \r \h \* MERGEFORMAT 6.13.
The message element is not shown in this table for two reasons. First, when it appears, it is always optional. Second, to emphasize that the message content must only be used for informative purposes; it must not be used as a vehicle for providing unique information that would inhibit a services interoperability.
Permitted Status Values (Informative)
REF _Ref401924549 \h Table 8 provides a visual summary of the status values permitted.
Table SEQ Table \* ARABIC 8. Possible Status Values Per Operation (informative)
Status
Values
Operation DescriptionsuccessfailureinvalidIdcanceledcanceledWithSensorFailuresensorFailurelockNotHeld l o c k H e l d B y A n o t h e r i n i t i a l i z a t i o n N e e d e d c o n f i g u r a t i o n N e e d e d s e n s o r B u s y s e n s o r T i m e o u t u n s u p p o r t e d b a d V a l u e n o S u c h P a r a m e t e r p r e p a r i n g D o w n l o a d r e g i s t e r l l u n r e g i s t e r l l l l l t r y l o c k l l l l l s t e a l l o c k l l l l u n l o c k l l l l l g e t s e r v i c e i n f o l l i n i t i a l i z e l l l l l l l l l l l g e t c o n f i g u r a t i o n l l l l l l l l l l l l l s e t c o n f i g u r a t i o n l l l l l l l l l l l l l l c a p t u r e l l l l l l l l l l l l l d o w n l o a d l l l l l g e t d o w n l o a d i n f o l l l l l t h r i f t y d o w n l o a d l l l l l l c a n c e l l l l l l l T h e p r e s e n c e ( a b s e n c e ) o f a s y m b o l i n a c e l l i n d i c a t e s t h a t t h e r e s p e c t i v e s t a t u s m a y ( m a y n o t ) b e r e t u r n e d b y t h e c o r r e s p o nding operation.
Example SEQ Example \* MERGEFORMAT 30: The register operation may only return a Result with a Status that contains either success or failure. The unregister operation may only return success, failure, invalidId, sensorBusy, or badValue.
The visual summary does not imply that services may return these values arbitrarilythe services must adhere to the behaviors as specified in their respective sections.
Documentation Conventions
About
Each WS-BD operation is documented according to the conventions described in this subsection ( REF _Ref401904046 \w \h 6.3).
General Information
Each operation begins with the following tabular summary:
DescriptionA short description of the operationURL TemplateThe suffix used to access the operation. These take the form
/resourceName
or
/resourceName/{URL_parameter_1}//{URL_parameter_N}
Each parameter, {URL_parameter...} must be replaced, in-line with that parameters value.
Parameters have no explicit names, other than defined by this document or reported back to the client within the contents of a badFields element.
It is assumed that consumers of the service will prepend the URL to the service endpoint as appropriate.
EXAMPLE SEQ Example \* MERGEFORMAT 31: The resource resourceName hosted at the endpoint
HYPERLINK "http://example.com/Service" http://example.com/Service
would be accessible via
HYPERLINK "http://example.com/Service" http://example.com/Service/resourceName
HTTP Method The HTTP method that triggers the operation, i.e., GET, POST, PUT, or DELETEURL ParametersA description of the URL-embedded operation parameters. For each parameter the following details are provided:
the name of the parameter
the expected data type ( REF _Ref363508183 \r \h \* MERGEFORMAT 3)
a description of the parameterInput PayloadA description of the content, if any, to be posted to the service as input to an operation.IdempotentYesthe operation is idempotent ( REF _Ref281307737 \r \h \* MERGEFORMAT 2.5.8).
Nothe operation is not idempotent.Sensor Operation (Lock Required)
Yesthe service may require exclusive control over the target biometric sensor.
Nothis operation does not require a lock.
Given the concurrency model ( REF _Ref280082456 \r \h \* MERGEFORMAT 2.5.6) this value doubles as documentation as to whether or not a lock is required.Result Summary
This subsection summarizes the various forms of a Result that may be returned by the operation. Each row represents a distinct combination of permitted values & elements associated with a particular status. An operation that returns success may also provide additional information other than status.
success status="success"failurestatus="failure"
message*=informative message describing failure [status value]status=status literal
[required element name]=description of permitted contents of the element
[optional element name]*=description of permitted contents of the elementFor each row, the left column contains a permitted status value, and the right column contains a summary of the constraints on the Result when the status element takes that specific value. The vertical ellipses at the bottom of the table signify that the summary table may have additional rows that summarize other permitted status values.
Data types without an explicit namespace or namespace prefix are members of the wsbd namespace as defined in REF _Ref310251511 \r \h 3.2.
Element names suffixed with a * indicate that the element is optional.
Usage
Each of the parts in this subsection describe the behaviors & requirements that are specific to its respective operation.
Unique Knowledge
For each operation, there is a brief description of whether or not the operation affords an opportunity for the server or client to exchange information unique to a particular implementation. The term unique knowledge is used to reflect the definition of interoperability referenced in REF _Ref363508285 \r \h 2.2.
Return Values Detail
This subsection details the various return values that the operation may return. For each permitted status value, the following table details the Result requirements:
Status ValueThe particular status valueConditionThe service accepts the registration requestRequired ElementsA list of the required elements. For each required element, the element name, its expected contents, and expected data type is listed If no namespace prefix is specified, then the wsbd namespace ( REF _Ref310251511 \r \h \* MERGEFORMAT 3.2) is inferred.
For example, badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
Indicates that badFields is a required element, and that the contents of the element must be a wsbd:StringArray containing the single literal "sessionId".Optional ElementsA list of the required elements. Listed for each optional element are the element names and its expected contents.Constraints and information unique to the particular operation/status combination may follow the table, but some status values have no trailing explanatory text.
A data type without an explicit namespace or namespace prefix implies it is a member of the wsbd namespace as defined in REF _Ref310251511 \r \h 3.2.
Register
Overview
DescriptionOpen a new client-server sessionURL Template/registerHTTP Method POSTURL ParametersNoneInput PayloadNoneIdempotentNoSensor OperationNoResult Summary
successstatus = "success"
sessionId = session id (UUID, REF _Ref280079094 \r \h \* MERGEFORMAT 3.3)failurestatus = "failure"
message* = informative message describing failure Usage
Register provides a unique identifier that can be used to associate a particular client with a server.
In a sequence of operations with a service, a register operation is likely one of the first operations performed by a client (get service info being the other). It is expected (but not required) that a client would perform a single registration during that clients lifetime.
Design Note SEQ DesignNote \* MERGEFORMAT 4 (Informative): By using an UUID, as opposed to the source IP address, a server can distinguish among clients sharing the same originating IP address (i.e., multiple clients on a single machine, or multiple machines behind a firewall). Additionally, a UUID allows a client (or collection of clients) to determine client identity rather than enforcing a particular model ( REF _Ref283989051 \r \h 2.5.4).
Unique Knowledge
As specified, the register operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The register operation must return a Result according to the constraints described in this subsection ( REF _Ref401904740 \w \h 6.4.5).
Success
Status ValuesuccessConditionThe service accepts the registration requestRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"
sessionId (UUID, REF _Ref280079094 \r \h \* MERGEFORMAT 3.3)
an identifier that can be used to identify a sessionOptional ElementsNoneThe register operation must not provide a sessionId of 00000000-0000-0000-0000-000000000000.
Failure
Status ValuefailureConditionThe service cannot accept the registration requestRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureRegistration might fail if there are too many sessions already registered with a service. The message element must only be used for informational purposes. Clients must not depend on particular contents of the message element to control client behavior.
See REF _Ref363508352 \r \h 4 and REF _Ref281911758 \r \h \* MERGEFORMAT A.2 for how a client can use sensor metadata to determine the maximum number of current sessions a service can support.
Unregister
Overview
DescriptionClose a client-server sessionURL Template/register/{sessionId}HTTP Method DELETEURL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session to removeInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failuresensorBusystatus = "sensorBusy"badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
General
Unregister closes a client-server session. Although not strictly necessary, clients should unregister from a service when it is no longer needed. Given the lightweight nature of sessions, services should support (on the order of) thousands of concurrent sessions, but this cannot be guaranteed, particularly if the service is running within limited computational resources. Conversely, clients should assume that the number of concurrent sessions that a service can support is limited. (See REF _Ref281911758 \r \h \* MERGEFORMAT A.2 for details on connection metadata.)
Inactivity
A service may automatically unregister a client after a period of inactivity, or if demand on the service requires that least-recently used sessions be dropped. This is manifested by a client receiving a status of invalidId without a corresponding unregistration. Services should set the inactivity timeout to a value specified in minutes. (See REF _Ref281911758 \r \h \* MERGEFORMAT A.2 for details on connection metadata.)
Sharing Session Ids
A session id is not a secret, but clients that share session ids run the risk of having their session prematurely terminated by a rogue peer client. This behavior is permitted, but discouraged. See REF _Ref286223458 \r \h \* MERGEFORMAT 2.5 for more information about client identity and the assumed security models.
Locks & Pending Sensor Operations
If a client that holds the service lock unregisters, then a service must also release the service lock, with one exception. If the unregistering client both holds the lock and is responsible for a pending sensor operation, the service must return sensorBusy (See REF _Ref286146281 \r \h \* MERGEFORMAT 6.5.5.4).
Unique Knowledge
As specified, the unregister operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The unregister operation must return a Result according to the constraints described in this subsection ( REF _Ref401904851 \w \h 6.5.5).
Success
Status ValuesuccessConditionThe service accepted the unregistration requestRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneIf the unregistering client currently holds the service lock, and the requesting client is not responsible for any pending sensor operation, then successful unregistration must also release the service lock.
As a consequence of idempotency, a session id does not need to ever have been registered successfully in order to unregister successfully. Consequently, the unregister operation cannot return a status of invalidId.
Failure
Status ValuefailureConditionThe service could not unregister the session.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureIn practice, failure to unregister is expected to be a rare occurrence. Failure to unregister might occur if the service experiences a fault with an external system (such as a centralized database used to track session registration and unregistration)
Sensor Busy
Status ValuesensorBusyConditionThe service could not unregister the session because the biometric sensor is currently performing a sensor operation within the session being unregistered.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorBusy"Optional ElementsNoneThis status must only be returned if (a) the sensor is busy and (b) the client making the request holds the lock (i.e., the session id provided matches that associated with the current service lock). Any client that does not hold the session lock must not result in a sensorBusy status.
Example SEQ Example \* MERGEFORMAT 32: The following sequence diagram illustrates a client that cannot unregister (Client A) and a client that can unregister (Client B). After the initialize operation completes (Step 6), Client A can unregister (Steps 7-8).
Figure SEQ Figure \* ARABIC 7. Example of how an unregister operation can result in sensorBusy.
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Try Lock
Overview
DescriptionTry to obtain the service lockURL Template/lock/{sessionId}HTTP Method POSTURL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting the service lockInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)lockHeldByAnotherstatus = "lockHeldByAnother"badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
The try lock operation attempts to obtain the service lock. The word try is used to indicate that the call always returns immediately; it does not block until the lock is obtained. See REF _Ref280082456 \n \h \* MERGEFORMAT 2.5.6 for detailed information about the WS-BD concurrency and locking model.
Unique Knowledge
As specified, the try lock cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The try lock operation must return a Result according to the constraints described in this subsection ( REF _Ref401904896 \w \h 6.6.5)
Success
Status ValuesuccessConditionThe service was successfully locked to the provided session id.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneClients that hold the service lock are permitted to perform sensor operations ( REF _Ref280082456 \n \h \* MERGEFORMAT 2.5.6). By idempotency ( REF _Ref281307737 \r \h \* MERGEFORMAT 2.5.8), if a client already holds the lock, subsequent try lock operations MUST also return success.
Failure
Status ValuefailureConditionThe service could not be locked to the provided session id.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must reserve a failure status to report system or internal failures and prevent the acquisition of the lock. Most try lock operations that do not succeed will not produce a failure status, but more likely a lockHeldByAnother status (See REF _Ref280099937 \n \h \* MERGEFORMAT 6.6.5.5 for an example).
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Lock Held by Another
Status ValuelockHeldByAnotherConditionThe service could not be locked to the provided session id because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockHeldByAnother"Optional ElementsNoneExample SEQ Example \* MERGEFORMAT 33: The following sequence diagram illustrates a client that cannot obtain the lock (Client B) because it is held by another client (Client A).
Figure SEQ Figure \* ARABIC 8. Example of a scenario yielding a lockHeldByAnother result.
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Steal Lock
Overview
DescriptionForcibly obtain the lock away from a peer clientURL Template/lock/{sessionId}HTTP Method PUTURL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting the service lockInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
General
The steal lock operation allows a client to forcibly obtain the lock away from another client that already holds the lock. The purpose of this operation is to prevent a client that experiences a fatal error from forever preventing another client access to the service, and therefore, the biometric sensor.
Avoid Lock Stealing
Developers and integrators should endeavor to reserve lock stealing for exceptional circumstancessuch as when a fatal error prevents a client from releasing a lock. Lock stealing should not be used as the primary mechanism in which peer clients coordinate biometric sensor use.
Lock Stealing Prevention Period (LSPP)
To assist in coordinating access among clients and to prevent excessive lock stealing, a service may trigger a time period that forbids lock stealing for each sensor operation. For convenience, this period of time will be referred to as the lock stealing prevention period (LSPP).
During the LSPP, all attempts to steal the service lock will fail. Consequently, if a client experiences a fatal failure during a sensor operation, then all peer clients need to wait until the service re-enables lock stealing.
All services should implement a non-zero LSPP. The recommended time for the LSPP is on the order of 100 seconds. Services that enforce an LSPP must start the LSPP immediately before sovereign sensor control is required. Conversely, services should not enforce an LSPP unless absolutely necessary.
If a request provides an invalid sessionId, then the operation should return an invalidId status instead of a failurethis must be true regardless of the LSPP threshold and whether or not it has expired. A failure signifies that the state of the service is still within the LSPP threshold and the provided sessionId is valid.
A service may reinitiate a LSPP when an operation yields an undesirable result, such as failure. This would allow a client to attempt to resubmit the request or recover without worrying about whether or not the lock is still owned by the clients session.
An LSPP ends after a fixed amount of time has elapsed, unless another sensor operation restarts the LSPP. Services should keep the length of the LSPP fixed throughout the services lifecycle. It is recognized, however, that there may be use cases in which a variable LSPP timespan is desirable or required. Regardless, when determining the appropriate timespan, implementers should carefully consider the tradeoffs between preventing excessive lock stealing, versus forcing all clients to wait until a service re-enables lock stealing.
Cancellation & (Lack of) Client Notification
Lock stealing must not affect any currently running sensor operations. That is, it must be possible that a client initiates a sensor operation, has its lock stolen away, and have the operation completes successfully anyway. Subsequent sensor operations would yield a lockNotHeld status, which a client could use to indicate that their lock was stolen away from them.
Services should be implemented such that the LSPP is longer than any sensor operation.
Unique Knowledge
As specified, the steal lock operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The steal lock operation must return a Result according to the constraints described in this subsection ( REF _Ref401904959 \w \h 6.7.5).
Success
Status ValueSuccessConditionThe service was successfully locked to the provided session id.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneSee REF _Ref280082456 \n \h \* MERGEFORMAT 2.5.6 for detailed information about the WS-BD concurrency and locking model. Cancellation must have no effect on pending sensor operations ( REF _Ref286227699 \r \h 6.7.3.4).
Failure
Status ValuefailureConditionThe service could not be locked to the provided session id.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureMost steal lock operations that yield a failure status will do so because the service receives a lock stealing request during a lock stealing prevention period ( REF _Ref280266744 \n \h \* MERGEFORMAT 6.7.3.3). Services must also reserve a failure status for other non-LSPP failures that prevent the acquisition of the lock.
Implementers may choose to use the optional message field to provide more information to an end-user as to the specific reasons for the failure. However (as with all other failure status results), clients must not depend on any particular content to make this distinction.
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Unlock
Overview
DescriptionRelease the service lockURL Template/lock/{sessionId}HTTP Method DELETEURL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session releasing the service lockInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
The unlock operation releases a service lock, making locking available to other clients.
See REF _Ref280082456 \n \h \* MERGEFORMAT 2.5.6 for detailed information about the WS-BD concurrency and locking model.
Unique Knowledge
As specified, the unlock operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The steal lock operation must return a Result according to the constraints described in this subsection ( REF _Ref401904974 \w \h 6.8.5).
Success
Status ValuesuccessConditionThe service returned to an unlocked state.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneUpon releasing the lock, a client is no longer permitted to perform any sensor operations ( REF _Ref280082456 \n \h \* MERGEFORMAT 2.5.6). By idempotency ( REF _Ref281307737 \r \h \* MERGEFORMAT 2.5.8), if a client already has released the lock, subsequent unlock operations should also return success.
Failure
Status ValuefailureConditionThe service could not be transitioned into an unlocked state.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must reserve a failure status to report system or internal failures and prevent the release of the service lock. The occurrence of unlock operations that fail is expected to be rare.
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Get Service Info
Overview
DescriptionRetrieve metadata about the service that does not depend on session-specific information, or sovereign control of the target biometric sensorURL Template/infoHTTP Method GET URL ParametersNoneInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"
metadata = dictionary containing service metadata (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)failurestatus = "failure"
message* = informative message describing failureUsage
The get service info operation provides information about the service and target biometric sensor. This operation must return information that is both (a) independent of session, and (b) does not require sovereign biometric sensor control. In other words, services must not control the target biometric sensor during a get service info operation itself. Implementations may (and are encouraged to) use service startup time to query the biometric sensor directly to create a cache of information and capabilities for get service info operations. The service should keep a cache of sensor and service metadata to reduce the amount of operations that query the sensor as this can be a lengthy operation.
The get service info operation does not require that a client be registered with the service. Unlike other operations, it does not take a session id as a URL parameter.
See REF _Ref301256253 \r \h \* MERGEFORMAT 4.2 for information about the metadata returned from this operation.
Example SEQ Example \* MERGEFORMAT 34: The following represents a raw request to get the services metadata.
GET http://10.0.0.8:8000/Service/info HTTP/1.1
Content-Type: application/xml
Host: 10.0.0.8:8000
Example SEQ Example \* MERGEFORMAT 35: The following is the raw response from the above request. The metadata element of the result contains a Dictionary ( REF _Ref281914219 \r \h 3.4) of parameter names and parameter information represented as a Parameter ( REF _Ref311032062 \r \h 3.5).
HTTP/1.1 200 OK
Content-Length: 4244
Content-Type: application/xml; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 03 Jan 2012 14:54:51 GMT
success
-
width
width
a:unsignedInt
800
1280
960
800
640
424
416
352
320
-
height
height
a:unsignedInt
600
720
600
544
480
448
360
288
240
144
120
-
frameRate
frameRate
a:unsignedInt
30
30
15
10
-
modality
modality
a:string
true
face
-
submodality
submodality
a:string
true
frontalFace
Unique Knowledge
As specified, the get service info can be used to obtain knowledge about unique characteristics of a service. Through get service info, a service may expose implementation and/or service-specific configuration parameter names and values that are not defined in this specification (see REF _Ref363508407 \r \h Appendix A for further information on parameters).
Return Values Detail
Overview
The get service info operation must return a Result according to constraints described in this subsection ( REF _Ref401905028 \w \h 6.9.5).
Success
Status ValuesuccessConditionThe service provides service metadataRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"
metadata (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)
information about the service metadataOptional ElementsNoneFailure
Status ValuefailureConditionThe service cannot provide service metadataRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failure
Initialize
Overview
DescriptionInitialize the target biometric sensorURL Template/initialize/{sessionId}HTTP Method POST URL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting initializationInput PayloadNoneIdempotentYesSensor OperationYesResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)canceledstatus = "canceled"canceledWithSensorFailurestatus = "canceledWithSensorFailure"sensorFailurestatus = "sensorFailure"lockNotHeldstatus = "lockNotHeld"lockHeldByAnotherstatus = "lockHeldByAnother"sensorBusystatus = "sensorBusy"sensorTimeoutstatus = "sensorTimeout"badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
The initialize operation prepares the target biometric sensor for (other) sensor operations.
Some biometric sensors have no requirement for explicit initialization. In that case, the service should immediately return a success result.
Although not strictly necessary, services should directly map this operation to the initialization of the target biometric sensor, unless the service can reliably determine that the target biometric sensor is in a fully operational state. In other words, a service may decide to immediately return success if there is a reliable way to detect if the target biometric sensor is currently in an initialized state. This style of short circuit evaluation could reduce initialization times. However, a service that always initializes the target biometric sensor would enable the ability of a client to attempt a manual reset of a sensor that has entered a faulty state. This is particularly useful in physically separated service implementations where the connection between the target biometric sensor and the web service host may be less reliable than an integrated implementation.
Unique Knowledge
As specified, the initialize operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The initialize operation must return a Result according to constraints described in this subsection ( REF _Ref401905056 \w \h 6.10.5).
Success
Status ValuesuccessConditionThe service successfully initialized the target biometric sensorRequired Elementsstatusmust be populated with the Status literal "success"Optional ElementsNoneFailure
Status ValuefailureConditionThe service experienced a fault that prevented successful initialization.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureA failure status must only be used to report failures that occurred within the web service, not within the target biometric sensor ( REF _Ref280706912 \r \h \* MERGEFORMAT 6.10.5.6, REF _Ref280706913 \r \h \* MERGEFORMAT 6.10.5.7)
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Canceled
Status ValuecanceledConditionThe initialization operation was interrupted by a cancellation request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceled"Optional ElementsNoneSee REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Canceled with Sensor Failure
Status ValuecanceledWithSensorFailureConditionThe initialization operation was interrupted by a cancellation request and the target biometric sensor experienced a failureRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceledWithSensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must return a canceledWithSensorFailure result if a cancellation request caused a failure within the target biometric sensor. Clients receiving this result may need to reattempt the initialization request to restore full functionality. See REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Sensor Failure
Status ValuesensorFailureConditionThe initialization failed due to a failure within the target biometric sensorRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureA sensorFailure status must only be used to report failures that occurred within the target biometric sensor, not a failure within the web service ( REF _Ref280707040 \r \h \* MERGEFORMAT 6.10.5.3).
Lock Not Held
Status ValuelockNotHeldConditionInitialization could not be performed because the requesting client does not hold the lockRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockNotHeld"Optional ElementsNoneSensor operations require that the requesting client holds the service lock.
Lock Held by Another
Status ValuelockHeldByAnotherConditionInitialization could not be performed because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockHeldByAnother"Optional ElementsNoneSensor Busy
Status ValuesensorBusyConditionIf the initialization could not be performed because the service is already performing a sensor operation.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorBusy"Optional ElementsNoneSensor Timeout
Status ValuesensorTimeoutConditionInitialization could not be performed because the target biometric sensor took too long to complete the initialization request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorTimeout"Optional ElementsNoneA service did not receive a timely response from the target biometric sensor. This condition is distinct from the clients originating HTTP request, which may have its own, independent timeout. (See REF _Ref284581851 \r \h A.3 for information on how a client might determine timeouts.)
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Get Configuration
Overview
DescriptionRetrieve metadata about the target biometric sensors current configurationURL Template/configure/{sessionId}HTTP Method GET URL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting the configurationInput PayloadNoneIdempotentYesSensor OperationYesResult Summary
successstatus = "success"metadata = current configuration of the sensor (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)canceledstatus = "canceled"canceledWithSensorFailurestatus = "canceledWithSensorFailure"sensorFailurestatus = "sensorFailure"lockNotHeldstatus = "lockNotHeld"lockHeldByAnotherstatus = "lockHeldByAnother"initializationNeededstatus = "initializationNeeded"configurationNeededstatus = "configurationNeeded"sensorBusystatus = "sensorBusy"sensorTimeoutstatus = "sensorTimeout"badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
The get configuration operation retrieves the services current configuration.
Example SEQ Example \* MERGEFORMAT 36: The following represents a raw request to retrieve the current configuration information of the service.
GET http://10.0.0.8:8000/Service/configure/d745cd19-facd-4f91-8774-aac5ca9766a2 HTTP/1.1
Content-Type: application/xml
Host: 10.0.0.8:8000
Example SEQ Example \* MERGEFORMAT 37: The following is the raw response from the previous request. The metadata element in the result contains a Dictionary ( REF _Ref281914219 \r \h 3.4) of parameter names and their respective values.
HTTP/1.1 200 OK
Content-Length: 554
Content-Type: application/xml; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 03 Jan 2012 14:57:29 GMT
success
-
width
800
-
height
600
-
frameRate
15
Unique Knowledge
As specified, the get configuration can be used to obtain knowledge about unique characteristics of a service. Through get configuration, a service may expose implementation and/or service-specific configuration parameter names and values that are not explicitly described in this document.
Return Values Detail
Overview
The get configuration operation must return a Result according to the constraints described in this subsection ( REF _Ref401905089 \w \h 6.11.5).
Success
Status ValuesuccessConditionThe service provides the current configurationRequired Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "success"
metadata (Dictionary, REF _Ref281914219 \r \h 3.4)
the target biometric sensors current configurationOptional ElementsNoneSee REF _Ref301256146 \r \h 4.3 for information regarding configurations.
Failure
Status ValuefailureConditionThe service cannot provide the current configuration due to service (not target biometric sensor) error.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [XMSCHEMA-2])
an informative description of the nature of the failureServices must only use this status to report failures that occur within the web service, not the target biometric sensor (see REF _Ref281305298 \r \h \* MERGEFORMAT 6.11.5.6, REF _Ref281305300 \r \h \* MERGEFORMAT 6.11.5.7).
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Canceled
Status ValuecanceledConditionThe get configuration operation was interrupted by a cancellation request.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "canceled"Optional ElementsNoneSee REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Canceled with Sensor Failure
Status ValuecanceledWithSensorFailureConditionThe get configuration operation was interrupted by a cancellation request during which the target biometric sensor experienced a failureRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceledWithSensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must return a canceledWithSensorFailure result if a cancellation request caused a failure within the target biometric sensor. Clients receiving this result may need to perform initialization to restore full functionality. See REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Sensor Failure
Status ValuesensorFailureConditionThe configuration could not be queried due to a failure within the target biometric sensor.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "sensorFailure"Optional Elementsmessage (xs:string, [XMSCHEMA-2])
an informative description of the nature of the failureA sensorFailure status must only be used to report failures that occurred within the target biometric sensor, not a failure within the web service ( REF _Ref280707040 \r \h \* MERGEFORMAT 6.10.5.3).
Lock Not Held
Status ValuelockNotHeldConditionThe configuration could not be queried because the requesting client does not hold the lock.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "lockNotHeld"Optional ElementsNoneSensor operations require that the requesting client holds the service lock.
Lock Held by Another
Status ValuelockHeldByAnotherConditionThe configuration could not be queried because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "lockHeldByAnother"Optional ElementsNoneInitialization Needed
Status ValueinitializationNeededConditionThe configuration could not be queried because the target biometric sensor has not been initialized.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "initializationNeeded"Optional ElementsNoneServices should be able to provide the sensors configuration without initialization; however, this is not strictly necessary. Regardless, robust clients should assume that configuration will require initialization.
Configuration Needed
Status ValueconfigurationNeededConditionThe configuration could not be queried because the target biometric sensor has not been initialized.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "configurationNeeded"Optional ElementsNoneServices may require configuration to be set before a configuration can be retrieved if a service does not provide a valid default configuration.
Sensor Busy
Status ValuesensorBusyConditionIf the configuration could not be queried because the service is already performing a sensor operation.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorBusy"Optional ElementsNoneSensor Timeout
Status ValuesensorTimeoutConditionThe configuration could not be queried because the target biometric sensor took too long to complete the request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorTimeout"Optional ElementsNoneA sensorTimeout result indicates that the service did not receive a timely response from the target biometric sensor. This condition is distinct from the clients originating HTTP request, which may have its own, independent timeout. (See REF _Ref284581851 \r \h A.3 for information on how a client might determine timeouts.)
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Set Configuration
Overview
DescriptionSet the target biometric sensors configurationURL Template/configure/{sessionId}HTTP Method POST URL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session setting the configurationInput PayloadDesired sensor configuration (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)IdempotentYesSensor OperationYesResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)canceledstatus = "canceled"canceledWithSensorFailurestatus = "canceledWithSensorFailure"sensorFailurestatus = "sensorFailure"lockNotHeldstatus = "lockNotHeld"lockHeldByAnotherstatus = "lockHeldByAnother"initializationNeededstatus = "initializationNeeded"sensorBusystatus = "sensorBusy"sensorTimeoutstatus = "sensorTimeout"unsupportedstatus = "unsupported"
badFields = { field names } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = {"sessionId"} (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
(or)
status = "badValue"
badFields = { field names } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)noSuchParameterstatus = "unsupported"
badFields = { field names } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
The set configuration operation sets the configuration of a services target biometric sensor.
The set configuration operation is the only operation that takes input within the body of the HTTP request. The desired configuration must be sent as a single Dictionary ( REF _Ref310597518 \r \h 3.4) element named configuration. See REF _Ref301256146 \r \h 4.3 for information regarding configurations. See REF _Ref363508491 \r \h Appendix A for a complete XML Schema for this specification. The root element of the configuration data must conform to the following XML definition:
Example SEQ Example \* MERGEFORMAT 38: The following represents a raw request to configure a service at http://10.0.0.8:8000/Sensor such that width=800, height=600, and frameRate=15. (In this example, each value element contains fully qualified namespace information, although this is not necessary.)
POST http://10.0.0.8:8000/Service/configure/d745cd19-facd-4f91-8774-aac5ca9766a2 HTTP/1.1
Content-Type: application/xml
Host: 10.0.0.8:8000
Content-Length: 459
Expect: 100-continue
-
width
800
-
height
600
-
frameRate
15
More information regarding the use of the xmlns attribute can be found in [XML-NAMES].
Unique Knowledge
The set configuration can be used to provide knowledge about unique characteristics to a service. Through set configuration, a client may provide implementation and/or service-specific parameter names and values that are not defined in this specification (see REF _Ref363508520 \r \h Appendix A for further information on parameters).
Return Values Detail
Overview
The set configuration operation must return a Result according to the constraints described in this subsection ( REF _Ref401905135 \w \h 6.12.5).
Success
Status ValuesuccessConditionThe service was able to successfully set the full configuration Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneFailure
Status ValuefailureConditionThe service cannot set the desired configuration due to service (not target biometric sensor) error.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failure Services must only use this status to report failures that occur within the web service, not the target biometric sensor (see REF _Ref286730999 \r \h 6.12.5.6, REF _Ref286730995 \r \h 6.12.5.7).
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
Canceled
Status ValuecanceledConditionThe set configuration operation was interrupted by a cancellation request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceled"Optional ElementsNoneSee REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Canceled with Sensor Failure
Status ValuecanceledWithSensorFailureConditionThe set configuration operation was interrupted by a cancellation request during which the target biometric sensor experienced a failureRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceledWithSensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must return a canceledWithSensorFailure result if a cancellation request caused a failure within the target biometric sensor. Clients receiving this result may need to perform initialization to restore full functionality. See REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Sensor Failure
Status ValuesensorFailureConditionThe configuration could not be set due to a failure within the target biometric sensor.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureA sensorFailure status must only be used to report failures that occurred within the target biometric sensor, not a failure within the web service ( REF _Ref282153919 \r \h \* MERGEFORMAT 6.12.5.3). Errors with the configuration itself should be reported via an unsupported ( REF _Ref282154596 \r \h \* MERGEFORMAT 6.12.5.13), badValue ( REF _Ref282154605 \r \h \* MERGEFORMAT 6.12.5.14), or badValue status ( REF _Ref282154611 \r \h \* MERGEFORMAT 6.12.5.15).
Lock Not Held
Status ValuelockNotHeldConditionThe configuration could not be queried because the requesting client does not hold the lock.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockNotHeld"Optional ElementsNoneSensor operations require that the requesting client holds the service lock.
Lock Held by Another
Status ValuelockHeldByAnotherConditionThe configuration could not be set because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockHeldByAnother"Optional ElementsNoneInitialization Needed
Status ValueinitializationNeededConditionThe configuration could not be set because the target biometric sensor has not been initialized.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "initializationNeeded"Optional ElementsNoneServices should be able to set the configuration without initialization; however, this is not strictly necessary. Similarly, clients should assume that setting configuration will require initialization.
Sensor Busy
Status ValuesensorBusyConditionIf the configuration could not be performed because the service is already performing a sensor operation.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorBusy"Optional ElementsNoneSensor Timeout
Status ValuesensorTimeoutConditionThe configuration could not be set because the target biometric sensor took too long to complete the request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorTimeout"Optional ElementsNoneA sensorTimeout result indicates that the service did not receive a timely response from the target biometric sensor. Note that this condition is distinct from the clients originating HTTP request, which may have its own, independent timeout. (See REF _Ref284581851 \r \h A.3 for information on how a client might determine timeouts.)
Unsupported
Status ValueunsupportedConditionThe requested configuration contains one or more values that are syntactically and semantically valid, but not supported by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "unsupported"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the field name(s) that corresponding to the unsupported value(s)Optional ElementsNoneReturning multiple fields allows a service to indicate that a particular combination of parameters is not supported by a service (i.e., there is no direct mechanism for encoding co-occurrence constraints). See REF _Ref284581998 \r \h 6.2.3 for additional information on how services must handle parameter failures.
Example SEQ Example \* MERGEFORMAT 39: A WS-BD service uses a very basic off-the-shelf web camera with limited capabilities. This camera has three parameters that are all dependent on each other: ImageHeight, ImageWidth, and FrameRate. The respective allowed values for each parameter might look like: {240, 480, 600, 768}, {320, 640, 800, 1024}, and {5, 10, 15, 20, 30}. Configuring the sensor will return unsupported when the client tries to set ImageHeight=768, ImageWidth=1024, and FrameRate=30; this camera might not support capturing images of a higher resolution at a fast frame rate. Another example is configuring the sensor to use ImageHeight=240 and ImageWidth=1024; as this is a very basic web camera, it might not support capturing images at this resolution. In both cases, the values provided for each parameter are individually valid but the overall validity is dependent on the combination of parameters
Bad Value
Status ValuebadValueConditionEither:
The provided session id is not a well-formed UUID, or,
The requested configuration contains a parameter value that is either syntactically (e.g., an inappropriate data type) or semantically (e.g., a value outside of an acceptable range) invalid.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains either
the single field name, "sessionId", or
the field name(s) that contain invalid value(s)Optional ElementsNoneNotice that for the set configuration operation, an invalid URL parameter or one or more invalid input payload parameters can trigger a badValue status.
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
No Such Parameter
Status ValuenoSuchParameterConditionThe requested configuration contains a parameter name that is not recognized by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "noSuchParameter"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the field name(s) that are not recognized by the serviceOptional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Capture
Overview
DescriptionCapture biometric dataURL Template/capture/{sessionId}HTTP Method POST URL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting the captureInput PayloadNoneIdempotentNoSensor OperationYesResult Summary
successstatus = "success"
captureIds = { identifiers of captured data } (UuidArray, REF _Ref401923979 \w \h 3.9)failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)canceledstatus = canceled"canceledWithSensorFailurestatus = "canceledWithSensorFailure"sensorFailurestatus = "sensorFailure"lockNotHeldstatus = "lockNotHeld"lockHeldByAnotherstatus = "lockHeldByAnother"initializationNeededstatus = "initializationNeeded"configurationNeededstatus = "configurationNeeded"sensorBusystatus = "sensorBusy"sensorTimeoutstatus = "sensorTimeout"badValuestatus = "badValue"badFields = { "sessionId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)Usage
General
The capture operation triggers biometric acquisition. On success, the operation returns one or more identifiers, or capture ids. Naturally, the capture operation is not idempotent. Each capture operation returns unique identifierseach execution returning references that are particular to that capture. Clients then can retrieve the captured data itself by passing a capture id as a URL parameter to the download operation.
Multiple capture ids are supported to accommodate sensors that return collections of biometric data. For example, a multi-sensor array might save an image per sensor. A mixed-modality sensor might assign a different capture id for each modality.
Important: The capture operation may include some post-acquisition processing. Although post-acquisition processing is directly tied to the capture operation, its effects are primarily on data transfer, and is therefore discussed in detail within the download operation documentation ( REF _Ref284591070 \r \h 6.14.3.3)
Providing Timing Information
Depending on the sensor, a capture operation may take anywhere from milliseconds to tens of seconds to execute. (It is possible to have even longer running capture operations than this, but special accommodations may need to be made on the server and client side to compensate for typical HTTP timeouts.) By design, there is no explicit mechanism for a client to determine how long a capture operation will take. However, services can provide hints through capture timeout information ( REF _Ref284424825 \r \h A.3.5), and clients can automatically adjust their own timeouts and behavior accordingly.
Unique Knowledge
As specified, the capture operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The capture operation must return a Result according to the constraints described in this subsection ( REF _Ref401905185 \w \h 6.13.5).
Success
Status ValuesuccessConditionThe service successfully performed a biometric acquisitionRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"
captureIds (UuidArray, REF _Ref401923993 \w \h 3.9)
one more UUIDs that uniquely identify the data acquired by the operationOptional ElementsNoneSee the usage requirements for capture ( REF _Ref284596064 \r \h 6.13.3) and download ( REF _Ref284596081 \r \h 6.14.3) for full detail.
Failure
Status ValuefailureConditionThe service cannot perform the capture due to a service (not target biometric sensor) error.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failure Services must only use this status to report failures that occur within the web service, not the target biometric sensor (see REF _Ref284581753 \r \h 6.13.5.6, REF _Ref284581762 \r \h 6.13.5.7). A service may fail at capture if there is not enough internal storage available to accommodate the captured data ( REF _Ref284598798 \r \h A.4).
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not registered with the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h \* MERGEFORMAT 6.2.3 for general information on how services must handle parameter failures.
Canceled
Status ValuecanceledConditionThe capture operation was interrupted by a cancellation request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceled"Optional ElementsNoneSee REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Canceled with Sensor Failure
Status ValuecanceledWithSensorFailureConditionThe capture operation was interrupted by a cancellation request during which the target biometric sensor experienced a failureRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "canceledWithSensorFailure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices must return a canceledWithSensorFailure result if a cancellation request caused a failure within the target biometric sensor. Clients receiving this result may need to perform initialization to restore full functionality. See REF _Ref284932914 \r \h 6.17.3.3 for information about what may trigger a cancellation.
Sensor Failure
Status ValuesensorFailureConditionThe service could perform the capture due to a failure within the target biometric sensor.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorFailure"Optional Elementsmessage (xs:string, [XMSCHEMA-2])
an informative description of the nature of the failureA sensorFailure status must only be used to report failures that occurred within the target biometric sensor, not a failure within the web service ( REF _Ref284581726 \r \h 6.13.5.3).
Lock Not Held
Status ValuelockNotHeldConditionThe service could not perform a capture because the requesting client does not hold the lock.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockNotHeld"Optional ElementsNoneSensor operations require that the requesting client holds the service lock.
Lock Held by Another
Status ValuelockHeldByAnotherConditionThe service could not perform a capture because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockHeldByAnother"Optional ElementsNoneInitialization Needed
Status ValueinitializationNeededConditionThe service could not perform a capture because the target biometric sensor has not been initialized.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "initializationNeeded"Optional ElementsNoneServices should be able perform capture without explicit initialization. However, the specification recognizes that this is not always possible, particularly for physically separated implementations. Regardless, for robustness, clients should assume that setting configuration will require initialization.
Configuration Needed
Status ValueconfigurationNeededConditionThe capture could not be set because the target biometric sensor has not been configured.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "configurationNeeded"Optional ElementsNoneA service should offer a default configuration to allow capture to be performed without an explicit configuration. Regardless, for robustness, clients should assume that capture requires configuration.
Sensor Busy
Status ValuesensorBusyConditionIf the capture could not be performed because the service is already performing a sensor operation.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorBusy"Optional ElementsNoneSensor Timeout
Status ValuesensorTimeoutConditionThe service could not perform a capture because the target biometric sensor took too long to complete the request.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "sensorTimeout"Optional ElementsNoneA sensorTimeout result indicates that the service did not receive a timely response from the target biometric sensor. Note that this condition is distinct from the clients originating HTTP request, which may have its own, independent timeout. (See REF _Ref284581851 \r \h A.3 for information on how a client might determine timeouts.)
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Download
Overview
DescriptionDownload the captured biometric dataURL Template/download/{captureId}HTTP Method GETURL Parameters{captureId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the captured data to downloadInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"
metadata = sensor configuration at the time of capture (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)sensorData = biometric data (xs:base64Binary)failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "captureId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = { "captureId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)preparingDownloadstatus = "preparingDownload"Usage
General
The download operation allows a client to retrieve biometric data acquired during a particular capture.
Capture and Download as Separate Operations
WS-BD decouples the acquisition operation (capture) from the data transfer (download) operation. This has two key benefits. First, it is a better fit for services that have post-acquisition processes. Second, it allows multiple clients to download the captured biometric data by exploiting the concurrent nature of HTTP. By making download a simple data transfer operation, service can handle multiple, concurrent downloads without requiring locking.
Services with Post-Acquisition Processing
A service does not need to make the captured data available immediately after capture; a service may have distinct acquisition and post-acquisition processes. The following are two examples of such services:
Example SEQ Example \* MERGEFORMAT 40: A service exposing a fingerprint scanner also performs post processing on a fingerprint imagesegmentation, quality assessment, and templatization.
Example SEQ Example \* MERGEFORMAT 41: A service exposes a digital camera in which the captured image is not immediately available after a photo is taken; the image may need to be downloaded from to the cameras internal storage or from the camera to the host computer (in a physically separated implementation). If the digital camera was unavailable for an operation due to a data transfer, a client requesting a sensor operation would receive a sensorBusy status.
The first method is to perform the post-processing within the capture operation itself. I.e., capture not only blocks for the acquisition to be performed, but also blocks for the post-processingreturning when the post-processing is complete. This type of capture is the easier of the two to both (a) implement on the client, and (b) use by a client.
Example SEQ Example \* MERGEFORMAT 42: REF _Ref284582620 \h \* MERGEFORMAT Figure 9 illustrates an example of a capture operation that includes post-processing. Once the post-processing is complete, capture ids are returned to the client.
Figure SEQ Figure \* ARABIC 9. Including post-processing in the capture operation means downloads are immediately available when capture completes. Unless specified, the status of all returned operations is success.
In the second method, post-processing may be performed by the web service after the capture operation returns. Capture ids are still returned to the client, but are in an intermediate state. This exposes a window of time in which the capture is complete, but the biometric data is not yet ready for retrieval or download. Data-related operations (download, get download info, and thrifty download) performed within this window return a preparingDownload status to clients to indicate that the captured data is currently in an intermediate statecaptured, but not yet ready for retrieval.
Example SEQ Example \* MERGEFORMAT 43: REF _Ref284590573 \h \* MERGEFORMAT Figure 10 illustrates an example of a capture operation with separate post-processing. Returning to the example of the fingerprint scanner that transforms a raw biometric sample into a template after acquisition, assume that the service performs templatization after capture returns. During post-processing, requests for the captured data return preparingDownload, but the sensor itself is available for another capture operation.
Figure SEQ Figure \* ARABIC 10. Example of capture with separate post-acquisition processing that involves the target biometric sensor. Because the post-acquisition processing does not involve the target biometric sensor, it is available for sensor operations. Unless specified, the status of all returned operations is success.
Services with an independent post-processing step should perform the post-processing on an independent unit of execution (e.g., a separate thread, or process). However, post-processing may include a sensor operation, which would interfere with incoming sensor requests.
Example SEQ Example \* MERGEFORMAT 44: REF _Ref284590892 \h \* MERGEFORMAT Figure 11 illustrates another variation on a capture operation with separate post-processing. Return to the digital camera example, but assume that it is a physically separate implementation and capture operation returns immediately after acquisition. The service also has a post-acquisition process that downloads the image data from the camera to a computer. Like the previous example, during post-processing, requests for the captured data return preparingDownload. However, the sensor is not available for additional operations because the post-processing step requires complete control over the camera to transfer the images to the host machine: preparing them for download.
Figure SEQ Figure \* ARABIC 11. Because the post-acquisition processing does not involve the target biometric sensor, it is available for sensor operations. Unless specified, the status of all returned operations is success.
Unless there is an advantage to doing so, when post-acquisition processing includes a sensor operation, implementers should avoid having a capture operation that returns directly after acquisition. In this case, even when the capture operation finishes, clients cannot perform a sensor operation until the post-acquisition processing is complete.
In general, implementers should try to combine both the acquisition and post-acquisition processing into one capture operationparticularly if the delay due to post-acquisition processing is either operationally acceptable or a relatively insignificant contributor to the combined time.
A download operation must return failure if the post-acquisition processing cannot be completed successfully. Such failures cannot be reflected in the originating capture operation that operation has already returned successfully with capture ids. Services must eventually resolve all preparingDownload statuses to success or failure. Through get service info, a service can provide information to a client on how long to wait after capture until a preparingDownload is fully resolved.
Client Notification
A client that receives a preparingDownload must poll the service until the requested data becomes available. However, through get service info, a service can provide hints to a client on how long to wait after capture until data can be downloaded ( REF _Ref284588850 \r \h A.3.6)
Unique Knowledge
The download operation can be used to provide metadata, which may be unique to the service, through the metadata element. See REF _Ref363508585 \r \h 4 for information regarding metadata.
Return Values Detail
Overview
The download operation must return a Result according to the constraints described in this section ( REF _Ref401905256 \w \h 6.14.5).
Success
Status ValuesuccessConditionThe service can provide the requested dataRequired Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "success"
metadata (Dictionary, REF _Ref281914219 \r \h 3.4)
sensor metadata as it was at the time of capture
sensorData (xs:base64Binary, [XMSCHEMA-2])
the biometric data corresponding to the requested capture id, base-64 encodedOptional ElementsNoneA successful download must populate the Result with all of the following information:
The status element must be populated with the Status literal success.
The metadata element must be populated with metadata of the biometric data and the configuration held by the target biometric sensor at the time of capture.
The sensorData element must contain the biometric data, base-64 encoded (xs:base64Binary), corresponding to the requested capture id.
See the usage requirements for both capture ( REF _Ref284596064 \r \h 6.13.3) and download ( REF _Ref284596081 \r \h 6.14.3) for more detail regarding the conditions under which a service is permitted to accept or deny download requests.
Failure
Status ValuefailureConditionThe service cannot provide the requested data.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureA service might not be able to provide the requested data due to failure in post-acquisition processing, a corrupted data store or other service or storage related failure.
Invalid Id
Status ValueinvalidIdConditionThe provided capture id is not recognized by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "captureId"Optional ElementsNoneA capture id is invalid if it was not returned by a capture operation. A capture id may become unrecognized by the service automatically if the service automatically clears storage space to accommodate new captures ( REF _Ref284598798 \r \h A.4).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Bad Value
Status ValuebadValueConditionThe provided capture id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "captureId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Preparing Download
Status ValuepreparingDownloadConditionThe requested data cannot be provided because the service is currently performing a post-acquisition processi.e., preparing it for downloadRequired Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "preparingDownload"Optional ElementsNoneSee the Us for both capture ( REF _Ref284596064 \r \h 6.13.3) and download ( REF _Ref284596081 \r \h 6.14.3) for full detail.
Get Download Info
Overview
DescriptionGet only the metadata associated with a particular captureURL Template/download/{captureId}/infoHTTP Method GETURL Parameters{captureId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the captured data to queryInput PayloadNot applicableIdempotentYesSensor OperationNoResult Summary
successstatus = "success"
metadata = sensor configuration at the time of capturefailurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"badFields = { "captureId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = { "captureId" } (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)preparingDownloadstatus = "preparingDownload"Usage
Given the potential large size of some biometric data the get download info operation provides clients with a way to get information about the biometric data without needing to transfer the biometric data itself. It is logically equivalent to the download operation, but without any sensor data. Therefore, unless detailed otherwise, the usage requirements for download ( REF _Ref284574710 \r \h 6.15.3) also apply to get download info.
Unique Knowledge
The get download info operation can be used to provide metadata, which may be unique to the service, through the metadata element. See REF _Ref363508627 \r \h 4 for information regarding metadata.
Return Values Detail
Overview
The get download info operation must return a Result according to the constraints described in this subsection ( REF _Ref401905315 \w \h 6.15.5).
Success
Status ValuesuccessConditionThe service can provide the requested dataRequired Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "success"
metadata (Dictionary, REF _Ref281914219 \r \h 3.4)
the sensors configuration as it was set at the time of captureOptional ElementsNoneA successful get download info operation returns all of the same information as a successful download operation ( REF _Ref286316234 \r \h 6.14.5.2), but without the sensor data.
Failure
Status ValuefailureConditionThe service cannot provide the requested data.Required Elementsstatus (Status, REF _Ref286240918 \r \h " \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failure A service might not be able to provide the requested data due to failure in post-acquisition processing, a corrupted data store or other service or storage related failure.
Invalid Id
Status ValueinvalidIdConditionThe provided capture id is not recognized by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "captureId"Optional ElementsNoneA capture id is invalid if it was not returned by a capture operation. A capture id may become unrecognized by the service automatically if the service automatically clears storage space to accommodate new captures ( REF _Ref284598798 \r \h A.4).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Bad Value
Status ValuebadValueConditionThe provided capture id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "captureId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Preparing Download
Status ValuepreparingDownloadConditionThe requested data cannot be provided because the service is currently performing a post-acquisition processi.e., preparing it for downloadRequired Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "preparingDownload"Optional ElementsNoneSee the usage requirements for both capture ( REF _Ref284596064 \r \h 6.13.3) and download ( REF _Ref284596081 \r \h 6.14.3) for full detail.
Thrifty Download
Overview
DescriptionDownload a compact representation of the captured biometric data suitable for previewURL Template/download/{captureId}/{maxSize}HTTP Method GETURL Parameters{captureId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the captured data to download
{maxSize} (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
Content-type dependent indicator of maximum permitted download sizeInput PayloadNoneIdempotentYesSensor OperationNoResult Summary
successstatus = "success"metadata = minimal metadata describing the captured data (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4, REF _Ref309811494 \r \h \* MERGEFORMAT 4.4.2)
sensorData = biometric data (xs:base64Binary)failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"
badFields = {"captureId"} (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)badValuestatus = "badValue"badFields = either "captureId", "maxSize", or both (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)unsupportedstatus = "unsupported"preparingDownloadstatus = "preparingDownload"Usage
The thrifty download operation allows a client to retrieve a compact representation of the biometric data acquired during a particular capture. It is logically equivalent to the download operation, but provides a compact version of the sensor data. Therefore, unless detailed otherwise, the usage requirements for download ( REF _Ref284574710 \r \h 6.15.3) also apply to get download info.
The suitability of the thrifty download data as a biometric is implementation-dependent. For some applications, the compact representation may be suitable for use within a biometric algorithm; for others, it may only serve the purpose of preview.
For images, the maxSize parameter describes the maximum image width or height (in pixels) that the service may return; neither dimension SHALL exceed maxSize. It is expected that servers will dynamically scale the captured data to fulfill a client request. This is not strictly necessary, however, as long as the maximum size requirements are met.
For non-images, the default behavior is to return unsupported. It is possible to use URL parameter maxSize as general purpose parameter with implementation-dependent semantics. (See the next section for details.)
Unique Knowledge
The thrifty download operation can be used to provide knowledge about unique characteristics to a service. Through thrifty download, a service may (a) redefine the semantics of maxSize or (b) provide a data in a format that does not conform to the explicit types defined in this specification (see REF _Ref363508726 \r \h Appendix B for content types).
Return Values Detail
Overview
The thrifty download operation must return a Result according to the constraints described in this subsection ( REF _Ref401905353 \w \h 6.16.5).
Success
Status ValuesuccessConditionThe service can provide the requested dataRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"
metadata (Dictionary, REF _Ref281914219 \r \h \* MERGEFORMAT 3.4)
minimal representation of sensor metadata as it was at the time of capture. See REF _Ref309811494 \r \h \* MERGEFORMAT 4.4.2 for information regarding minimal metadata.
sensorData (xs:base64Binary, [ REF XMSCHEMA2 \h XMSCHEMA-2])
the biometric data corresponding to the requested capture id, base-64 encoded, scaled appropriately to the maxSize parameter.Optional ElementsNoneFor increased efficiency, a successful thrifty download operation only returns the sensor data, and a subset of associated metadata. The metadata returned should be information that is absolutely essential to open or decode the returned sensor data.
Failure
Status ValuefailureConditionThe service cannot provide the requested data.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureA service might not be able to provide the requested data due to a corrupted data store or other service or storage related failure.
Invalid Id
Status ValueinvalidIdConditionThe provided capture id is not recognized by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "captureId"Optional ElementsNoneA capture id is invalid if it does not correspond to a capture operation. A capture id may become unrecognized by the service automatically if the service automatically clears storage space to accommodate new captures ( REF _Ref284598798 \r \h A.4).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Bad Value
Status ValuebadValueConditionThe provided capture id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains one or both of the following fields:
"captureId" if the provided session id is not well-formed
"maxSize" if the provided maxSize parameter is not well-formedOptional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Unsupported
Status ValueunsupportedConditionThe service does not support thrifty downloadRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "unsupported"Optional ElementsNoneServices that capture biometrics that are not image-based should return unsupported.
Preparing Download
Status ValuepreparingDownloadConditionThe requested data cannot be provided because the service is currently performing a post-acquisition processi.e., preparing it for downloadRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "preparingDownload"Optional ElementsNoneLike download, the availability of thrifty download data may also be affected by the sequencing of post-acquisition processing. See REF _Ref284591070 \r \h 6.14.3.3 for detail.
Cancel
Overview
DescriptionCancel the current sensor operationURL Template/cancel/{sessionId}HTTP Method POSTURL Parameters{sessionId} (UUID, REF _Ref280079094 \n \h \* MERGEFORMAT 3.3)
Identity of the session requesting cancellationInput PayloadNoneIdempotentYesSensor OperationYesResult Summary
successstatus = "success"failurestatus = "failure"
message* = informative message describing failureinvalidIdstatus = "invalidId"lockNotHeldstatus = "lockNotHeld"lockHeldByAnotherstatus = "lockHeldByAnother"badValuestatus = "badValue"
badFields = {"sessionId"}Usage
General
The cancel operation stops any currently running sensor operation; it has no effect on non-sensor operations. If cancellation of an active sensor operation is successful, cancel operation receives a success result, while the canceled operation receives a canceled (or canceledWithSensorFailure) result. As long as the operation is canceled, the cancel operation itself receives a success result, regardless if cancellation caused a sensor failure. In other words, if cancellation caused a fault within the target biometric sensor, as long as the sensor operation has stopped running, the cancel operation is considered to be successful.
All services must provide cancellation for all sensor operations.
Example SEQ Example \* MERGEFORMAT 45: REF _Ref401905448 \h Figure 12 illustrates a client that cancels a capture request.
Figure SEQ Figure \* ARABIC 12. Example sequence of events for a client initially requesting a capture followed by a cancellation request.
Canceling Non-Sensor Operations
Clients are responsible for canceling all non-sensor operations via client-side mechanisms only. Cancellation of sensor operations requires a separate service operation, since a service may need to manually interrupt a busy sensor. A service that had its client terminate a non-sensor operation would have no way to easily determine that a cancellation was requested.
Example SEQ Example \* MERGEFORMAT 46: REF _Ref401905448 \h Figure 12 illustrates a client that cancels download request (a non-sensor operation).
Figure SEQ Figure \* ARABIC 13. Cancellations of non-sensor operations do not require a cancel operation to be requested to the service. An example of this is where a client initiates then cancels a download operation.
Cancellation Triggers
Typically, the client that originates the sensor operation to be cancelled also initiates the cancellation request. Because WSBD operations are performed synchronously, cancellations are typically initiated on a separate unit of execution such as an independent thread or process.
Notice that the only requirement to perform cancellation is that the requesting client holds the service lock. It is not a requirement that the client that originates the sensor operation to be canceled also initiates the cancellation request. Therefore, it is possible that a client may cancel the sensor operation initiated by another client. This occurs if a peer client (a) manages to steal the service lock before the sensor operation is completed, or (b) is provided with the originating clients session id.
A service may also self-initiate cancellation. In normal operation, a service that does not receive a timely response from a target biometric sensor would return sensorTimeout. However, if the services internal timeout mechanism fails, a service may initiate a cancel operation itself. Implementers should use this as a last resort compensating action.
In summary, clients should be designed to not expect to be able to match a cancelation notification to any specific request or operation.
Unique Knowledge
As specified, the cancel operation cannot be used to provide or obtain knowledge about unique characteristics of a client or service.
Return Values Detail
Overview
The cancel operation must return a Result according to the constraints described in this subsection ( REF _Ref401905674 \w \h 6.17.5).
Success
Status ValuesuccessConditionThe service successfully canceled the sensor operationRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "success"Optional ElementsNoneSee the Usage sections for capture ( REF _Ref284596064 \r \h 6.13.3) and download ( REF _Ref284596081 \r \h 6.14.3) for full detail.
Failure
Status ValuefailureConditionThe service could not cancel the sensor operationRequired Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)the literal "failure"Optional Elementsmessage (xs:string, [ REF XMSCHEMA2 \h XMSCHEMA-2])
an informative description of the nature of the failureServices should try to return failure in a timely fashionthere is little advantage to a client if it receives the cancellation failure after the sensor operation to be canceled completes.
Invalid Id
Status ValueinvalidIdConditionThe provided session id is not recognized by the service.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "invalidId"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneA session id is invalid if it does not correspond to an active registration. A session id may become unregistered from a service through explicit unregistration or triggered automatically by the service due to inactivity ( REF _Ref280092668 \n \h \* MERGEFORMAT 6.5.5.2).
See REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Lock Not Held
Status ValuelockNotHeldConditionThe service could cancel the operation because the requesting client does not hold the lock.Required Elementsstatus (Status, REF _Ref286240918 \r \h 3.13)
the literal "lockNotHeld"Optional ElementsNoneSensor operations require that the requesting client holds the service lock.
Lock Held by Another
Status ValuelockHeldByAnotherConditionThe service could not cancel the operation because the lock is held by another client.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "lockHeldByAnother"Optional ElementsNone
Bad Value
Status ValuebadValueConditionThe provided session id is not a well-formed UUID.Required Elementsstatus (Status, REF _Ref286240918 \r \h \* MERGEFORMAT 3.13)
the literal "badValue"
badFields (StringArray, REF _Ref302380364 \r \h \* MERGEFORMAT 3.8)
an array that contains the single field name, "sessionId"Optional ElementsNoneSee REF _Ref284581998 \r \h 6.2.3 for general information on how services must handle parameter failures.
Conformance Profiles
About
This section of the specification describes the requirements regarding the conformance of a service to the WS-Biometric Devices specification.
Conformance Requirements
Conformance to WS-Biometric Devices applies to WS-Biometric Devices servers. This version of the specification does not address client conformance.
In order to conform to this specification, a service must
fully implement REF _Ref401568494 \w \h 2, REF _Ref401568487 \h Design Concepts and Architecture
fully implement REF _Ref401568543 \w \h 3, REF _Ref401568510 \h Data Dictionary,
fully implement REF _Ref401568609 \w \h 4, REF _Ref401568607 \h Metadata,
optionally implement REF _Ref401568634 \w \h 5, REF _Ref401568858 \h Live Preview
implement REF _Ref401564848 \r \h 6, REF _Ref401568881 \h Operations, according to REF _Ref396131739 \r \h 7.5 below
fully implement REF _Ref401568936 \w \h Appendix A, REF _Ref401568933 \h Parameter Details (Normative)
use applicable data format and content-type strings in REF _Ref401568985 \w \h Appendix B, REF _Ref401568987 \h Content Type Data (Normative)
use XML that strictly validates according to the XML Schema located at HYPERLINK "http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0" http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0
where the key words must, must not, required, shall, shall not, should, should not, recommended, may and optional are to be interpreted as described REF _Ref401569416 \w \h 1.3.2.
Claims of Conformance
Implementations claiming conformance to this specification, MUST make such a claim according to all three of the following factors.
If the implementation is general or modality specific
The operations that are implemented ( REF _Ref396131739 \r \h 7.5)
If the implementation includes live preview ( REF _Ref396132177 \r \h 5)
An implementation that is modality specific must implement the service information and configuration metadata according to their respective subsection. For example, a fingerprint conformant service must implement the service and configuration information according to REF _Ref396132049 \r \h 7.6. It is possible to implement a fingerprint-based WS-Biometric Devices service without adhering to REF _Ref396132049 \r \h 7.6, however, such an implementation cannot claim modality specific conformance.
Language
Conformance claims must take the form
WS-Biometric Devices [modality] Conformance Level n [L]
where
[modality] is an optional phrase that indicates if the implementation is modality specific
L* is an indicator if the implementation supports live preview.
Square brackets, [ ], are indicator to the reader of this specification that the phrase is optional; they are not to be included in the claim itself
For example, the phrase WS-Biometric Devices Conformance Level 3 indicates that the implementation is (a) not modality specific (b) implements the operations get service information, initialize, get configuration, capture, download, and get download information and (c) does NOT support live preview. Likewise, the phrase WS-Biometric Devices Fingerprint Conformance Level 1L indicates that the implementation (a) implements the service information and configuration parameters as specified by REF _Ref396132049 \r \h 7.6, (b) implements all operations and (c) supports live-preview.
For implementations that support multiple modalities, then there SHALL be a conformance claim for each modality. For example, a converged device that supports machine readable documents, fingerprint (according to REF _Ref396132049 \r \h 7.6) and iris (according to REF _Ref396133754 \r \h 7.8) might claim WS-Biometric Devices Conformance Level 2, WS-Biometric Devices Fingerprint Conformance Level 3L, and WS-Biometric Devices Iris Conformance Level 1.
Operations & Conformance Levels
REF _Ref401911045 \h Table 9 shows three levels of conformance to this specification. An X represents that the operation requires functionality and implementation. For operations that lack an identifier, the service should implement the operation minimally by always returning success and related arbitrary data. Sending success and arbitrary data removes any concern from clients whether or not certain operations are supported by removing the responsibility of functionality and implementation from the implementer/service.
Table SEQ Table \* ARABIC 9. Operations required for each conformance level
Operation ` Conformance Level123Register ( REF _Ref371506511 \r \h \* MERGEFORMAT 6.4)XUnregister ( REF _Ref371506520 \r \h \* MERGEFORMAT 6.5)XTry Lock ( REF _Ref284846466 \r \h \* MERGEFORMAT 6.6)XSteal Lock ( REF _Ref284846472 \r \h \* MERGEFORMAT 6.7)XUnlock ( REF _Ref371506540 \r \h \* MERGEFORMAT 6.8)XGet Service Information ( REF _Ref371506500 \r \h \* MERGEFORMAT 6.9)XXXInitialize ( REF _Ref371506566 \r \h \* MERGEFORMAT 6.10)XXXGet Configuration ( REF _Ref371506589 \r \h \* MERGEFORMAT 6.11)XXXSet Configuration ( REF _Ref371506582 \r \h \* MERGEFORMAT 6.12)XXCapture ( REF _Ref371506601 \r \h \* MERGEFORMAT 6.13)XXXDownload ( REF _Ref371506610 \r \h \* MERGEFORMAT 6.14)XXXGet Download Information ( REF _Ref371506621 \r \h \* MERGEFORMAT 6.15)XXXThrifty Download ( REF _Ref371506627 \r \h \* MERGEFORMAT 6.16)XXCancel ( REF _Ref371506634 \r \h \* MERGEFORMAT 6.17)XX
Additional Supported Operations
OperationIdentifierLive Preview ( REF _Ref371506648 \r \h \* MERGEFORMAT 5)L
Fingerprint Service Information
Submodality
Formal NamesubmodalityDescriptionA distinct subtype of fingerprint modality, supported by the sensor.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesRightThumbFlat
RightIndexFlat
RightMiddleFlat
RightRingFlat
RightLittleFlat
LeftThumbFlat
LeftIndexFlat
LeftMiddleFlat
LeftRingFlat
LeftLittleFlat
LeftSlap
RightSlap
ThumbsSlap
RightThumbRolled
RightIndexRolled
RightMiddleRolled
RightRingRolled
RightLittleRolled
LeftThumbRolled
LeftIndexRolled
LeftMiddleRolled
LeftRingRolled
LeftLittleRolledImage Size
Formal NamefingerprintImageSizeDescriptionThe width and height of a resulting fingerprint image, in pixels. If this value is calculated after capture, this shall be the maximum width and height of a resulting image.Data Typeresolution [3.9]RequiredYesAllowed ValuesThe width element can be any positive integer value.
The height element can be any positive integer value.
The unit element, if defined, must be pixel or pixels.
Image Content Type
Formal NamefingerprintImageContentTypeDescriptionThe data format of the resulting fingerprint image.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesAny string value conformant with Appendix B, B.2.
Image Density
Formal NamefingerprintImageDensityDescriptionThe pixel density of a resulting image represented in pixels per inch (PPI).Data Typexs:int [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesAny positive integer value.
Face Service Information
Submodality
Formal NamesubmodalityDescriptionA distinct subtype of face modality, supported by the sensor.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesFace2d
Face3dImage Size
Formal NamefaceImageSizeDescriptionThe width and height of a resulting face image, in pixels. If this value is calculated after capture, this must be the maximum width and height of a resulting image.Data Typeresolution [3.9]RequiredYesAllowed ValuesThe width element can be any positive integer value.
The height element can be any positive integer value.
The unit element, if defined, must be pixel or pixels.
Image Content Type
Formal NamefaceImageContentTypeDescriptionThe data format of the resulting face image.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesAny string value conformant with Appendix B, B.2.
Iris Service Information
Submodality
Formal NamesubmodalityDescriptionA distinct subtype of iris modality, supported by the sensor.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesLeftIris
RightIris
BothIrisesImage Size
Formal NameirisImageSizeDescriptionThe width and height of a resulting iris image, in pixels. If this value is calculated after capture, this must be the maximum width and height of a resulting image.Data Typeresolution [3.9]RequiredYesAllowed ValuesThe width element can be any positive integer value.
The height element can be any positive integer value.
The unit element, if defined, must be pixel or pixels.
Image Content Type
Formal NameirisImageContentTypeDescriptionThe data format of the resulting iris image.Data Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesAllowed ValuesAny string value conformant with Appendix B, B.2.Parameter Details (Normative)
About
This appendix details the individual parameters available from a get service info operation. For each parameter, the following information is listed:
The formal parameter name
The expected data type of the parameters value
If a the service is required to implement the parameter
Connection Parameters
The parameters listed in this subsection ( REF _Ref401923299 \w \h A.2) describe how the service handles session lifetimes and registrations.
Last Updated
Formal NamelastUpdatedData Typexs:dateTime [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter provides a timestamp of when the service last updated the common info parameters (this parameter not withstanding). The timestamp must include time zone information. Implementers should expect clients to use this timestamp to detect if any cached values of the (other) common info parameters may have changed.
Inactivity Timeout
Formal NameinactivityTimeoutData Typexs:nonNegativeInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes how long, in seconds, a session can be inactive before it may be automatically closed by the service. A value of 0 indicates that the service never drops sessions due to inactivity.
Inactivity time is measured per session. Services must measure it as the time elapsed between (a) the time at which a client initiated the sessions most recent operation and (b) the current time. Services must only use the session id to determine a sessions inactivity time. For example, a service does not maintain different inactivity timeouts for requests that use the same session id, but originate from two different IP addresses. Services may wait longer than the inactivity timeout to drop a session, but must not drop inactive sessions any sooner than the inactivityTimeout parameter indicates.
Maximum Concurrent Sessions
Formal NamemaximumConcurrentSessionsData Typexs:positiveInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes the maximum number of concurrent sessions a service can maintain. Upon startup, a service must have zero concurrent sessions. When a client registers successfully ( REF _Ref281904658 \r \h 6.4), the service increases its count of concurrent sessions by one. After successful unregistration ( REF _Ref281306265 \r \h 6.5), the service decreases its count of concurrent sessions by one .
Least Recently Used (LRU) Sessions Automatically Dropped
Formal NameautoDropLRUSessionsData Typexs:boolean [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes whether or not the service automatically unregisters the least-recently-used session when the service has reached its maximum number of concurrent sessions. If true, then upon receiving a registration request, the service may drop the least-recently used session if the maximum number of concurrent sessions has already been reached. If false, then any registration request that would cause the service to exceed its maximum number of concurrent sessions results in failure. The service shall not drop a session that currently holds the lock unless the sessions inactivity is outside of the inactivity timeout ( REF _Ref316375043 \r \h A.2.2) threshold.
Timeout Parameters
About
Clients should not block indefinitely on any operation. However, since different services may differ significantly in the time they require to complete an operation, clients require a means to determine appropriate timeouts. The timeouts in this subsection describe how long a service waits until the service either returns sensorTimeout or initiates a service-side cancellation ( REF _Ref284933548 \r \h 6.17.3.2). Services may wait longer than the times reported here, but, (under normal operations) must not report a sensorTimeout or initiate a cancellation before the reported time elapses. In other words, a client should be able to use these timeouts to help determine a reasonable upper bound on the time required for sensor operations.
These timeouts do not include any round-trip and network delayclients should add an additional window to accommodate delays unique to that particular client-server relationship.
Initialization Timeout
Formal NameinitializationTimeoutData Typexs:positiveInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes how long, in milliseconds, a service will wait for a target biometric sensor to perform initialization before it returns sensorTimeout ( REF _Ref284934119 \r \h 6.10.5.11) or initiates a service-side cancellation ( REF _Ref284933548 \r \h \* MERGEFORMAT 6.17.3.2).
Get Configuration Timeout
Formal NamegetConfigurationTimeoutData Typexs:positiveInteger [XMSCHEMA-2]RequiredYesThis parameter describes how long, in milliseconds, a service will wait for a target biometric sensor to retrieve its configuration before it returns sensorTimeout ( REF _Ref284934294 \r \h 6.11.5.13) or initiates a service-side cancellation ( REF _Ref284933548 \r \h \* MERGEFORMAT 6.17.3.2).
Set Configuration Timeout
Formal NamesetConfigurationTimeoutData Typexs:positiveInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes how long, in milliseconds, a service will wait for a target biometric sensor to set its configuration before it returns sensorTimeout ( REF _Ref284934425 \r \h 6.12.5.12) or initiates a service-side cancellation ( REF _Ref284933548 \r \h \* MERGEFORMAT 6.17.3.2).
Capture Timeout
Formal NamecaptureTimeoutData Typexs:positiveInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes how long, in milliseconds, a service will wait for a target biometric sensor to perform biometric acquisition before it returns sensorTimeout ( REF _Ref284934425 \r \h 6.12.5.12) or initiates a service-side cancellation ( REF _Ref284933548 \r \h \* MERGEFORMAT 6.17.3.2).
Post-Acquisition Processing Time
Formal NamepostAcquisitionProcessingTimeData Typexs:nonNegativeInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes an upper bound on how long, in milliseconds, a service takes to perform post-acquisition processing. A client should not expect to be able to download captured data before this time has elapsed. Conversely, this time also describes how long after a capture a server is permitted to return preparingDownload for the provided capture ids. A value of zero (0) indicates that the service includes any post-acquisition processing within the capture operation or that no post-acquisition processing is performed.
Lock Stealing Prevention Period
Formal NamelockStealingPreventionPeriodData Typexs:nonNegativeInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes the length, in milliseconds, of the lock stealing prevention period ( REF _Ref280266744 \r \h 6.7.3.3).
Storage Parameters
About
The parameters described in this section ( REF _Ref401908475 \w \h A.4) describe how the service stores captured biometric data.
Maximum Storage Capacity
Formal NamemaximumStorageCapacityData Typexs:positiveInteger [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes how much data, in bytes, the service is capable of storing.
Least-Recently Used Capture Data Automatically Dropped
Formal NamelruCaptureDataAutomaticallyDroppedData Typexs:boolean [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes whether or not the service automatically deletes the least-recently-used capture to stay within its maximum storage capacity. If true, the service may automatically delete the least-recently used biometric data to accommodate for new data. If false, then any operation that would require the service to exceed its storage capacity would fail.
Sensor Parameters
The following parameters describe information about the sensor and its supporting features
Modality
Formal NamemodalityData Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes which modality or modalities are supported by the sensor.
REF _Ref401910244 \h Table 10 enumerates the list of modalities, as defined in [CBEFF2010], which provides the valid values for this field for currently identified modalities. Implementations are not limited to the following values, but must use them if such modality is exposed. For example, if an implementation is exposing fingerprint capture capability, Finger shall be used. If an implementation is exposing an unlisted modality, it may use another value.
Table SEQ Table \* ARABIC 10. Valid modalities
Modality ValueDescriptionScentInformation about the scent left by a subjectDNAInformation about a subjects DNAEarA subjects ear imageFaceAn image of the subjects face, either in two or three dimensionsFingerAn image of one of more of the subjects fingerprintsFootAn image of one or both of the subjects feet.VeinInformation about a subjects vein patternHandGeometryThe geometry of an subjects handIrisAn image of one of both of the subjects irisesRetinaAn image of one or both of the subjects retinasVoiceInformation about a subjects voiceGaitInformation about a subjects gait or ambulatory movementKeystrokeInformation about a subjects typing patternsLipMovementInformation about a subjects lip movementsSignatureSignInformation about a subjects signature or handwriting
Submodality
Formal NamesubmodalityData Typexs:string [ REF XMSCHEMA2 \h XMSCHEMA-2]RequiredYesThis parameter describes which submodalities are supported by the sensor. See REF _Ref367783608 \r \h 7 for submodality requirements for a particular modality.
Content Type Data (Normative)
About
This appendix contains a catalog of content types for use in conformance profiles and parameters. When appropriate, the following identified data formats must be used.
General Type
application/xmlExtensible Markup Language (XML) [ REF XML \h XML]text/plainPlaintext [ REF RFC2046 \h RFC2046]text/xmlExtensible Markup Language (XML) [ REF XML \h XML]
Image Formats
Refer to [ REF CMediaType \h CMediaType] for more information regarding a registered image type.
image/jpegJoint Photographics Experts Group [ REF JPEG \h JPEG]image/pngPortable Network Graphics [ REF PNG \h PNG]image/tiffTagged Image File Format [ REF TIFF \h TIFF]image/x-ms-bmpWindows OS/2 Bitmap Graphics [ REF BMP \h BMP]image/x-wsqWavelet Scalar Quantization (WSQ) [ REF WSQ \h WSQ]
Video Formats
Refer to [ REF CMediaType \h CMediaType] for more information regarding a registered video type.
multipart/x-mixed-replacemultipart/x-mixed-replace [ REF HTML5 \h HTML5] (12.2)video/h264H.264 Video Compression [ REF H264 \h H264]video/mpegMoving Pictures Experts Group [ REF MPEG \h MPEG]video/quicktimeQuickTime File Format [ REF QTFF \h QTFF]video/x-aviAudio Video Interleave [AVI]video/x-ms-asfAdvanced Systems Format [ REF ASF \h ASF]video/x-ms-asxAdvanced Stream Redirector [ REF ASX \h ASX]video/x-ms-wmvWindows Media Video [ REF ASF \h ASF]
Audio Formats
Refer to [ REF CMediaType \h CMediaType] for more information regarding a registered audio type.
audio/3gpp3rd Generation Partnership Project Multimedia files [ REF gpp \h 3GPP]audio/3gpp23rd Generation Partnership Project Multimedia files [ REF gpp2 \h 3GPP2]audio/mpegMoving Pictures Experts Group [ REF MPEG1 \h MPEG1]audio/oggVorbis OGG Audio File [ REF OGG \h OGG]audio/x-aiffAudio Interchange File Format [ REF aiff \h AIFF]audio/x-ms-wavWaveform Audio File Format [ REF WAVE \h WAVE]audio/x-ms-wmaWindows Media Audio [ REF ASF \h ASF]audio/x-sphereNIST Speech Header Resources [ REF SPHERE \h SPHERE]
General Biometric Formats
x-biometric/x-ansi-nist-itl-2000Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Scar Mark & Tattoo (SMT) Information [ REF AN2K \h AN2K]x-biometric/x-ansi-nist-itl-2007Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Other Biometric Information Part 1 [ REF AN2K7 \h AN2K7]x-biometric/x-ansi-nist-itl-2008Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial, & Other Biometric Information Part 2: XML Version [ REF AN2K8 \h AN2K8]x-biometric/x-ansi-nist-itl-2011Information Technology: American National Standard for Information SystemsData Format for the Interchange of Fingerprint, Facial & Other Biometric Information [ REF AN2K11 \h AN2K11]x-biometric/x-cbeff-2010Common Biometric Exchange Formats Framework with Support for Additional Elements [ REF CBEFF2010 \h CBEFF2010]
ISO / Modality-Specific Formats
x-biometric/x-iso-19794-2-05Finger Minutiae Data [ REF BDIF205 \h BDIF205]x-biometric/x-iso-19794-3-06Finger Pattern Spectral Data [ REF BDIF306 \h BDIF306]x-biometric/x-iso-19794-4-05Finger Image Data [ REF BDIF405 \h BDIF405]x-biometric/x-iso-19794-5-05Face Image Data [ REF BDIF505 \h BDIF505]x-biometric/x-iso-19794-6-05Iris Image Data [ REF BDIF605 \h BDIF605]x-biometric/x-iso-19794-7-07Signature/Sign Time Series Data [BDIF707]x-biometric/x-iso-19794-8-06Finger Pattern Skeletal Data [ REF BDIF806 \h BDIF806]x-biometric/x-iso-19794-9-07Vascular Image Data [ REF BDIF907 \h BDIF907]x-biometric/x-iso-19794-10-07Hand Geometry Silhouette Data [ REF BDIF1007 \h BDIF1007]
XML Schema (Informative)
The XML Schema for WS-Biometric Devices is presented here for completeness and for the sake of convenience to the reader. The electronic version of this schema is authoritative can be located at HYPERLINK "http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0" http://docs.oasis-open.org/biometrics/ns/ws-bd-1.0
Security (Informative)
About
This section is an informative appendix that provides security control recommendations for systems that include the use of WS-Biometric Devices.
Security requirements are context and organizational dependent. However, by providing general guidance, the OASIS Biometrics TC hopes to provide a common baseline that can be used to help ensure interoperability among components that leverage WS-Biometric Devices. If the approach to security varies widely among WS-BD enabled components, there is significantly less chance that off-the-shelf products will interoperate. This appendix is not a comprehensive security standard. Therefore, updates to security guidance incorporated by reference should take precedence to any recommendation made here. In addition, security recommendations tend to be continuously updated, evolved, and improved; always seek the latest version of any of the referenced security specifications.
Further, the security controls described here are specific to the WS-Biometric Devices protocols and the components using it. It is assumed controls described here are only part of the overall security posture that a system comprises.
References
The following references are used in this Appendix and can provide more specific security guidance for the identified technology.
AbbreviationTechnologyCitation[802.1x]Port-based network access controlIEEE Standard 801.1X-2004, Institute of Electrical and Electronics Engineers, Standard for Local and metropolitan area networks, Port-Based Network Access Control, 2004.[FIPS 197]Advanced encryption standardFederal Information Process Standards Publication 197. Advanced Encryption Standard (AES). November 2001.[OSI]Network abstraction layersISO/IEC 74989-1:1994(E). Open Systems InterconnectBasic Reference Model: The Basic Model. [SP 800-38A]Block cipher modes of operationM. Dworkin. Recommendation for Block Cipher Modes of Operation: Methods and Techniques. NIST Special Publication 800-38A. December 2001.[SP 800-60]System sensitivity classificationsK. Stine, et al. Guide for Mapping Types of Information and Information Systems to Security Categories. NIST Special Publication 800-600, Volume 1, Revision 1. August 2008.[SP 800-52]Transport Layer Security (TLS)T. Polk, S. Chokhani, and K. McKay. DRAFT Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations. NIST Special Publication 800-52 Revision 1. September 2013.[SP 800-77]IPSECS. Frankel, K. Kent, R. Lewkowski, A. Orebaugh, R. Ritchey, S. Sharma. Guide to IPsec VPNs. NIST Special Publication 800-77. December 2005.[SP 800-97]Wireless network securityS. Frankel, B. Eydt, L. Owens, K. Scarfone. Establishing Wireless Robust Security Networks, A Guide to IEEE 802.11i. NIST Special Publication 800-97. February 2007.[SP 800-113]SSL VPNS. Frankel, P. Hoffman, A. Orebaugh, R. Park. Guide to SSL VPNs. NIST Special Publication 800-113. July 2008.Overview
WS-Biometric Devices components are only useful in the context of the system within which they participate. Therefore, recommended security controls are defined with respect to two orthogonal characteristics of those enclosing systems:
An overall sensitivity level of low (L), medium (M), or high (H) defines a set of recommended security controls. These levels roughly, but not directly, correspond to those defined in [ REF E_80060 \h SP 800-60]. The 800-60 level accompanies other information as inputs for determining the set of recommended controls specific for WS-BD. For the sake of disambiguation, L, M, or H will refer to a set of controls recommended by this appendix.
For each sensitivity level, a set of controls is recommended to be applied at a particular layer of abstraction. For each sensitivity level, recommendations are made for controls to be applied at the network, transport and/or application level. These levels roughly, but not directly, correspond to the network, transport, and application layers defined in the OSI model [ REF E_OSI \h OSI].
Control Set Determination
The following criteria are recommended for helping users and system owners in identifying a recommended set of security controls.
L Security Controls Criteria
The set of L controls are recommended if, for a given system, each of the following three clauses are true:
The system is used in a non-production environment or has an overall NIST SP 800-60 sensitivity of Low
All WS-Biometric Devices clients and servers reside within the same trusted network
The network that provides the WS-Biometric Devices interconnectivity network is completely isolated or otherwise security separated from untrusted networks with a strong buffer such as a comprehensive network firewall.
Examples that may qualify for L security controls are the use of WS-Biometric devices:
In product development, testing, or other research where no real biometric data is stored or captured
Across physical or logical components that are within an embedded device with other physical or logical controls that make it difficult to access or surreptitiously monitor the channels that carry WS-Biometric Devices traffic.
M Security Controls Criteria
The set of M controls are recommended if, for a given system, each of the following three clauses are true:
The system is used in a production environment or the system has an overall NIST SP 800-60 sensitivity of Medium
All WS-Biometric Devices clients and servers reside within the same trusted network
The systems network is either completely isolated or otherwise security separated from untrusted networks with a buffer such as a firewall.
Examples that may qualify for M security controls are the use of WS-Biometric devices:
In an identification enrollment station, where WS-Biometric Devices is used as a wire replacement for other less interoperable connectors. The WS-Biometric Devices network could be composed solely of the enrollment workstation and a biometric device with an Ethernet cable between them.
In a border screening application in which attended workstations in physically secure locations are used to submit biometrics to various law enforcement watch lists.
H Security Controls Criteria
The set of H controls are recommended if the overall system has an NIST SP 800-60 sensitivity of High or if WS-Biometric Devices is used across an untrusted network.
Recommended & Candidate Security Controls
The following table outlines the candidate & recommended security controls. Recommended security controls are likely to be relevant and beneficial for all systems of a particular category. Candidate controls are those that are likely to more application and implementation specific.
Candidate controls are marked with an asterisk (*). For example, in all L systems, any wireless networking should use WPA-2 Personal with 256-bit strength encryption (or better), and is therefore recommended. However, the use of TLS is a candidate since an L system might comprise a communications channel that is physically isolated or otherwise embedded in a system. In that case, foregoing TLS may be an acceptable tradeoff.
There may be a degree of redundancy among these controls; for example, multiple layers of encryption. However, using multiple layers of security also affords more granular policy enforcement. For example, IPSEC may allow the communications among one set of systems, but TLS client certificates would restrict WS-Biometric Devices communications to a particularly trustworthy subset.
Security Control SetLMHNetwork LayerWiredNone802.1x and/or IPSEC*IPSECWirelessWPA-2 Personal WPA-2 Enterprise WPA-2 EnterpriseTransport LayerTLS [ REF E_80052 \h SP 800-52]TLS [ REF E_80052 \h SP 800-52]TLS with client certificates [ REF E_80052 \h SP 800-52]Application LayerNoneBiometric payload encryption with AES [ REF E_FIPS197 \h FIPS 197]*Full payload encryption with AES [ REF E_FIPS197 \h FIPS 197]
L Security Controls
Network. No network security controls are recommended for wired networks. For wireless networks, WPA-2, personal or enterprise mode is recommended.
Transport. TLS as described in [ REF E_80052 \h SP 800-52]; the use of client certificates is optional.
Application. No application layer security control is recommended.
M Security Controls
Network. Networks should be secured with 802.1x [ REF E_8021x \h 802.1x] and/or IPSEC [ REF E_80077 \h Error! Reference source not found.].
Transport. TLS as described in [ REF E_80052 \h SP 800-52]; the use of client certificates is optional.
Application. All biometric data (the contents of a Results sensorData) should be encrypted with AES as described in [ REF E_FIPS197 \h FIPS 197] and [ REF E_80038A \h SP 800-38A].
H Security Controls
Network. Networks should be secured with an IPSEC [ REF E_SP80077 \h SP 800-77].
Transport. TLS with client certificates as described in [ REF E_80052 \h SP 800-52].
Application. All biometric data (the contents of a Results sensorData) should be encrypted with AES as described in [ REF E_FIPS197 \h FIPS 197] and [ REF E_80038A \h SP 800-38A].
Acknowledgments (Informative)
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants: MACROBUTTON
Almog Aley-Raz, Nuance
Mr. Jeremiah Bruce, US Department of Homeland Security
Mr. Doron Cohen, SafeNet, Inc.
Robin Cover, OASIS
Matthias de Haan, Tandent Vision Science, Inc
Mr. Francisco Diez-Jimeno, Carlos III University of Madrid
Dr. Jeff Dunne, Johns Hopkins University Applied Physics Laboratory
Mr. Chet Ensign, OASIS
Mr. Sander Fieten, Individual
Richard Friedhoff, Tandent Vision Science, Inc
Bob Gupta, Viometric, LLC
Emily Jay, NIST
Mr. Ken Kamakura, Fujitsu Limited
Mr. Kevin Mangold, NIST
Dr. Ross Micheals, NIST
Derek Northrope, Fujitsu Limited
Mr Tony Pham, Bank of America
Dr. Raul Sanchez-Reillo, Carlos III University of Madrid
Mrs. Dee Schur, OASIS
Mr. Jeffrey Shultz, US Department of Defense (DoD)
Casey Smith, Tandent Vision Science, Inc
Mr. Kevin Strickland, Tandent Vision Science, Inc
Cathy Tilton, Daon
Mr. Ryan Triplett, Booz Allen Hamilton
Ms. Maria Vachino, Johns Hopkins University Applied Physics Laboratory
Mr. Steven Venable, Lockheed Martin
Anne Wang, 3M HIS
Youngrock Yoon, Tandent Vision Science, Inc
Authors of initial NIST specification
Ross J. Micheals
Kevin Mangold
Matt Aronoff
Kristen Greene
Kayee Kwong
Karen Marshall
Acknowledgments listed in initial NIST specification
Biometric Standards Working Group, Department of Defense
Michael Albright, Vision and Security Technology Laboratory, University of Colorado at Colorado Springs
Senaka Balasuriya, SolidBase Consulting
Terrance Boult, Vision and Security Technology Laboratory, University of Colorado at Colorado Springs
Leslie Collica, Information Technology Laboratory, National Institute of Standards and Technology
Tod Companion, Science & Technology Directorate, Department of Homeland Security
Bert Coursey, Science & Technology Directorate, Department of Homeland Security
! " # A C D O P R S T U b h m n t v w - . / ; l q } Ĺ~tg h7 h1D 0J B* ph hY&