Integration Guide

RSA Adaptive Authentication
(On-Premise) 7.1
Integration Guide
Contact Information
Go to the RSA corporate website for regional Customer Support telephone and fax numbers:
www.emc.com/domains/rsa/index.htm
Trademarks
RSA, the RSA Logo, BSAFE and EMC are either registered trademarks or trademarks of EMC Corporation in the United
States and/or other countries. All other trademarks used herein are the property of their respective owners. For a list of EMC
trademarks, go to www.emc.com/legal/emc-corporation-trademarks.htm#rsa.
License agreement
This software and the associated documentation are proprietary and confidential to EMC, are furnished under license, and
may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice
below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any
other person.
No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any
unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability.
This software is subject to change without notice and should not be construed as a commitment by EMC.
Note on encryption technologies
This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption
technologies, and current use, import, and export regulations should be followed when using, importing or exporting this
product.
Distribution
Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change
without notice.
THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO
REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS
PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Copyright 2013 EMC Corporation. All Rights Reserved. Published in the USA.
July 2013
RSA Adaptive Authentication (On-Premise) 7.1 Integration Guide
Contents
Preface................................................................................................................................... 3
About This Guide................................................................................................................ 3
RSA Adaptive Authentication (On-Premise) Documentation ............................................ 3
Support and Service ............................................................................................................ 4
Before You Call Customer Support............................................................................. 4
Chapter 1: Encryption System ............................................................................... 5

Database and Persistence Encryption ................................................................................. 5
Encryption Algorithms........................................................................................................ 5
Key Creation and Storage ................................................................................................... 5
Chapter 2: Reverse HTTP Proxy in the DMZ .................................................. 7

Reverse HTTP Proxy Server............................................................................................... 7
Reasons for Using a Reverse Proxy............................................................................. 7
Chapter 3: Validating User Data ............................................................................ 9

Validating User Input.......................................................................................................... 9
Profanity....................................................................................................................... 9
SQL Injection............................................................................................................. 10
XML Injection ........................................................................................................... 10
Special Characters...................................................................................................... 10
Scripting Patterns ....................................................................................................... 10
Additional Data Validation Guidelines..............................................................................11
Chapter 4: Device Information Collection ..................................................... 13

Device Information ........................................................................................................... 13
HTTP Headers ........................................................................................................... 13
Source IP Address...................................................................................................... 14
Device Print ............................................................................................................... 14
Mobile Device Information ....................................................................................... 14
User-Defined Credentials .......................................................................................... 15
Device Token ............................................................................................................. 15
Device Token Theft Detection................................................................................... 18
Collection of Device Information ..................................................................................... 18
Collection of Device Print Information During Logon ............................................. 19
Collection of Device Print Information During Enrollment ...................................... 20
Collection of Device Print Information During Transaction Authentication ............ 21
Collection of Information Using the Mobile SDK - Adaptive Authentication Module
22
Scripts for Collection of Device Print Information ................................................... 23
Retrieval of the Device Token ................................................................................... 24
Information Sent to Web Services .................................................................................... 30
Overview of the Setting of Device Print Information....................................................... 31
Device Print Information Set During Enrollment...................................................... 32
Contents 1
Device Print Information Set After a Successful Challenge...................................... 33

Device Print Information Set During Transaction Authentication ............................ 34
Setting Device Print Information ...................................................................................... 35
Place the PMData Cookie .......................................................................................... 35
Place the Flash Shared Object Token ........................................................................ 35
Chapter 5: Information Collection ...................................................................... 39

Trojan Protection Solution ................................................................................................ 39
HTML Injection Protection ....................................................................................... 39
Man vs. Machine Detection ....................................................................................... 43
Proxy Attack Protection............................................................................................. 47
Mobile Location Awareness ............................................................................................. 48
Overview of Information Collection for Mobile Location Awareness...................... 49
Script for Collection of Mobile Location Awareness Information............................ 49
Mobile Location Awareness Function Names........................................................... 50
Collect Information for Mobile Location Awareness................................................ 52
2 Contents
Preface
About This Guide

This guide introduces the procedures required to integrate RSA Adaptive
Authentication (On-Premise) 7.1 with existing applications. This guide is intended for
system administrators, security analysts, and other trusted personnel. Do not make this
guide available to the general user population.
RSA Adaptive Authentication (On-Premise) Documentation

For more information about RSA Adaptive Authentication (On-Premise), see the
following documentation:
Authentication Plug-In Developers Guide. Describes the Authentication Plug-In
development process that enables external authentication providers to integrate
their products with RSA Adaptive Authentication (On-Premise).
Back Office Users Guide. Provides an overview of the following Back Office
applications: Policy Management, Case Management, Access Management,
Customer Service Administration, and the Report Viewer.
Bait Credentials Setup and Implementation Guide. Describes how to set up and
implement RSA bait credentials, which help provide you with accelerated fraud
detection and prevention capabilities.
Best Practices for Challenge Questions. Describes the best practices related to
challenge questions that RSA has evolved through experience at multiple
deployments.
Installation and Upgrade Guide. Describes detailed procedures on how to install,
upgrade, and configure RSA Adaptive Authentication (On-Premise).
Integration Guide. Describes how to integrate and deploy RSA Adaptive
Authentication (On-Premise).
Operations Guide. Provides information on how to administer and operate
RSA Adaptive Authentication (On-Premise) after upgrade. This guide also
describes how to configure Adaptive Authentication (On-Premise) within the
Configuration Framework.
Performance Guide. Provides information about performance testing and
performance test results for the current release version of RSA Adaptive
Authentication (On-Premise).
Product Overview Guide. Provides a high-level overview of RSA Adaptive
Authentication (On-Premise), including system architecture.
Preface 3
Release Notes. Provides information about what is new and changed in this
release, as well as workarounds for known issues. It also includes the supported
platforms and work environments for platform certifications. The latest version of
the Release Notes is available on RSA SecurCare Online at
https://knowledge.rsasecurity.com.
Security Best Practices Guide. Provides recommendations for configuring your
network and RSA Adaptive Authentication (On-Premise) securely.
Web Services API Reference Guide. Describes RSA Adaptive Authentication
(On-Premise) web services API methods and parameters. This guide also
describes how to build your own web services clients and applications using web
services API to integrate and utilize the capabilities of Adaptive Authentication
(On-Premise).
Whats New. Highlights new features and enhancements in RSA Adaptive
Authentication (On-Premise) 7.1.
Workflows and Processes Guide. Describes the workflows and processes that
allow end users to interact with your system and that allow your system to interact
with RSA Adaptive Authentication (On-Premise).
Support and Service

RSA SecurCare Online https://knowledge.rsasecurity.com
Customer Support Information www.emc.com/support/rsa/index.htm
RSA Solution Gallery https://gallery.emc.com/community/marketplace/rsa?

view=overview
RSA SecurCare Online offers a knowledgebase that contains answers to common

questions and solutions to known problems. It also offers information on new releases,
important technical news, and software downloads.
The RSA Solution Gallery provides information about third-party hardware and
software products that have been certified to work with RSA products. The gallery
includes Secured by RSA Implementation Guides with step-by-step instructions and
other information about interoperation of RSA products with these third-party
products.
Before You Call Customer Support

Make sure that you have direct access to the computer running the RSA Adaptive
Authentication (On-Premise) software.
Please have the following information available when you call:
Your RSA Customer/License ID.
Adaptive Authentication (On-Premise) software version number.
The make and model of the machine on which the problem occurs.
The name and version of the operating system under which the problem occurs.
4 Preface
1 Encryption System
The RSA Adaptive Authentication (On-Premise) system makes extensive use of
encryption for internal operations with other systems, such as online systems. This
chapter describes where and how encryption is used in the Adaptive Authentication
(On-Premise) system.
Database and Persistence Encryption

You must encrypt any sensitive data that is stored in the database or the file system.
The only persistent data encrypted by the Adaptive Authentication (On-Premise)
system are the keys themselves. These keys are used for encrypting internal and
customer messages, user phrases, and secret answers.
Encryption Algorithms
RSA Adaptive Authentication (On-Premise) complies with FIPS 140-2 Level 1 and
uses RSA BSAFE 4.1. For details about FIPS 140-2 compliance, see the
RSA BSAFE Crypto-J 4.1 Security Policy at
http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1291.pdf.
Key Creation and Storage

