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