Invoke-BWSVerify
NAME
Invoke-BWSVerify
SYNOPSIS
Performs a one-to-one comparison of the given samples with a stored biometric template in order to verify that the
individual is the person he or she claims to be.
SYNTAX
Invoke-BWSVerify [-BWS] <string> [-Certificate] <X509Certificate> [-BCID] <string> [-Path] <string[]>
[-LiveFaceDetection <SwitchParameter>] [-LivePeriocularDetection <SwitchParameter>] [-AutoEnrollment
<SwitchParameter>] [<CommonParameters>]
Invoke-BWSVerify [-BWS] <string> [-Certificate] <X509Certificate> [-BCID] <string> [-Samples] <Sample[]>
[-LiveFaceDetection <SwitchParameter>] [-LivePeriocularDetection <SwitchParameter>] [-AutoEnrollment
<SwitchParameter>] [<CommonParameters>]
DESCRIPTION
A biometric verification tests the given samples against already stored samples (biometric template) of the given
class. When this test shows that the new samples belong to the class, the verification succeeds, otherwise it
fails.
This method supports live detection (currently only for the face and periocular trait). To activate live
detection, simply use the switch LiveFaceDetection or LivePeriocularDetection. Note that in this case the
verification will only succeed, when it can undoubtedly determine that the given data is live data. In case that
the live detection for the face trait succeeds, the degree of the head rotation between two subsequent images is
reported with the returned result.
Additionally, verification supports the AutoEnrollment switch that allows an automatic adaption of the template of
a user by sending (asynchrounously) the submitted samples to the enrollment operation in case that the
verification succeeds.
Internally this operation always performs a QualityCheck (in BioID ExtractTokenData mode) for all submitted
samples before they are forwarded to the live detection - in case a live-detection flag is set - and finally the
verification is performed. Therefore you might get results from these operations as well together with the
verification results.
PARAMETERS
-BWS <string>
Specifies the BioID Web Service (BWS) installation where the command shall be executed. You can simply use the
hostname like 'bws.bioid.com' or the entire URL, e.g. 'https://bws.bioid.com/BioIDWebService.svc'. If scheme
and/or path are not given, the defaults (https, BioIDWebService.svc) are used.
Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Certificate <X509Certificate>
Specifies the client certificate that is used to authenticate the BWS client. Enter a variable that contains a
certificate or a command or expression that gets the certificate.
To find a certificate, use Get-PfxCertificate or use the Get-ChildItem cmdlet in the Certificate (Cert:)
drive. For example:
get-childitem -path Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
If the certificate is not valid or does not have sufficient authority, the command fails.
Required? true
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
-BCID <string>
The Biometric ClassID (BCID) identifies a class within the BWS. A class is an anonymous entity representing
all the biometric data associated with a single individual.
The BCID is a combination of a string, a partition id and the class id itself. The string specifies the
Storage, e.g. the Windows Azure Storage Service to use, whereas the partition and class id is used within this
storage to address the class.
Required? true
Position? 3
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Path <string[]>
A list of files containing the samples to be uploaded to BWS and used for the verification. Files with the
extension .wav are assumed to be voice-samples, all others files are assigned to the face trait.
Required? true
Position? 4
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? true
-Samples <BioID.Cmdlets.BWS.Sample[]>
The array of samples that shall be uploaded to the BWS and used for the verification. You can use BWS samples
instead of files in case you explicitely need to specify the trait of the sample or have to add a tag to the
sample.
To create a sample array from a file-path you can use a command like:
$samples =
@([BioID.Cmdlets.BWS.Sample]@{Data=[System.IO.File]::ReadAllBytes(path);Trait="Periocular";Tag="something"})
Required? true
Position? 4
Default value
Accept pipeline input? false
Accept wildcard characters? false
-LiveFaceDetection [<SwitchParameter>]
Enables live face detection. In this case the operation typically fails, as soon as it cannot undoubtedly
determine that the given data is live data.
Required? false
Position? named
Default value No live face detection.
Accept pipeline input? false
Accept wildcard characters? false
-LivePeriocularDetection [<SwitchParameter>]
Enables live periocular detection. In this case the operation typically fails, as soon as it cannot
undoubtedly determine that the given data is live data.
Required? false
Position? named
Default value No live periocular detection.
Accept pipeline input? false
Accept wildcard characters? false
-AutoEnrollment [<SwitchParameter>]
Enables automatic enrollment with the verification opreration: in case a verification succeeds, the uploaded
samples are automatically enrolled. This ensures that the biometric template of the person is automatically
adapted and always "up-to-date".
Required? false
Position? named
Default value No automatic enrollment.
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
System.String[]
You can pipe sample files to Invoke-BWSVerify.
OUTPUTS
BioID.Cmdlets.JobResult
Returns an object containing the results of the verification. The object contains information about the
performed "Command", a unique "JobID", whether the operation "Succeeded" and a list of operation specific
"Errors". It also contains information about the "Samples" that have been received by the operation, including
sample specific "Errors" that might have occurred.
NOTES
Enrollment
To successfully perform a verification, the specified class needs to be enrolled already. Use the
Invoke-BWSEnroll cmdlet to perform an enrollment. If you don't need a class any more, you can delete it using
the Invoke-BWSDeleteClass cmdlet.
-------------------------- EXAMPLE 1 --------------------------
$cert = get-childitem -path Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
Invoke-BWSVerify -BWS bws.bioid.com/BioIDWebService.svc -Certificate $cert -BCID bws.123.12345 -Path
c:\samples\image1.png, c:\samples\image2.png
Performs a verification of the class bws.123.12345 using the two images supplied. As the Path allows wildcard
characters, the following command uses at least the same sample files as above and additionally performs a live
detection:
$result = Invoke-BWSVerify bws.bioid.com $cert bws.113.12345 c:\samples\image*.png -lfd
-------------------------- EXAMPLE 2 --------------------------
$cert = gci Cert:\CurrentUser\My\1234567890ABCDEF1234567890ABCDEF12345678
$samples = @(
[BioID.Cmdlets.BWS.Sample]@{
Data=[System.IO.File]::ReadAllBytes("c:\samples\image1.png");
Trait="Face"},
[BioID.Cmdlets.BWS.Sample]@{
Data=[System.IO.File]::ReadAllBytes("c:\samples\image2.png");
Trait="Periocular"},
[BioID.Cmdlets.BWS.Sample]@{
Data=[System.IO.File]::ReadAllBytes("c:\samples\audio1.wav");
Trait="Voice"})
Invoke-BWSVerify bws.bioid.com $cert bws.123.12345 $samples
Performs a verification of the class bws.123.12345 using the three samples supplied.
RELATED LINKS
BWS Verification API
BioID Web Service reference