The key creation and storage mechanisms are different for each type of application
use:
Internal Token Keys. Keys for internal token encryption are generated within the
Adaptive Authentication system and are only applicable to device tokens.
Key seed data is generated using the Java SecureRandom class, seeded with time
stamp and key name bits. This key seed data is stored in a named record in the
MSG_CODE_KEY table. At runtime, the actual key is constructed from the key
seed using a fixed transformation of hashes.
Internal token keys are periodically regenerated, also known as key rolling, on a
regular basis. You can configure the key regeneration interval using the
field-configurable setting KEY_LIFETIME_IN_DAYS. The default value for key
regeneration is seven days.
Consequently, there may be multiple keys that are used, depending on the device
token that is submitted by the user device. The correct key is selected based on the
device token.
1: Encryption System 5
Persistence Keys. When the Adaptive Authentication system is first used, a new
entry is created in the MSG_CODE_KEY table with the initial key name. There is
never any externalized storage of persistent keys on the file system or in the
database, except in the compiled Java code.
6 1: Encryption System
2 Reverse HTTP Proxy in the DMZ

As a security application server, the contents of the RSA Adaptive Authentication
(On-Premise) system must be protected. RSA recommends that you locate the
Adaptive Authentication server behind one of the most secure segments of the
firewall, in a location not open to network traffic directly from the Internet.
To accommodate this recommended configuration, use a device or software agent in
the web DMZ, defined as the least protected network segment behind the fire wall,
as a reverse proxy.
Reverse HTTP Proxy Server

A proxy is a device that breaks the connection between a sender and a receiver. It
functions as a relay between the client and the server. The type of proxy server
discussed in this guide is a reverse HTTP proxy server.
This device is intended to reside near the web or application server. It performs its
proxy functions at the HTTP application layer, unlike other simpler devices that
perform proxy functions only at the IP layer.
Reasons for Using a Reverse Proxy

The main reasons for using a reverse proxy are that the reverse proxy:
Allows the RSA application server to reside in a more protected zone, inaccessible
to direct Internet traffic
Increases the chances that the requests reaching the application server are well
formed because reverse proxy servers inspect the contents of each request more
thoroughly than most firewalls
Often performs SSL acceleration and load distribution
2: Reverse HTTP Proxy in the DMZ 7

3 Validating User Data

Any time that your application accepts information from the user, the application is
responsible to verify that the users data is of a valid type before submitting this
information to the RSA Adaptive Authentication (On-Premise) system.
The Adaptive Authentication (On-Premise) system in the standalone model contains
user data validation capability. At any point in which the user enters data, the
standalone model validates the user information. This functionality compares the
information that the user enters, for example, user phrase or answers, against profanity
and certain special characters, such as -, <, /, and \.
This type of data validation is not yet available in the RSA API models.
Validating User Input

Before passing information to the methods, your application must validate user input
into the API models against the following:
Profanity
SQL Injection
XML Injection
Special Characters
Scripting Patterns
Profanity
There are several methods for validating user-entered data, including using the same
logic that is used to check a users password. However, RSA currently does not offer
any recommended method with which to check this information.
Edit the Profanity Filter

During the installation and configuration, you can configure the profanity filter to
include a list of profanity not allowed in the users personalized caption.
Important: Because of the double-byte nature of the configuration files, you must use
a UTF-8 compatible text editor. If you use a text editor that is not UTF-8 compatible,
you may encounter UTF-8 errors when you load your configuration files.
3: Validating User Data 9

To edit the profanity filter:

1. In the rsa_root_directory/configs directory, locate and open the
phrase_profanity.txt file.
2. Add any additional terms as necessary, or remove files.
3. Save the file.
Note: Changes to the profanity filter are applied only after a configuration reload. For
more information, refer to the topic about reloading a Configuration Tree in the
Operations Guide.
SQL Injection
SQL injection is a way to exploit your web application by inserting a SQL query or
command into fields that are normally reserved for user information that is submitted
as input, such as the user name or password field. This query or command then
submits a request to your database.
RSA Adaptive Authentication (On-Premise) provides functionality to check for SQL
injection.
Configure your application to check for potential SQL queries or commands.
XML Injection
XML injection is a way for fraudsters to manipulate the users SOAP API by inserting
XML fragments into the users input fields. XML injection can cause undesired
behavior of the system, such as disabling the running of the RSA Risk Engine.
Configure your application to look for the following character strings and disallow
these strings from the users input:
<!- - -->
Special Characters
RSA Adaptive Authentication (On-Premise) provides functionality to check for
special characters. Configure your application to look for and disallow the following
characters in user input:
` < > " ' % ; ( ) & + \ # ? { } | ^ ~ [ ]
If your system finds any of these characters within the users data fields, it displays an
input error to the user and asks the user to resubmit the data.
Scripting Patterns
RSA Adaptive Authentication (On-Premise) provides functionality to check for
scripting patterns. Configure your application to look for and disallow the following
scripting patterns in user input:
' " ` \
10 3: Validating User Data

Additional Data Validation Guidelines

For more information on securing online applications, including guidelines for data
validation, go to http://www.owasp.org.
3: Validating User Data 11

4 Device Information Collection

Device Information
Collection of Device Information
Information Sent to Web Services
Overview of the Setting of Device Print Information
Setting Device Print Information
The RSA Adaptive Authentication (On-Premise) system collects specific information
about a users device, such as a personal computer or web-enabled PDA, that is used
to initiate requests to your system. The collected information, such as device
information and device tokens, helps to determine the level of risk associated with a
user accessing your system.
This chapter describes the device information that is required by the RSA Adaptive
Authentication (On-Premise) system. It also describes how to collect the data using
the tools and scripts provided by RSA.
Device Information
Device information is a collection of facts from a users machine. These facts feed
into the RSA Risk Engine and help identify fraudsters and fraudulent activities. The
collection of these facts is performed through the use of JavaScript and HTTP request
headers.
The device information that is collected helps to uniquely identify a users device.
For each device that interacts with the Adaptive Authentication (On-Premise) system,
the following information is captured:
HTTP headers
Source IP address
Device Print
Mobile Device information
User-defined credentials
Device Token (optional)
HTTP Headers
The information collected within the HTTP headers includes the following:
Accept string
Referrer value
4: Device Information Collection 13

Accept-Language string. This language may be different than what is captured by

the Device Print scripts.
User-Agent string. This request information is captured by the system to validate
the authenticity of the device token and for further forensic analysis and fuzzy
matching.
Source IP Address
Source IP addresses are used to further validate the device and to generate user
geographic location forensics. It is important that this value is the IP address of the
end user, not of a proxy or internal machine.
If the web server is fronted with a reverse proxy server, you can use a trusted
proxies mechanism to obtain the true source IP address. This mechanism retrieves
the source IP address by interpreting a different field of the HTTP header based on the
configuration of the proxy that sent the request. For example, if the proxy server that
sent the request is an Apache server, the trusted proxies mechanism looks for the
X-Forwarded-For header field.
Device Print
The Adaptive Authentication (On-Premise) system creates a globally unique device
ID for each computer that accesses your online transaction system. The device ID,
together with additional methods, is used to verify the computers identification. The
additional methods are:
Device forensicsAnalysis of the detailed hardware and software characteristics,
or Device Print, of each computer
Network forensicsAnalysis of the IP address, subnet, ownership, and
geographic location of the network connection the computer is using
The Device Print consists of the following pieces of data:
User agent stringThe version, platform, and the acceptance-language header
(the users language preference)
Screen resolutionWidth, height, and color depth of the users screen
Plug-in informationThe browser plug-ins that a user has installed on the device
Browser languageThe language of the actual browser
Time zoneThe users current time zone in GMT
LanguageThe users browser language and the system language
Java-enabledWhether or not the user has Java enabled on the device
CookiesWhether or not the user has cookies enabled on the device
This information is fed into the RSA Risk Engine and contributes to risk analysis and
fuzzy matching. RSA Adaptive Authentication (On-Premise) supplies a series of
scripts to gather this information
Mobile Device Information

