DigitalPersona, Inc. Altus AUTH SDK. Version 1.1. Developer Guide

(1)

DigitalPersona, Inc.

Altus AUTH SDK

Version 1.1

(2)

DigitalPersona, Inc.

All intellectual property rights in the DigitalPersona software, firmware, hardware and documentation included with or described in this guide are owned by DigitalPersona or its suppliers and are protected by United States copyright laws, other applicable copyright laws, and international treaty provisions. DigitalPersona and its suppliers retain all rights not expressly granted.

U.are.U® and DigitalPersona® are trademarks of DigitalPersona, Inc. registered in the United States and other countries. Windows, Windows Server 2003/2008, Windows Vista and Windows 7 are registered trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners.

This DigitalPersona Altus AUTH SDK Developer Guide and the software it describes are furnished under license as set forth in the “License Agreement”.

Except as permitted by such license, no part of this document may be reproduced, stored, transmitted and translated, in any form and by any means, without the prior written consent of DigitalPersona. The contents of this manual are furnished for informational use only and are subject to change without notice.

Any mention of third-party companies and products is for demonstration purposes only and constitutes neither an endorsement nor a recommendation. DigitalPersona assumes no responsibility with regard to the performance or use of these third-party products.

DigitalPersona makes every effort to ensure the accuracy of its documentation and assumes no responsibility or liability for any errors or inaccuracies that may appear in it.

Technical Support

The DigitalPersona web site provides online technical support at http://www.digitalpersona.com/support. You can also access our free support forum at any time at http://www.digitalpersona.com/webforums.

Feedback

Although the information in this guide has been thoroughly reviewed and tested, we welcome your feedback on any errors, omissions, or suggestions for future improvements. Please contact us at

Crossmatch

720 Bay Road, Suite 100 Redwood City, California 94063 USA

(3)

1 Introduction . . . 4

Target Audience . . . 5 Chapter Overview . . . 5 Additional Resources . . . 6 Related Documentation . . . 6 Online Resources . . . 6 System Requirements . . . 6 Development system . . . 6 Target system . . . 6

Supported DigitalPersona Products . . . 7

2 Installation . . . 8

Preparing the Altus Server . . . 8

Install Altus Confirm . . . 8

Add Internet Information Services . . . 9

Import or create an SSL Certificate . . . 17

Set https binding . . . 17

Install Client Workstation . . . 18

3 Using the SDK . . . 19

Workflow . . . 19

Authentication Policies . . . 20

Functions . . . 20

The Sample Application . . . 21

4 Custom Authentication Policies . . . 24

How an Authentication Policy is Represented . . . 24

Extending an Authentication Policy . . . 26

(4)

(5)

Introduction

1

The DigitalPersona Pro Authentication SDK is a component of Altus Confirm, and one piece of the three-part Altus framework that delivers identity assurance through a strong multi-factor authentication client and server.

The purpose of the DigitalPersona Pro Authentication SDK is to allow you to add authentication to your C++ applications. The Pro Authentication SDK lets you authenticate DigitalPersona Altus users quickly and easily using the authentication policy defined (outside of the SDK) by the Altus administrator and subsequently release their protected data (secrets). All of the authentication methods provided in the Altus solution (password, fingerprint recognition, smart cards, etc.) can be accessed through the SDK.

The DigitalPersona Altus AUTH SDK provides authentication and identification only. User enrollment must be handled through an Altus client.

When you install DigitalPersona Altus Workstation or Kiosk, the DigitalPersona Altus AUTH SDK runtime is installed as well. As shown in the diagram below, your application runs on workstations that are also running one of the Altus clients.

The SDK can be used for the following:

 Authenticating users with the authentication policy and user interface used by DigitalPersona Altus Workstation/Kiosk and optionally reading a user secret.

(6)

Chapter 1: Introduction Target Audience

required by the authentication policy set by the Pro administrator. On successful authentication, DPAlAuthenticate can optionally return user secrets to the application.

 Identifying users by searching in the Altus database to find the user and authenticate them.

 The DPAlIdentAuthenticate function displays the multi-factor identification dialog and identifies the user based on the credentials supplied. The customizable dialog box allows the user to provide the credentials required by the current authentication policy. If the identification succeeds, DPAlIdentAuthenticate can optionally return the user name and secret to the application.

 Retrieving and saving user secrets. Secrets are cryptographically protected and are released to an application only after successful authentication of the user. Secrets are stored in the Altus database and roam with the rest of the user data.

 Implementing custom authentication policies which extend the Altus administrator’s policies or create