For information on mobile device information, see the Web Services API Reference
Guide.
14 4: Device Information Collection

For information about integrating the RSA Mobile SDK - Adaptive Authentication
Module, setting the user permissions, and installing and using the sample application,
see the RSA Mobile SDK - RSA Adaptive Authentication Module Developers Guide.
User-Defined Credentials
For information on user-defined credentials, see the Web Services API Reference
Guide.
Device Token
Note: The collection of Device Token information is optional.
The Adaptive Authentication (On-Premise) system handles the device information

used in second-factor authentication in the form of encrypted device tokens, also
referred to as device cookies or PMData cookies. Device tokens are generated by the
system and stored on the client device in the form of cookies and Flash Shared Objects
(FSOs).
Information Stored in a Device Token

Data encoded into device tokens includes payload data (device ID, user-agent string to
identify browser, creation date) and protocol data (version number, key ID,
checksum).
Each device token is constructed using the following format:
[Token Version][Key Name][Encrypted Token Information]
where:
Token Version is the version of the device token. For instance, version 3 is V3
Key Name is the name of the key used to encrypt the data within the token
Encrypted Token Information includes:
Device ID
Creation date
Checksum of the Device ID and Creation date values (to ensure the integrity
of the data)
Storage of Device Tokens

Device tokens are stored on the users device using two different mechanisms:
Cookies.The system uses a persistent cookie, PMData, as the primary mechanism
for storing device tokens. This persistent first-party cookie does not contain
personally identifiable information in its P3P definition.
Flash Shared Objects. A Flash Shared Object (FSO) is used as a backup copy of
the device token in the event that the PMData cookie is deleted. The FSO is stored
and retrieved by playing an invisible Flash movie.
RSA provides the Flash movie file pmfso.swf, which you can run to retrieve and
set the FSO.

Using Device Tokens

When a user enrolls in the Adaptive Authentication (On-Premise) system, the
following occurs:
A device token is created and placed on the users device.
The device token is also stored in the User ID record in the database after
enrollment is completed.
The device token helps to authenticate a user in the following situations.
When the user signs in to your online system
During transaction authentication
Bind and Set Device Tokens

In the Adaptive Authentication (On-Premise) system, you can either:
Set a token, which places a device token on a users device.
Bind a token, which places a device token on the users device and associates it
with that particular user. The device is bound to that user.
A token can be set on a users device, but not bound to the user. This might occur
during certain actions, such as transaction authentication. Setting a token on a users
device during transaction authentication can help detect fraud, such as
man-in-the-middle attacks.
You can configure your application when to specifically bind a user to a device at
certain times, such as after the user successfully enrolls or after the user has
successfully passed a challenge, and when to simply set a token. Typically, a user is
bound to a device after successfully enrolling into the Adaptive Authentication
(On-Premise) system and after successfully responding to a challenge.
A device binding (linking a user and a device) helps identify the user and allows the
user to log on to your system without being challenged. If the device token is not
present, or if the user is not bound to a device, for example, when logging on from a
different computer, the user is challenged.
Multiple Devices and Tokens

A single user can log on to more than one machine by logging on from a different
machine and successfully passing a challenge. For example, one person can use a
computer at home and a computer at work to check account information.
In addition, a single device can be bound to more than one user through single or
multiple tokens on the same machine. For example, a family with multiple users can
use one computer to log on to their respective online accounts.
Device Token Checksum and Encryption

The RSA Adaptive Authentication (On-Premise) system complies with FIPS 140-2
Level 1 encryption standards.
Adaptive Authentication calculates a checksum for and encrypts all data stored in a
device token on the users computer. Because the sending and receiving parties are the
same, the system uses secret-key encryption to encrypt device tokens.

This checksum and encryption ensures the integrity of the data and verifies the source
of the data as the system.
Domain Scoping
For information about domain scoping, refer to the section about configuring domain
scoping in the Operations Guide.
Device Token Recovery

When an enrolled user logs on to the Adaptive Authentication (On-Premise) system,
the system searches for device tokens on the users device. The user may have deleted
or suppressed cookies or disabled Flash player, which prevents the Adaptive
Authentication system from identifying the user as a valid user. Consequently, the user
may be challenged repeatedly.
Device token recovery helps prevent legitimate users from unnecessary challenges if
they delete cookies or disable Flash player. Device token recovery works only for
devices that are bound to users.
Device token recovery is relevant only for the following channels:
Web
Mobile
In earlier versions, data elements were used to determine whether the channel is Web
or Mobile. Starting from RSA Adaptive Authentication (On-Premise) 7.0, the Channel
Determination Service is used to identify the type of channel.
Note: Device token recovery is automatically enabled for the Adaptive Authentication
(On-Premise) system. You can disable device token recovery by modifying the
relevant parameters in the Administration Console. For more information, see the
Operations Guide.
Due to forensic similarities between browsers across mobile devices, RSA
recommends that you use these capabilities to disable device recovery specifically for
mobile browsers.
The process of device token recovery is as follows:

1. When a user logs on to your system and the device token is missing, the system
attempts to re-create the device token for the user using information such as:
Source IP address
HTTP header information
Device print information
The information in the database is compared to the information from the users
current device and passes through various models that determine how good a
match it is to the current device. A device recovery score is generated based on the
match.
2. The device recovery score passes through your institutions policies (within the
Policy Engine) to determine if the score meets a threshold setting for device token
recovery confidence, with one of the following results:

If the device recovery score exceeds that threshold, the device token is
considered recovered and the user is allowed to proceed without challenge.
If the device recovery score does not meet the threshold, the device token is
not considered recovered and the user is challenged.
3. If the device token is recovered, a new device token is generated from the
recovered record and sent back to your application to place on the users device.
4. The new information indicating that a device token recovery occurred.
Device Token Theft Detection

Device tokens can potentially be stolen by malware and used to identify a hackers
device as a legitimate device. Device token theft protection helps prevent imposters
from using stolen device tokens.
Device token theft detection prevents fraudsters who steal device tokens from a
legitimate device and attempt to use it on another machine.
This section describes the process of device token theft detection.
1. Because a device token is regenerated each time a user accesses the system, an old
instance of a token is detected.
2. An analyzer compares the retrieved token against the users history in the device
record, with one of the following results:
If the match confidence is low, a high risk score is assigned to that device,
which triggers the Adaptive Authentication (On-Premise) system to issue a
challenge for the device and prevents the imposter from accessing your
system.
If the match confidence is high, a low risk score is assigned to the device.
Your institution can choose to either challenge the user or allow the user
access.
3. The database is updated with the new information including a high-risk device for
that device token.
Collection of Device Information

This section describes the implementation mechanisms that do the following:
Allow your application, for example, an organization website, to collect device
data from the user and store it in the RSA Adaptive Authentication (On-Premise)
system
Store data to an end users device
This data is entered into the RSA Risk Engine, and helps the Adaptive Authentication
(On-Premise) system to identify potential fraudulent transactions.
RSA recommends that device print information collection always occurs at the
following times:
During logon, to help determine the validity of the user and provide authentication
information.

During enrollment, to capture historical information on the user.

During Transaction authentication, to help determine the validity of the user and
provide information for analysis.
Collection of Device Print Information During Logon

During logon, ensure that your application captures the device information when the
user submits his user name. You can then post all the device information and User ID
within one given page. The following figure shows an overview of the device
collection during logon.

Collection of Device Print Information During Enrollment

After the user is successfully authenticated by your system, you can enroll the user
into the Adaptive Authentication (On-Premise) system.
RSA recommends that you send the device information to the Adaptive
Authentication (On-Premise) system when the user selects challenge questions during
enrollment. The device information is posted to the server at the same time.
The following figure shows an overview of the collection during enrollment.

Collection of Device Print Information During Transaction Authentication

RSA recommends that you send the device information to the Adaptive
Authentication (On-Premise) system when the user begins a transaction. During this
period, your application should write the device token information to the users
browser. For more information, see Device Print Information Set During Transaction
Authentication.
The following figure shows an overview of the device collection during a transaction.

Collection of Information Using the Mobile SDK - Adaptive Authentication