new policies.

DigitalPersona Altus AUTH SDK observes all of the settings in Altus regarding its communications with the server, supported credentials, policies, etc.

For advanced users, your application can require additional credentials (i.e., you can create a custom

authentication policy), but if secret release is required, your application’s must meet the requirements of the policy set by the Altus administrator.

Target Audience

This guide is for developers who have a working knowledge of the C++ programming language. In addition, readers must have an understanding of the DigitalPersona Altus product and its authentication terminology and concepts.

Chapter Overview

Chapter 1, Introduction (this chapter), describes the audience for which this guide is written; cites a number of

resources that may assist you in using the Pro Authentication SDK; identifies the minimum system

requirements needed to run the Pro Authentication SDK; and lists the DigitalPersona products supported by the Pro Authentication SDK.

Chapter 2, Installation, contains instructions for installing the SDK on your development system.

Chapter 3, Using the SDK, describes typical workflow and describes the functions in the API and how to run the sample application.

(7)

Chapter 1: Introduction Additional Resources

Additional Resources

You can refer to the resources in this section to assist you in using the Pro Authentication SDK.

Online Resources

System Requirements

Development system

This section lists the minimum software and hardware requirements needed to develop applications with the Pro Authentication SDK.

 Development system running Windows 7 or higher

 To run the sample code and test applications: DigitalPersona Altus Workstation or Kiosk (see Supported

DigitalPersona Products below for a complete list of compatible clients)  To compile sample code: Visual Studio 2008 or higher

Target system

Any Windows-based (Windows 7 or higher) workstation that has any Altus client installed. See Supported

DigitalPersona Products below for a complete list of compatible clients.

 Note that if the logon and Password Manager applications are not needed, Altus can be installed on client

workstations without applications. This installs the Pro Authentication SDK runtime only.

Subject Document

Concepts and terminology for DigitalPersona Altus DigitalPersona Altus Administrator Guide and the DigitalPersona Altus AD Administrator Guide