Module
The RSA Mobile SDK - Adaptive Authentication Module provides collection
methods that support risk-based authentication of end users accessing online
transaction applications by way of a mobile device.
For information about integrating the module, setting the user permissions, and
installing and using the sample application, see the RSA Mobile SDK - RSA Adaptive
Authentication Module Developers Guide.
RSA recommends that you collect the information using the Mobile SDK - Adaptive
Authentication Module at the following times:
During logon, to help to determine the validity of the user and provide
authentication information. At this time, ensure that your application captures the
information when the user submits a user name. You can then post the collected
information and User ID within one given page.
During enrollment, to capture historical information on the user. After the user is
successfully authenticated by your system, you can enroll the user into the
Adaptive Authentication (On-Premise) system. RSA recommends that you send
the information to the Adaptive Authentication (On-Premise) system when the
user selects challenge questions during enrollment. The collected information is
posted to the server at the same time.
During transaction protection, to help determine the validity of the user and
provide information for analysis. RSA recommends that you send the collected
information to the Adaptive Authentication (On-Premise) system when the user
begins a transaction. During this period, your application should write the
collected information to the users browser.

The following figure shows an overview of the information collection during logon,
enrollment, and transaction authentication.
Scripts for Collection of Device Print Information

RSA provides mechanisms that your application can use to interface to the end-users
browser and mobile application, and to the Adaptive Authentication (On-Premise)
system. Example code is provided later in this chapter.
The logical flow of these operations is shown in the following files:
PassMarkSimpleFSOServlet. The servlet that shows how to retrieve posted
PMData using the invisible Flash movie.
pmfso.jsp. The reference file that shows how to run the Flash movie and retrieve
the device token from the Flash Shared Object (FSO).
pmfso_set.jsp. The reference file that shows how to run the Flash movie and set
the device token in the FSO.

rsa.js. The reference file that shows how to collect Device Print information and
post the information back to the server. For more information, see Retrieval of
the Device Token on page 24.
Note: Ensure that you integrate the JavaScript code from RSA into your web
applications. This JavaScript code collects device information from end users. It is
mandatory that you send RSA the device information through the deviceRequest
element.
pmfso.swf. The Flash movie that reads and sets the FSO.
Note: Do not edit this file.
Signin.jsp. The file that demonstrates how to include the reference information
found in pmfso and pm_fp in the logon workflow.
AC_OETags.js. The JavaScript file created by Adobe that is responsible for
detecting the Flash version on the end-users browser.
Note: The set of files is located in the WebResources.zip package that is installed
with the development utilities component. For more information, see the
Installation and Upgrade Guide.
Retrieval of the Device Token

You must retrieve the device token, which is stored as both a cookie and a Flash
Shared Object (FSO). For more information about the device token, see Device
Token on page 15.
Retrieve the PMData Cookie

The Adaptive Authentication (On-Premise) system uses a persistent cookie, PMData,
to store device tokens.
To retrieve the cookie using the Web Services API:

1. Retrieve the cookie from the users device.
2. Populate the Web Service parameter, deviceTokenCookie, with the value of
PMData.
Retrieve a Flash Shared Object Token

The Flash Shared Object (FSO) is a backup copy of the device token that is used if the
PMData cookie has been deleted. The FSO is retrieved by playing an invisible Flash
movie. Your application must have a listener that is ready to receive the posted data.
If the user does not have Flash Player installed, the movie is not played and the FSO is
not posted.
Before you Begin

In the pmfso.jsp file, set the following values in the FlashVars parameter:

sendUrlAddress of the servlet to which the retrieved device token is posted.

This is passed by the JavaScript or VBScript code to the Flash movie.
gotoUrlRedirects the user to a specific target page after the Flash movie sends
the tokens to the RSA application.
If you do not want the user redirected, set gotoURL=.
browserType - The user's browser type, which is used to distinguish between FSO
names that were created in different browser types.
The Flash movie, stored in the pmfso.swf file retrieves the device token and takes
these values as part of the FlashVars variable:
<param name='FlashVars' value='gotoUrl=&sendUrl=the servlet
url&browserType= the user's browser type'>
Note: When placing the token in the FSO, you can also pass the gotoUrl variable with
the value of a specific URL. The page that hosts the Flash redirects the user to the
specified target page after the Flash movie sets the token in the FSO.
To retrieve an FSO token:

1. Detect whether Flash is installed. For more information, see Detection of Flash
Player on page 25.
2. Detect the browser type. For more information, see Detection of the Browser
Type on page 26.
3. Retrieve the device token. For more information, see Retrieve the Device Token
on page 27.
4. Include the pmfso.jsp file in your logon page that contains the User ID field. For
more information, see Include the pmfso.jsp file in your logon page that contains
the User ID field on page 27.
5. Set the device token in session. For more information, see Set the Device Token
in Session on page 27.
6. Get the FSO token information from the session and populate Web Services. For
more information, see Retrieval of the Token from the Session on page 27.
Detection of Flash Player
The scripts provided by RSA detect whether Flash is installed on the users device.
This step avoids security warnings that are generated by trying to run Flash movies on
a system that does not have Macromedia Flash installed.
The AC_OETags.js script, provided by the Adobe Flash detection kit, is activated to
detect the Flash version installed on the user's browser.
You must use Flash version 6.0.0 or later to use the Flash token mechanism.
Example from pmfso.jsp:
<script src="AC_OETags.js" language="javascript"></script>
<script language="JavaScript" type="text/javascript">

</script>

</script>
Detection of the Browser Type
The FSO token value represents the same token value that is created in the cookie
placed on the browser.
A user may use different types of browsers on the same computer to access the online
site. In this case, different cookies are created for different browsers. Because the FSO
value backs up the same cookie value, different FSOs are created for different browser
types.
To detect the browser type for the Flash usage, RSA uses the rsa.js file. This same file
is used for gathering the device fingerprint. The rsa.js script must be called on every
page that uses the Flash file.
The script contains the BrowserDetect object, which collects the information about the
user's browser. You must use a specific BrowserDetect.browser parameter within
rsa.js to retrieve the browser type as a string.
Example from Signin.jsp:
<script src="rsa.js" language="JavaScript"
type="text/javascript"> </script>
<%@ include file="pmfso.jsp" %>
Example from pmfso.jsp:
<script>

</script>
..."<param name='FlashVars'
value='gotoUrl=<%=gotoUrlEnc%>&sendUrl=<%=sendUrlEnc%>&brows
erType=" + BrowserDetect.browser + "'>"...

Retrieve the Device Token

Run the Flash movie, contained in the pmfso.swf file to retrieve the device token.
Include the pmfso.jsp file in your logon page that contains the User ID field
When the sign-in page with User ID loads, the movie runs and fetches the device
token from the FSO and posts it to the FSO Servlet while the user is entering his data.
When the Flash movie is played, it reads the FSO data, and sends the data
asynchronously to sendURL.
The servlet reads the PMData from the HttpRequest object.
<html>
<head>
<title>Example Signin Page</title>
...
</head>
<body>
<%@ include file="pmfso.jsp" %>
...
Username: <input type="text" name="username"/>
Set the Device Token in Session
As a next step, the Flash movie posts the retrieved device token to an FSO Servlet
(PassMarkFSOServlet provides the reference code for this step.) This servlet stores
the device token using session-based mechanisms.
You can use the reference servlet to create your own listener to receive the posted FSO
data.
The Flash movie posts the device token under the PMData parameter.
Java example:
//get device token from request
fsoToken = request.getParameter("PMData");
//store it in the session
session.setAttribute(ATTR_FLASH_SO, fsoToken);
VB Script example:
If Not Request.Form("PMData") Is Nothing AndAlso
Request.Form("PMData").Trim().Length > 0 Then
pmfso = Request.Form("PMData")
Session("pmfso") = pmfso
Note: The token is passed to the FSO servlet to ensure that the information is bound to
the page hosting the movie. This prevents hackers from stealing movie tokens.
Retrieval of the Token from the Session

For Web Services, you must get the FSO token information from the session and
populate Web Services.

Collection of Device Print Information

RSA provides the rsa.js script, which:
Pulls the device print information from the web page
URL encodes the information
Posts the information to the server
The server URL decodes the information for use within the RSA database
The rsa.js script contains the add_deviceprint() function, which passes the device
print information as a single string to the Adaptive Authentication (On-Premise)
system. You must invoke this specific function within rsa.js to retrieve the device
print information.
Note: The function, add_deviceprint(), only returns the value of devicePrint. It does
not populate a hidden value to be returned to the Adaptive Authentication
The following is an example of HTML or JavaScript code that you must add below
the sign-in page with the username field.
<html>
<head>


</head>
<body>

<script language="javascript">
document.write("<INPUT TYPE='hidden' id='some id'
value='encode_deviceprint()'>");
</script>

</body>
</html>
Device Print Fields

For Web Services, this information is passed within the deviceRequest.devicePrint
parameter.
If you are using an earlier version of the Adaptive Authentication (On-Premise)
system (such as the legacy PassMark system), you can implement the new rsa.js script
without making changes to your existing pages. If you are using Web Services, you
can continue to populate individual devicePrint-related fields, using the
backward-compatible API.
The following information is collected by the rsa.js script:
User-agent stringContains information, such as the application name, version,
host operating system, and language.

Screen informationThe color depth, width, height, and vertical space of the
users screen.
Software plug-insThe software plug-ins installed in the users browser.
Time zoneThe users current time zone.
Browser languageThe language that the user has set in their browser.
A Boolean value that indicates whether Java is enabled in the browser.
A Boolean value that indicates whether cookies are enabled in the users browser.
Operating systemThe operating system installed. Possible values are: Windows,
Linux, Mac, iPhone/iPad, an unknown OS.
Major versionThe major version of the browser.
Browser typeThe browser being used. Possible values are: Netscape, Mozilla,
Explorer, Camino, Firefox, Konqueror, iCab, Opera, Safari, OmniWeb, Chrome.
Latency (internal IP and external IP ping time)
The following is an example of the devicePrint output.
version=1&pm_fpua=mozilla/5.0 (windows; u; windows nt 5.1;
en-us; rv:1.8.0.4) gecko/20060508 firefox/1.5.0.4|5.0
(Windows;
en-US)|Win32&pm_fpsc=32|1280|1024|990&pm_fpsw=def|qt6|qt5|qt
4|qt3|qt2|qt1|swf|pdf|mso|j14|j32|j11|j12|j13|wpm|drn|drm&pm
_fptz=-7&pm_fpln=lang=en-US|syslang=|userlang=&pm_fpjv=1&pm_
fpco=1
URL Encoding Example

The following is the URL encoding performed on the preceding devicePrint output
example.
version=DEV_VERSION&pm_fpua=mozilla/5.0 (windows nt 6.1;
wow64; rv:8.0.1) gecko/20100101 firefox/8.0.1|5.0
(Windows)|Win32&pm_fpsc=24|1440|900|860&pm_fpsw=|pdf|swf|mso
&pm_fptz=2&pm_fpln=lang=en-US|syslang=|userlang=&pm_fpjv=1&p
m_fpco=1&pm_fpasw=npgoogleupdate3|nppdf32|npctrl|npdeployjav
a1|npjp2|nperoom7|npswf32|npwatweb|npnv3dvstreaming|npnv3dv|
npwachk|npoffice&pm_fpan=Netscape&pm_fpacn=Mozilla&pm_fpol=t
rue&pm_fposp=&pm_fpup=&pm_fpsaw=1440&pm_fpspd=24&pm_fpsbd=&p
m_fpsdx=&pm_fpsdy=&pm_fpslx=&pm_fpsly=&pm_fpsfse=&pm_fpsui=&
pm_os=Windows&pm_brmjv=8&pm_br=Firefox&pm_fp_inpt=1049&pm_fp
_expt=1050

Information Sent to Web Services

The Web Services AuthRequest has a deviceRequest parameter, which contains
various fields in which to populate the device information.
Several of the variables listed in the following table are used for earlier versions of
Web Services. The devicePrint parameter sets this value in Web Services 5.7 and later.
If you are using Web Services 2.2 or 2.2.1, you can continue using older
deviceRequest fields, or you can substitute with devicePrint. However, RSA
recommends that you use devicePrint to pass these values to the Adaptive
Authentication (On-Premise) system.
Variable Description Value
browserDevicePrint The Device Print of the browser. string
cookies The users cookies. array of cookie
deviceLanguage (For releases 2.2 - 2.2.1) The browsers language setting information. string
devicePrint The information collected by the rsa.js script, for Device Print. For string
more information, see Retrieval of the Device Token on page 24.
devicePrintChecked A Boolean value that tells the Adaptive Authentication (On-Premise) boolean
system whether your system checked the Device Print. This value
should be set to true if your system has attempted to retrieve the
Device Print.
deviceTimeZone (For releases 2.2 - 2.2.1) The time zone of the users device. string
flashToken The Flash Shared Object. string
httpAccept The Accept value in the HTTP header. string
httpAcceptLanguage The Accept language value in the HTTP header. string
httpReferer The Referrer value in the HTTP header. string
ipAddress The IP address of the users device. string
language The users language setting. string
screenDevicePrint (For releases 2.2 - 2.2.1) The users screen device information. string
softwareDevicePrint (For releases 2.2 - 2.2.1) The plug-ins on the users device string
userAgent (For releases 2.2 - 2.2.1) The user agent string string
For more information about these fields within Web Services, see the Web Services
API Reference Guide.

Overview of the Setting of Device Print Information

RSA Adaptive Authentication (On-Premise) creates the device token when necessary
and returns it as part of the appropriate API message.
You can choose to set device information at any time, however it must always be set.
RSA recommends that you set device information at the following times:
EnrollmentCaptures historical information on the user.
ChallengeOnce the user has successfully passed the challenge, the device
information should be set. If the user fails the challenge, you do not need to set the
cookie.
Transaction authenticationSetting the device information at the time of a
transaction authentication helps to determine the validity of the user and prevent
man-in-the-middle attacks.
Note: You must place the PMDataCookie and the fsoToken on the users device if
returned within the return message.
In accordance with general security best practices, RSA recommends that you verify
that the device token received via the PMData parameter is properly formatted.
Device tokens should only consist of numbers, letters, and the following
special characters: +, \, and =.

Device Print Information Set During Enrollment

After the user has been successfully authenticated by your system, you can enroll the
user into the Adaptive Authentication (On-Premise) system.
RSA recommends that you set the device information when the user confirms the
enrollment information.
The following figure shows an overview of setting the device information during
enrollment.

Device Print Information Set After a Successful Challenge

After a user successfully passes a challenge through the Adaptive Authentication
(On-Premise) system, you must place the device information on the users device,
provided it is not a public computer, for example, a computer in a library or Internet
cafe. Your system should ask the users if they are using a public device.
The following figure shows an overview of setting the device information during
challenge.

Device Print Information Set During Transaction Authentication

During a transaction, you need to collect device token information and place new
information on the users browser. For information about how to collect the
information, see Collection of Device Print Information During Transaction
Authentication on page 21. When you initiate a transaction authentication, you
receive a message back from the Adaptive Authentication (On-Premise) system with
device token information. Set this new token information on the users browser.
Placing this information on the users browser can help prevent man-in-the-middle
attacks. The following figure shows an overview of setting a device token during a
transaction authentication.

Setting Device Print Information

The Adaptive Authentication (On-Premise) system passes two types of data to be
placed on the users device:
A cookie named PMData
A Flash Shared Object (FSO)
Place the PMData Cookie

You can set the cookie information using HTTP protocols.
To set the cookie information:

Set the received deviceToken on the users machine in a cookie with the following
properties:
NamePMData
Max Age365 days
domainyour domain name
path / This ensures that the cookie is accessible from any URL on this server.
securefor production, this must always be secure.
valuedeviceToken
Place the Flash Shared Object Token

RSA provides pmfso_set.jsp script to set the Flash Shared Object token on a users
device.
To set the Flash Shared Object token:

1. Set the received deviceToken in the HTTP session when parsing the response.
2. Edit pmfso_set.jsp to get the information from the session.
3. Include pmfso_set.jsp in the landing page.
Note: When placing the FSO, make sure it is URL encoded.
The following steps outline how the fsoToken is set into the FSO using
pmfso_set.jsp:
1. Detect whether Flash is installed.
2. Detect the browser type.
3. Run the Flash movie.
Note: The rsa.js and AC_OETags.js files must be included in pmfso_set.jsp or in the
file that contains the pmfso_set.jsp file.

In the pmfso_set.jsp file, two values within the FlashVars parameter are passed to the
Flash movie and need to be set:
PMData - The value of the deviceToken that is extracted from the session.
browserType - The user's browser type that is used to distinguish between FSO
names that were created in different browser types.
The Flash movie, stored in the pmfso.swf file, retrieves the device token and takes
these values as part of the FlashVars parameter, as shown below:
FlashVars='PMData=the deviceToken value &browserType=the
user's browser type'
If you are using a web technology other than JSP, use the following code example to
see how to call the movie and pass it the deviceToken.
<%@ page
import="java.net.URLEncoder,java.util.regex.Matcher,java.util.regex.
Pattern" %>
<%
// get the deviceToken from session. JavaScript will pass this value
to the flash movie
String pmfso_set_devToken = (String)
session.getAttribute("_FLASH_SO_");
if (pmfso_set_devToken == null)
{
pmfso_set_devToken = "";
}
Pattern p = Pattern.compile("[^0-9a-zA-Z/+=]");
Matcher m = p.matcher(pmfso_set_devToken);
Boolean isTokenValid = false;
if (!m.find())
{
pmfso_set_devToken = URLEncoder.encode(pmfso_set_devToken,
"UTF-8");
isTokenValid = true;
}
else
{
// Throw an error
pmfso_set_devToken = "";
isTokenValid = false;
}
%>

<script src="pm_fp.js" language="JavaScript"

type="text/javascript"></script>
<script>

</script>
<script src="AC_OETags.js" language="javascript"></script>


</script>

</script>


</script>
<%
if (isTokenValid)
{
%>
<noscript>
<object classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000'
width='1' height='1'>
<param name='movie' value='pmfso.swf'>
<param name='quality' value='high'>
<param name='bgcolor' value=#FFFFFF>
<param name='FlashVars' value='pmdata=<%=pmfso_set_devToken%>'>
<embed src='pmfso.swf'
FlashVars='pmdata=<%=pmfso_set_devToken%>'
quality='low' bgcolor='#FFFFFF' width='1' height='1'
type='application/x-shockwave-flash'>
<noembed></noembed>
<noobject></noobject>
</embed>
<noobject></noobject>
</object>
</noscript>
<%
5 Information Collection
Trojan Protection Solution
Mobile Location Awareness
This chapter describes the implementation mechanisms that:
Collect information about users Document Object Model (DOM) elements for a
specific HTML page
Collect browser events that occur on an HTML page
Collect detailed information about the location of the end-user mobile device
Provide security from threats arising from man-in-the-middle proxy attacks
The collected data is entered into the RSA Risk Engine and helps the RSA Adaptive
Authentication (On-Premise) system identify potential fraudulent transactions.
Note: Ensure that you integrate the JavaScript code from RSA into your web
applications.
Trojan Protection Solution

The Trojan Protection Solution includes the following two features:
HTML Injection Protection
Man vs. Machine Detection
Proxy Attack Protection
Note: The Trojan Protection Solution feature is designed for websites only, and does
not apply to WAP (mobile Internet) sites.
HTML Injection Protection

HTML Injection Protection protects against fraudsters who perform fraudulent
activities by manipulating JavaScript functions that are active on HTML pages.
For HTML Injection Protection, JavaScript collects information about users
Document Object Model (DOM) elements for a specific HTML page. These DOM
elements include:
Field names
iFrames
JavaScript function names
5: Information Collection 39
When the information is collected, it is formatted as a single string and sent to the
RSA Adaptive Authentication (On-Premise) system as part of the domElements
element within the DeviceRequest payload.
Note: This feature is designed for websites only and does not apply to WAP (mobile
Internet) sites.
Overview of Information Collection for HTML Injection Protection

The following figure shows an overview of the information collection for HTML
Injection Protection.
For information about how to collect data for HTML Injection Protection, see Collect
Information for HTML Injection Protection on page 42.
40 5: Information Collection
Script for Collection of HTML Injection Protection Information

RSA provides the same script, rsa.js, for collecting the device print information and
for the Trojan Protection Solution features. This script includes all of the functions
that are called based on the data that you want to collect. When you collect
information for HTML Injection Protection, the information is formatted as a single
string. This string is posted to your organizations application and sent to the Adaptive
Authentication (On-Premise) system. Adaptive Authentication uses this information
to detect Trojan activities.
Note: You must apply the script to each page that requires HTML Injection
Protection.
HTML Injection Protection Function Names

The following functions in the rsa.js script are used to collect information for HTML
Injection Protection:
dom_data_collection.initFunctionsToExclude - Configures the collection of DOM
elements, such as field names, iFrames, and function names.
dom_data_collection.startInspection - Runs the main collection of information.
dom_data_collection.domDataAsJSON - Formats the collected DOM elements
into a single string.
Note: You must call dom_data_collection.startInspection and

dom_data_collection.domDataAsJSON after the onLoad event is called and before the
onSubmit event is called.
The string is posted to your organizations application and sent as part of the
domElements element within the DeviceRequest payload, to the Adaptive
Authentication (On-Premise) system.
For more information about the flow of this event within Web Services, see the Web
Services API Reference Guide.
For information about how to collect information for HTML Injection Protection, see
Collect Information for HTML Injection Protection on page 42.
Collect Information for HTML Injection Protection

The following section describes how to collect information about users Document
Object Model (DOM) elements for a specific HTML page.
Before You Begin

Perform Collection of Device Information on page 18.
Note: You cannot collect information for HTML Injection Protection if you do not
complete the information collection for Device Print. Device Print collects
supplementary information for HTML Injection Protection.
Prepare a list of function names that should not be collected.
Note: You can find these function names, for example, the names of third-party
libraries, in your code.
The functions in this list are not collected, reducing the amount of information
collected. This list also helps to prevent important information from being
truncated due to constraints in the length of the string.
To collect HTML Injection Protection information:

1. Configure the information collection by adding the following sample code to the
existing HTML page:
var dom_data_collection = new DomDataCollection();
dom_data_collection.config.functionsToExclude = ['exclude1',
'exclude2'];
dom_data_collection.initFunctionsToExclude();
2. Replace 'exclude1' and 'exclude2' in the sample code with the names of the
functions you want to exclude.
Note: More than two functions can be excluded, for example, 'exclude1',
'exclude2', 'exclude3', 'exclude4'.
RSA recommends that you update the list of excluded functions when there is a
change to the third-party libraries applied to specific HTML pages.
3. Save the json2.js file in the directory in which you saved the rsa.js file.
4. Change the following line to include the name of the json2.js file in the
parenthesis.
For example:
var dom_data_collection = new DomDataCollection('json2.js');
Note: This path is relative to the location of the HTML document. This example
assumes that the HTML, rsa.js, and json2.js files are all in the same directory.
The JSON code from the json2.js file can be loaded only if it has not already been
made available by the browser. This can occur when you use an earlier version of
a browser that does not support JSON (for example, Windows Internet Explorer
8).
5. After the HTML page loads and before the onSubmit event, run the main
collection function by entering the following command:
dom_data_collection.startInspection();
6. Format the collected information into a single string by calling the following
function:
var domElementsString = dom_data_collection.domDataAsJSON();
7. Repeat steps 1 through 4 for each page that requires information collection for
HTML Injection Protection.
The string is posted to your organizations application and passed to the Adaptive
Authentication (On-Premise) system as part of the SOAP request.
Note: You must send the value of the pageId field to the Adaptive Authentication
(On-Premise) system using the SOAP request. For more information, see the Web
Example of the output for HTML Injection Protection
{
functions : {
names : [getX,run],
excluded : {
size : 2830,
count : 259
},
truncated : true,
},
inputs :
[amount,captcha,message,sel1,spell_check,submit,u
name],
iFrames : [http://mysite.com/a.html,
http://mysite.com/iframe],
scripts : [208,337,0,0,0,152],
collection_status : 0
}
Man vs. Machine Detection

Man vs. Machine Detection helps organizations protect against automated Trojans that
operate in the background to perform fraudulent activities in place of users.
Man vs. Machine Detection identifies unusual behavior by examining browser events
that occur on an HTML page. JavaScript collects the following browser events:
Keyboard strokes
Mouse movements
Adaptive Authentication (On-Premise) system as part of the jsEvents element within
the DeviceRequest payload.
Internet) sites.
Overview of Information Collection for Man vs. Machine Detection

The following figure shows an overview of the information collection for Man vs.
Machine Detection.
For information about how to collect data for Man vs. Machine Detection, see
Collect Information for Man vs. Machine Detection on page 45.
Script for Collection of Man vs. Machine Detection Information

RSA provides the same script, rsa.js, for the collection of device print information
and for the Trojan Protection Solution features. This script includes all of the functions
that are called based on the data that you want to collect. When you collect
information for Man vs. Machine Detection, the information is formatted as a single
string. This string is posted to your organizations application and sent to the Adaptive
Authentication (On-Premise) system. Adaptive Authentication uses this information
to detect Trojan activities.
Note: You need to apply the script to each page that requires Man vs. Machine
Detection.
Man vs. Machine Detection Function Names

The rsa.js script contains the following functions:
UIEventCollector.initEventCollection - Initializes the collection of data when the
HTML page loads.
UIEventCollector.serialize - Formats the collected browser events into a single
string.
Note: You must call these two functions after the onLoad event is called and before
the onSubmit event is called.
For information about how to collect information for Man vs. Machine Detection, see
Collect Information for Man vs. Machine Detection on page 45.
Collect Information for Man vs. Machine Detection

The following section describes how to collect information about browser events for a
specific HTML page.
For information about which browser events are collected, see Man vs. Machine
Detection on page 43.
Before You Begin

Perform Collection of Device Information on page 18.
Note: You cannot collect information for Man vs. Machine Detection if you do not
complete the information collection for Device Print. Device Print collects
supplemental information for Man vs. Machine Detection.
To collect Man vs. Machine Detection information:

1. After the HTML page loads and before the onSubmit event, initialize the
information collection by adding the following script code to the existing HTML
page:
<script type="text/javascript">
// initializes UI event recording when page loads

if(window.addEventListener) {
window.addEventListener('load',
UIEventCollector.initEventCollection, false);
} else if(window.attachEvent) {
window.attachEvent('onload',
UIEventCollector.initEventCollection;
} else {
window.onload = UIEventCollector.initEventCollection;
}
</script>
2. Format the collected information into a single string by calling the following
function:
var jsEventsString = UIEventCollector.serialize();
3. Repeat steps 1 and 2 for each payment-related page that requires information
collection for Man vs. Machine Detection.
Note: You must send the value of the pageId field to the Adaptive Authentication
(On-Premise) system using the SOAP request. For more information, see the Web
Example of the output for Man vs. Machine Detection

1,text1,INPUT:text,5;2,text2,INPUT:text,8;3,BODY,BODY,0;4,butto
n1,INPUT:button,8;5,submit1,INPUT:submit,6;6,show_collected_dat
a,INPUT:button,19;7,clear_collected_data,INPUT:button,20;@1,3,6
766;1,4,9240;2,3,15110;2,4,16086;1,3,3491984;1,1,3492256;1,1,34
92328;1,4,3492672;2,3,3492673;2,4,3493040;3,1,3493280;2,3,34951
76;2,1,3495384;2,1,3495432;2,1,3495519;2,4,3495760;2,3,3496200;
2,4,3496840;1,3,3499872;1,1,3500152;1,1,3500200;1,1,3500687;1,1
,3501352;1,4,3501353;2,3,3501353;2,1,3501544;2,4,3501545;2,3,35
01545;2,1,3501728;2,4,3501730;4,3,3501731;4,1,3501896;4,4,35018
97;5,3,3501898;5,1,3502080;5,4,3502081;3,1,3502906;6,3,3502907;
6,1,3503162;6,4,3503163;7,3,3503164;7,4,3503352;1,3,3503353;1,1
,3503680;1,4,3503681;2,3,3503681;2,1,3503912;2,1,3504088;2,4,35
04089;1,3,3504089;1,1,3504496;1,1,3505153;1,1,3505176;1,1,35053
43;1,1,3505481;1,1,3505482;1,4,3505736;1,3,3508368;1,1,3508592;
1,1,3508672;1,1,3508759;1,4,3509072;2,3,3509073;2,1,3509248;2,1
,3509327;2,1,3509375;2,1,3509559;2,1,3509663;2,1,3509704;2,4,35
09808;1,3,3510184;1,1,3510400;1,1,3510479;1,1,3510592;1,1,35107
27;1,1,3510824;1,4,3511415@0,1329401047597,0
Proxy Attack Protection

Proxy Attack Protection provides security from threats arising from
man-in-the-middle proxy attacks. In a proxy attack, a fraudster attacks an end-user
device with malware that opens a proxy on the device. The fraudster then seizes
control of the end-users device from a remote location and initiates a transaction
activity. Proxy Attack Protection analyzes the time taken to reach the end-users local
host and the end-users external IP address to determine whether the activity is
initiated from a genuine user or from a proxy.
Internet) sites.
For this feature, the JavaScript tries to connect to the URL through random ports, to
identify if a proxy exists in the end-user device.
Collect information for Proxy Attack Protection

The following procedure describes how to collect the information required to employ
the Proxy Attack Protection feature.
Before You Begin

Collect the following device print latency (ping time) information:
pm_inpt. The time taken to ping the internal IP.
pm_expt. The time taken to ping the external IP.
For information about which elements are collected, see Retrieval of the Device
Token on page 24.
To collect Proxy Attack Protection information:

1. Configure the proxy Trojan collection by adding the following activation code to
the HTML page when the page loads:
// initializes proxy trojan collector when page loads
ProxyCollector.initProxyCollection, false);
ProxyCollector.initProxyCollection);
} else {
window.onload = ProxyCollector.initProxyCollection;
}
2. Make sure that the ProxyCollector.externalIP=XXX.XXX.XXX.XXX variable
(end-users IP) is available to the JavaScript.
3. Repeat steps 1 and 2 for each page that requires information collection for Proxy
Attack Protection.
The collected data is sent to Adaptive Authentication (On-Premise) as part of the
Device Fingerprint information in the deviceRequest.devicePrint SOAP API
element.
Mobile Location Awareness