(available at http://www.digitalpersona.com/support/ reference-material/pro-reference-material/)

Web Site name URL

DigitalPersona Developer Connection Forum for DigitalPersona Developers

http://devportal.digitalpersona.com/

(Requires free registration.)

(8)

Chapter 1: Introduction Supported DigitalPersona Products

Supported DigitalPersona Products

The Pro Authentication SDK is compatible with the following DigitalPersona products:

 Altus and Altus AD Server 1.1 and higher.  Altus and Altus AD Workstation 1.1 and higher.

 Altus and Altus AD Kiosk 1.1 and higher.

(9)

Installation

2

The DigitalPersona Altus AUTH SDK is automatically installed as part of these Altus clients:

 Altus Workstation

 Altus Kiosk

 Altus AD Workstation

 Altus AD Kiosk

This documentation, sample code (for C++ and .NET), and any necessary includes are available in a separate Altus SDK package available from Crossmatch and your channel partner or reseller.

Preparing the Altus Server

SInce Altus is a client-server solution, use of the SDK requires installation of an Altus or Altus AD Server and client, plus additional steps on the server to prepare it for use with the SDK.

The necessary steps for installation and setup of the DigitalPersona Altus AUTH SDK are summarized below.

 Install Altus Confirm (begins below), and

 Add or configure Internet Information Services (IIS) (page 9)

 Import or create an SSL Certificate (page 17)

 Set https binding (page 17)

 Install Client Workstation (page 18)

Install Altus Confirm

To install Altus Confirm

1. Locate the Altus Confirm folder within the Altus SDK package. 2. Launch the Altus Confirm installer by clicking the Setup.exe file. 3. Follow the instructions provided in the installation wizard.

(10)

Chapter 2: Installation Add Internet Information Services

Add Internet Information Services

Use of the Altus AUTH SDK requires installation of the Internet Information Services role on the Windows Server, and configuration of specific IIS-related features in IIS Manager.

If you need to install IIS yourself, you should install it prior to installing Altus Confirm, since Altus Confirm will ensure that the proper features have been configured.

However, when installing outside of the Altus COnfirm installer, use the following instructions to ensure that the necessary features have been installed.

Installations on Windows Server 2008 and Windows Server 2012 are slightly different, so steps are shown below for both operating systems.

Ensure that you have administrative user rights on the computer on which you plan to install IIS. Note that by default, you do not have administrative user rights if you are logged on as a user other than as the built-in administrator, even if you were added to the local Administrators group on the computer.

Add IIS role and features (Windows Server 2012)

These instructions are for installing IIS on Windows Server 2012. For installation on Windows 2008 R2, see page13. If IIS has not been installed on the same machine as your Altus Server, follow the instructions below to do so.

(11)

2. On the Select installation type page, choose “Role-based or feature-based installation” and click “Next.”

(12)

4. On the Select Server Roles page, scroll down to and select, “Web Server (IIS).” When asked to add additional features required for IIS, click Add Features.

5. On the Select Features page, select at least the features shown in the next illustration. Specifically, note that both the 3.5 and 4.5 .NET Frameworks must be selected. Under .NET Frameworks 4.5, ensure that the sub-feature “WCF Services\HTTP Activation” is selected. When asked to add sub-features required for HTTP Activation, click Add Features. Then click Next.

(13)

7. On the Select role services page, in addition to the default settings, make sure that the settings shown in the following two images are selected. Then click Next. When asked to add features required for IIS

MAnagement Console, click Add Features.

(14)

Add IIS role and features (Windows Server 2008)

These instructions are for installing IIS on Windows Server 2008 R2. For installation on Windows 2012, see page9.

If IIS has not been installed on the same machine as your Altus Server, follow the instructions below to do so. 1. Open the “Server Manager” and choose to add a Role by selecting “Roles” in the left panel and then “Add

Roles” in the right panel.

2. On the Select Server Roles page, choose “Web Server (IIS).”

(15)

4. Back on the Select Server Roles page, click “Next”. A page displays containing an Introduction to IIS. Click “Next.”

(16)

(17)

7. Back on the Select Roles Services page, click “Next”. Then, on the Confirm Installation Selections page, click “Install” to begin the installation process. Once the installation is complete you should see a page that looks like the following illustration.

(18)

Chapter 2: Installation Import or create an SSL Certificate

Import or create an SSL Certificate

You will need an SSL Certificate to bind to the HTTPS protocol. You may already have one on your machine, in which case you can skip to the next topic, Set https binding on page 17.

Import SSL Certificate

If you have an SSL Certificate in the pfx format, you can import it to use with Altus. 1. Open the Windows Control panel and select Administrative Tools.

2. Launch the Internet Information Services (IIS) Manager.

3. You may be asked if you want to get started with Microsoft Web Platform. Click No.

4. In the left Connections panel of IIS Manager, select the <computer name> Home. Then double-click Server

Certificates.

5. In the right Actions panel, click Import. Navigate to the .pfx file, enter the password for the file and from the Select Certificate Store dropdown list, select Web Hosting.

6. Click OK.

Create a self-signed SSL Certificate

1. Open the Windows Control panel and select Administrative Tools. 2. Launch the Internet Information Services (IIS) Manager.

3. In the left Connections panel of IIS Manager, select the <computer name> Home. Then double-click Server

Certificates.

4. In the right Actions panel, click Create Self-Signed Certificate. 5. Specify a friendly name for the certificate.

6. (IIS 2012 only) From the Select Certificate Store dropdown list, select Web Hosting. 7. Click OK.

Set https binding

1. Open the Windows Control panel and select Administrative Tools. 2. Launch the Internet Information Services (IIS) Manager.

3. In the left Connections panel of IIS Manager, select the Default Web Site. 4. In the right Actions panel, click Bindings.

5. In the Site Bindings dialog, click Add. 6. In the Add Site Bindings dialog,

(19)

Chapter 2: Installation Install Client Workstation

8. Select your certificate from the SSL Certificate dropdown list. 9. Click OK.

Install Client Workstation

To run the Altus sample code or to run and test your application, you should have Altus Workstation or Altus AD Workstation installed on your development machine.

Additionally, if you are developing for an Altus Kiosk or Altus AD Kiosk environment, you should test your application with those clients. For a list of supported versions of Altus clients, refer to Supported DigitalPersona

Products on page 7. Complete instructions on installing Altus clients is provided in the Altus Client Guide, which

(20)

Using the SDK

3

This chapter describes the standard workflow for using the Altus AUTH SDK API and lists the functions provided. The information in this chapter is extracted from DPAltusAuthSdkApi.h.

For terminology and concepts, see the DigitalPersona Altus or Altus AD Administrator Guide.

Workflow

The normal process is: call DPAlInit to initialize ...

call functions in the SDK

if an SDK function returned an array, string or BLOG, call DPAlFreeBuffer to release the memory

...

call DPAlTerm to release resources

Note that if you are calling only one function in the SDK, then you don’t need to call DPAlInit and

DPAlTerm directly because the function will initialize and terminate for itself automatically. However when you are making multiple calls, it is faster and more efficient to initialize and terminate directly.

The SDK provides:

1. Authentication: Verifying that a user is who they claim to be by checking that the provided credentials (password, fingerprint, etc.) match their username's credentials in the Altus database.

The DPAlAuthenticate function displays the multi-factor authentication dialog and matches the supplied credentials against the user's enrolled credentials. The customizable dialog box accepts the credentials required by the authentication policy set by the Altus administrator.

Optional: On successful authentication, DPAlAuthenticate can return user secrets and the type of credential(s) that the user provided for authentication.

2. Identification: Searching in Active Directory to find the user and authenticate them. For Kiosk environments only.

The DPAlIdentAuthenticate function displays the multi-factor identification dialog and identifies the user based on the credentials supplied. The customizable dialog box allows the user to provide the credentials required by the current authentication policy.

(21)

Chapter 3: Using the SDK Authentication Policies

Authentication Policies

The simplest option provided by Altus AUTH SDK is to authenticate a user using the session authentication policy defined by the Altus administrator. In this case, you do not need to know how policies work and you may simply pass NULLs to the SDK for all parameters that take an authentication policy.

For more information on authentication policies, see Chapter 4, Custom Authentication Policies, on page 24.

Functions

This section lists the Pro Authentication API functions. For a detailed description of each function’s parameters, consult the header file DPAlAuthSdkApi.h.

Function Description

DPAlInit Initialize the authentication functions.

Calling this function is optional -- if you do not call it, the system will initialize itself. However if you are going to call multiple authentication functions, it is more efficient and provides better performance if you initialize and terminate explicitly.

DPAlTerm Terminate the authentication process, release resources.

You must call DPAlTerm once for each time that you called DPAlInit. DPAlAuthentication Display multi-factor authentication dialog and authenticate a user. Optionally

return the type of credentials used to authenticate and/or a secret upon successful authentication.

Note that this function performs a 1-to-1 comparison -- matching a user’s credentials against their enrolled credentials in the Altus database.

DPAlIdentAuthenticate For Kiosk environments only. Display multi-factor identification dialog and

identify a user. Optionally return the username, the type of credential(s) used to authenticate and/or user secret(s) upon successful identification.

Note that this function performs a 1-to-many comparison -- searching Active Directory to find the user -- and then authenticates the user.

DPAlReadAuthPolicy Read an authentication policy.

DPAlWriteSecret Save the requested secret (authenticated users only).

DPPTDoesSecretExist Check to see if a secret exists.

DPAlBufferFree Release memory buffer allocated by the other functions in the SDK.

(22)

Chapter 3: Using the SDK The Sample Application

The Sample Application

The sample application source code is provided in the folder UsingAltusSDK (including the Visual Studio 2008 project) from the Altus SDK package.

There are two sets of sample code. One for C++ and one for .NET.

The sample application displays a set of buttons that demonstrate a variety of tasks that you might perform with the Altus AUTH SDK, such as Authentication, Identification, Working with Secrets and Custom Authentication Policies. When you run the sample application, the main screen looks like one of the images below.

The source code header file, DPAltusAuthSdkApi.h, includes detailed comments describing what each button does.

(23)

.NET Sample UI

(24)

For example, to authenticate a user, click on the Authenticate the currently logged on user button. A standard Altus dialog box will appear, similar to the one shown below. The actual dialog box will vary depending on your environment and the Altus client that you have installed.

You can authenticate with any method that you have set up. After you authenticate, the result of the operation will appear in the main screen of the sample program as shown below, in this case the message

(25)

Custom Authentication Policies

4

This chapter describes how to work with authentication policies. This material is for advanced developers only. Technical support queries regarding custom authentication policies should be sent to

[email protected] rather than the usual DigitalPersona technical support.

If you need Altus to authenticate users and return user secrets, then you will need to satisfy the authentication policy defined by the Altus administrator. You can also choose to define your own custom authentication policy but if you do, your custom policy may not be sufficient for secret release. Altus will not release secrets unless you

satisfy the authentication policy defined by the Altus administrator.

The Altus administrator must define the authentication policy or policies. Some examples of authentication policies might be:

 Users can authenticate with either a fingerprint or a password but we don’t need both fingerprint AND password.

 Users can authenticate with password OR with a smartcard; if they use their smartcard, then they must also enter their PIN.

Consult the DigitalPersona Altus or Altus AD Administrator Guide (available at http://www.digitalpersona.com/ support/reference-material/pro-reference-material/) for more information on policies.

NOTE: An authentication policy is defined for a user on a specified workstation. Users may have different policies, and a policy for one user may not work if you try to use it to retrieve a secret for another user.

How an Authentication Policy is Represented

An authentication policy is represented by an array of credential masks.

To create a data representation of the Altus administrator’s authentication policy, we make a list of all credentials or credential combinations that are permitted. Then we create a credential mask for each valid credential or combination. Each mask has a bit set for every credential that is required in this combination. As long as the user supplies one valid combination of credentials (i.e., satisfies at least one credential mask) they will be authenticated.

(26)

Chapter 4: Custom Authentication Policies How an Authentication Policy is Represented

The simplest authentication policy consists of a single (binary) credential mask:

0000000000000000000000000000000000000000000000000000000000000001 which represents a policy that requires users to provide a password (the password bit is set).

As another example, if the authentication policy requires BOTH a password and fingerprint, the authentication policy would consist of this credential mask (password and fingerprint bits both set):

0000000000000000000000000000000000000000000000000000000000000011

If the user can authenticate either with a password OR a fingerprint, the authentication policy would consist of an array containing the following two credential masks. The first credential mask has the bit set for password access and the second mask has the bit set for fingerprint access. As long as a user satisfies ONE of these credentials masks, the user will be authenticated.

0000000000000000000000000000000000000000000000000000000000000001 0000000000000000000000000000000000000000000000000000000000000010 As another example, the policy below shows the two credential masks for the authentication policy that requires users to authenticate by providing both their fingerprint and their password OR by providing their smartcard.

0000000000000000000000000000000000000000000000000000000000000011 0000000000000000000000000000000000000000000000000000000000000100

A fairly typical default authentication policy is shown below. This policy allows the user to use ANY one of: password, fingerprint, or smart card.

(27)

Chapter 4: Custom Authentication Policies Extending an Authentication Policy

0000000000000000000000000000000000000000000000000000000000000010 0000000000000000000000000000000000000000000000000000000000000100 The order of credential masks within the Policy array is unimportant. The bits that correspond to each

credential type are consistent for all credential masks (i.e., bit 0 always represents that a password is required).

Extending an Authentication Policy

If you want to extend the Altus administrator’s authentication policy, you can read the current policy by calling DPAlReadAuthPolicy. You can then modify the credentials masks or add new credentials masks to the authentication policy array. You can then pass your authentication policy to calls to DPAlAuthenticate or DPAlIdentAuthenticate and your authentication policy will be used instead of the policy defined by the Altus administrator.

As a best practice, we recommend that this feature only be used to make the Altus administrator’s

authentication policy more strict. Altus will not release secrets if your policy is less stringent than the existing Altus

authentication policy.

For example, consider the case where the existing Altus authentication policy is to allow fingerprints or passwords. In that case, the authentication policy would consist of these two credential masks:

0000000000000000000000000000000000000000000000000000000000000001 0000000000000000000000000000000000000000000000000000000000000010

If you require that users also use face recognition in addition to either a fingerprint or password, you would update the authentication policy’s credential masks to this:

0000000000000000000000000000000000000000000000000000000000010001 0000000000000000000000000000000000000000000000000000000000010010 In this case, Altus will release secrets because the policy is stricter than the original.

However if you update the authentication policy to allow a different kind of credential entirely (for example, by adding a new credential mask that allows smart cards), then Altus will not release secret data.

Creating a New Authentication Policy

You can also create your own custom policy. To do this, simply create the appropriate credentials masks and pass your authentication policy to DPAlAuthenticate or DPAlIdentAuthenticate.

(28)

Index

A

additional resources 6 online resources 6 related documentation 6 audience for this guide 5

C

chapters, overview of 5

D

DigitalPersona Developer Connection Forum, URL to 6 documentation, related 6 O online resources 6 overview of chapters 5 R requirements, system

See system requirements

resources, additional

See additional resources

resources, online

See online resources

S

system requirements 6

T

target audience for this guide 5

U

updates for DigitalPersona software products, URL for downloading 6

URL

DigitalPersona Developer Connection Forum 6 Updates for DigitalPersona Software Products 6

W

Web site

DigitalPersona, Inc. Altus AUTH SDK. Version 1.1. Developer Guide