Mobile Location Awareness uses detailed information about the location of the
end-user mobile device to support risk-based authentication. It enables organizations
to identify the region or country from which the end user is attempting to access an
account by way of a new or previously used mobile device.
The RSA Mobile SDK - Adaptive Authentication Module and JavaScript collect data
using GPS, WiFi, or cell tower triangulation. Based on the collected information and
the end-user profile, Adaptive Authentication determines:
Whether the end user is accessing an account from a location other than the usual
location
Whether the end user is accessing an account from a high-risk area
The ground speed between two transactions
Note: This feature is relevant for the following W3C geolocation API types: HTML5
and BlackBerry proprietary API (version 4.1 and later).
The RSA Mobile SDK - Adaptive Authentication Module and JavaScript enable you
to collect the following information:
Longitude
Latitude
Horizontal accuracy
Altitude
Altitude accuracy
Heading
Speed
Time stamp
Status code
Adaptive Authentication (On-Premise) system as part of the geoLocation element
within the DeviceRequest payload.
For a detailed description of the information collected by the Mobile Location
Awareness feature, see MobileDevice in the chapter Web Services Request Data
Structures and Types in the Web Services API Reference Guide.
For information about how to collect information for Mobile Location Awareness, see
Collect Information for Mobile Location Awareness on page 52.
Overview of Information Collection for Mobile Location Awareness

The following figure shows an overview of the information collection for Mobile
Location Awareness.
For information about how to collect data for Mobile Location Awareness, see
Script for Collection of Mobile Location Awareness Information

RSA provides the same script, rsa.js, for the collection of device print information,
Trojan Protection Solution, and Mobile Location Awareness. This script includes
functions that collect detailed information about the location of the end-user mobile
device to support risk-based authentication. When you collect information for Mobile
Location Awareness, the information is formatted as a single string. This string is
posted to your organizations application and sent to the Adaptive Authentication
Note: This script applies to the following W3C geolocation API types: HTML5 and
BlackBerry proprietary API (version 4.1 and later).
Ensure that you integrate the JavaScript code from RSA into your web applications.
Mobile Location Awareness Function Names

The following functions in the rsa.js script are used to collect information for the
Mobile Location Awareness feature:
startCollection - Initializes the collection of Mobile Location Awareness
information when the HTML page loads. This function also determines the type of
mobile device used by the end user. When you call this function, the end user
receives a request to approve the collection of information for Mobile Location
Awareness.
Note: You must call this function during the onLoad event.
You can define specific parameters that help configure the information collection
for Mobile Location Awareness. For a list of these parameters, see Mobile
Location Awareness Parameters on page 50.
getGeolocationStruct - Formats the collected information into a single string. If

you call the stopCollection function during the collection, the
getGeolocationStruct function formats the information collected from the time the
onLoad event is called until the time the stopCollection function is called.
Note: You must call this function during the onSubmit event.
stopCollection - (Optional) Stops the collection of information.
Note: If you choose to stop the collection, you can call the stopCollection function
at any time after the onLoad event.
The string is posted to your organizations application and sent to the Adaptive
Authentication (On-Premise) system as part of the geoLocation element within the
DeviceRequest payload.
For information about how to collect information for Mobile Location Awareness, see
Mobile Location Awareness Parameters

RSA provides organizations with the option to define specific parameters that help
configure the information collection for Mobile Location Awareness. If you do not
specify the value for a parameter, or if the value exceeds the valid range, the default
value is used.
Note: If you choose to assign values to the parameters, you must do this before calling
the startCollection function.
When you call the startCollection () function, you must include the assigned values in
the parenthesis, with each value separated by a comma. You must position the values
according to the order of the parameters listed in the following table. For example,
startCollection (Accuracy value, Timeout value, Relevancy value, Expiration value,
aidMode value)..
Default
Parameter Description Valid Range
Value
Accuracy Threshold in meters for the accuracy of a position. This 100 5 - 200
parameter defines the radius of accuracy required to stop
the collection of Mobile Location Awareness
information. If the accuracy radius is lower or equal to
this value, then the location is no longer collected for
that transaction.
Note: This parameter is relevant for the HTML5

geolocation API.
Timeout Threshold in seconds for receiving a valid position. If no 180 90 - 300

position is received within this period, the collection of
Mobile Location Awareness information stops.
Relevancy Threshold in seconds for the age of a relevant position. If 120 60 - 240
the age of a position is lower than or equal to this value,
the collection of Mobile Location Awareness
information stops and that position is saved.
Expiration Threshold in hours for the maximum age of a cached 48 24 - 60

location. If the location is older than this value, a
location value is not returned.
aidMode The level of accuracy according to the type of collection NA See aidMode
mechanism used. Functions on
page 52 for a list
Note: This data type is relevant for the BlackBerry of available
proprietary API (version 4.1 and later). aidMode values.
aidMode Functions
The following table shows a list of aidMode functions.
aidMode Numeric
Description
Function Value
Cellsite Uses the GPS location of the cell site tower to provide first-order GPS 0
information.
Note: The cell site mode requires network connectivity and carrier
support.
Assisted Uses the network to provide short-term satellite data to the device 1
chip.
Note: The Assisted mode requires network connectivity and carrier

support.
Autonomous Uses the GPS chip on the BlackBerry device without assistance from 2
the network.
Collect Information for Mobile Location Awareness

The following procedure describes how to collect information about the location of
the end-user mobile device. It applies to the following W3C geolocation API types:
HTML5 and BlackBerry proprietary API (version 4.1 and later).
For information about which Mobile Location Awareness elements are collected, see
Note: You must apply the script to each page that requires Mobile Location
Awareness.
You must send RSA the collected information as part of the geoLocation element
within the DeviceRequest payload.
Before You Begin

(Optional) Define specific parameters that help configure the information collection
for Mobile Location Awareness. For a list of these parameters, see Mobile Location
Awareness Parameters on page 50.
To collect information for Mobile Location Awareness:

1. After the HTML page loads and before the onSubmit event, initialize the
information collection by calling the startCollection() function.
For example:
<script type="text/javascript">
// Wrapper function that calls GeoLocation
startCollection function
function geoLocationWrapper() {
startCollection();
}
// Register the wrapper function to the page loading
event
geoLocationWrapper, false);
geoLocationWrapper;
} else {
window.onload = geoLocationWrapper;
}
</script>
Note: You must call this function during the onLoad event.
2. (Optional) If you have assigned values for the parameters, add these values in the
startCollection parenthesis ().
Note: Each value must be separated by a comma. You must position the values
according to the order of the parameters listed in the table. For a list of the
parameters in the table, see Mobile Location Awareness Parameters on page 50.
For example:
startCollection(50,100,220,55,2)
3. During the onSubmit event, format the collected information into a single string
by calling the following function:
var geoLocationJSON= getGeolocationStruct();
For example:
<script>
function submitData() {
var geoLocationJSON = getGeolocationStruct();
//Send the string via SOAP request
}
</script>
Note: If you choose to stop the collection, you can call the stopCollection function at
any time after the onLoad event. The getGeolocationStruct function formats the
information collected from the time the onLoad event is called until the time the
stopCollection function is called.
4. Repeat steps 1 through 3 for each page that requires information collection for
Mobile Location Awareness.
Example of the Output for Mobile Location Awareness

{
"GeoLocationInfo":
[
{
"Status": "0",
"Latitude": "32.1593746442196",
"Longitude": "34.80888040361763",
"Altitude": "33",
"Heading": "0",
"Speed": "0",
"Timestamp": "1320814898265",
"HorizontalAccuracy": "65"
"AltitudeAccuracy": "10"
},
]
}

Integration Guide

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Integration Guide

Enviado por

Direitos autorais:

Formatos disponíveis

RSA Adaptive Authentication

Chapter 1: Encryption System ............................................................................... 5

Chapter 2: Reverse HTTP Proxy in the DMZ .................................................. 7

Chapter 3: Validating User Data ............................................................................ 9

Chapter 4: Device Information Collection ..................................................... 13

Device Print Information Set After a Successful Challenge...................................... 33

Chapter 5: Information Collection ...................................................................... 39

About This Guide

RSA Adaptive Authentication (On-Premise) Documentation

Support and Service

Customer Support Information www.emc.com/support/rsa/index.htm

RSA Solution Gallery https://gallery.emc.com/community/marketplace/rsa?

RSA SecurCare Online offers a knowledgebase that contains answers to common

Before You Call Customer Support

Database and Persistence Encryption

Key Creation and Storage

2 Reverse HTTP Proxy in the DMZ

Reverse HTTP Proxy Server

Reasons for Using a Reverse Proxy

2: Reverse HTTP Proxy in the DMZ 7

3 Validating User Data

Validating User Input

Edit the Profanity Filter

3: Validating User Data 9

To edit the profanity filter:

` < > " ' % ; ( ) & + \ # ? { } | ^ ~ [ ]

10 3: Validating User Data

Additional Data Validation Guidelines

3: Validating User Data 11

4 Device Information Collection

4: Device Information Collection 13

Accept-Language string. This language may be different than what is captured by

Mobile Device Information

14 4: Device Information Collection

Note: The collection of Device Token information is optional.

The Adaptive Authentication (On-Premise) system handles the device information

Information Stored in a Device Token

Storage of Device Tokens

4: Device Information Collection 15

Using Device Tokens

Bind and Set Device Tokens

Multiple Devices and Tokens

Device Token Checksum and Encryption

16 4: Device Information Collection

Device Token Recovery

The process of device token recovery is as follows:

4: Device Information Collection 17

Device Token Theft Detection

Collection of Device Information

18 4: Device Information Collection

During enrollment, to capture historical information on the user.

Collection of Device Print Information During Logon

4: Device Information Collection 19

Collection of Device Print Information During Enrollment

20 4: Device Information Collection

Collection of Device Print Information During Transaction Authentication

4: Device Information Collection 21

Collection of Information Using the Mobile SDK - Adaptive Authentication

22 4: Device Information Collection

Scripts for Collection of Device Print Information

4: Device Information Collection 23

Note: Do not edit this file.

Retrieval of the Device Token

Retrieve the PMData Cookie