Android

The Swivel Android Client Overview

For version 2 of the Swivel Android client see Android 2.0

Swivel Secure now offers an Android client for use with the Swivel platform. This article explains how to download, configure and use this client. For the Java Applet version see Swivlet How To Guide, for the Windows Mobile version see Windows Mobile How To Guide, for the iPhone client see IPhone. For the BlackBerry Client see Blackberry.

Prerequisites

Android Phone

The Swivel virtual or hardware appliance must be reachable from the mobile phone to receive security strings

Access device for authentication

The index is required to be entered as nn on the end eaxample: 292401, Swivel versions earlier than 3.10 require ,nn example: 2924,01 otherwise it will see it as a dual channel authentication.

Virtual or hardware appliances using Swivel 3.8 may require an upgrade on their proxy to provision a mobile device, see Appliance Proxy Server Upgrade

RADIUS authentications made against Swivel must use PAP RADIUS authentication since with other RADIUS protocols such as CHAP and MSCHAP the access device requests the OTC from Swivel.

Swivel Configuration

Configuring Mobile Client user access on the Swivel virtual or hardware appliance

To allow a user to authenticate using a One Time Code from the Mobile Phone Client, the user must have the Mobile Client authentication enabled. To do this on the Swivel Administration console ensure that the group they are part of has access to the Mobile Client under Repository Groups.

Configuring the Swivel Authentication

Swivel can authenticate users using the mobile client to authenticate by RADIUS or Agent-XML authentication

• For RADIUS authentication see RADIUS Configuration Note: The access device connecting to the Swivel RADIUS must be configured to use PAP for authentication.

• For Agent-XML authentication see XML Authentication Configuration

• To display to the user a the number of the Security String or One Time Code to use, see Mobile Security String Index

Mobile Provisioning

Swivel 3.8 and higher requires each mobile phone to be provisioned so it can be uniquely identified. Ensure that all Mobile Client users have suitable Transports configured to receive their Provision Code. To provision the mobile client select the user and click Re-provision. Earlier versions of Swivel do not need to use a Mobile Provision Code. See Mobile Provision Code.

Mobile Client Policies

For the Server based policies see Mobile Client Policies

Android Installation and Configuration

Installing the Android Client

The Swivel Android client is available from the Android Market place and can be downloaded directly onto the mobile phone.

Alternatively to find the application go the Android Marketplace https://play.google.com and search for "swivel secure".

The pinsafe.apk file may also be uploaded by various utilities such as Droid Explorer, the Android Marketplace is the preferred method of deployment. A Swivel version for testing is available here Swivel Android Client

Configuring the Android Client App

When you launch the Android Client select Settings on the main screen, the option to select a 3.8 and Above server can be made.

Get Server Settings

If a SSD server is being used, then select Get Server Settings and enter the Server ID, otherwise the settings can be manually entered with information from the Swivel System administrator.

Manual entry of Server Settings

The settings are

1. PINsafe Version The Version of the Swivel server. Default pre 3.8, Options pre 3.8 or 3.8 and above
2. User Your username that you use when you authenticate via Swivel
3. Webservice URL The URL from where the client can download security strings (or keys)
4. Webservice Port The port number used by the webservice. For a virtual or hardware appliance this is 8443, for a software install this is 8080
5. Webservice Context The context used by the webservice. For a virtual or hardware appliance this is proxy, for a software install this is usually pinsafe

Once you have entered the settings return to the main Swivel screen.

Downloading Security Strings (Update Keys)

At the main menu, test the settings by Selecting the Update Keys option, at the prompt select Yes to confirm to update the keys. This will attempt to retrieve Security Strings from the Swivel virtual or hardware appliance.

You will see a brief message stating Updated Keys and then if all is well the display will return to the main menu.

If there are any problems an error message will be displayed.

You can confirm that keys have been downloaded by going to the Enter PIN screen and Entering you PIN. (Note: Version 2 does not ask for PIN entry but for additional security provides an OTC). Once you have entered your PIN you will see you extracted one-time code and the number of Security Strings (Keys) you have remaining. The Swivel virtual or hardware appliance will display the following log message Security strings fetched for user: username

The first time you do this after downloading keys, the Keys Remaining will show as 98.

Options

The following options are available:

Auto extract OTC, Prompt for PIN Number to auto-extract OTC, Options, enable/disable. This option may be turned off on the Swivel server. When enabled ths allows the user to enter their PIN number and a One Time Code will be displayed. Note that there is no error checking of the PIN, so if an incorrect PIN is entered an incorrect One Time Code will be displayed.

Allow String Browsing, This is a Swivel server controlled option, which if enabled will allow the user to browse through security strings on the mobile app.

Using the Android Client to Authenticate

To use the Swivel Android Client to authenticate is very simple.

1. Open the application on your Android
2. Select the Enter PIN Option (Note: Version 2 does not ask for PIN entry but for additional security provides an OTC)
3. Enter your PIN using the Android keypad displayed.
4. The client will show the OTC that you need to enter, (as shown above)
5. Enter the OTC into the authentication dialogue, including the ',' and the following 2 digits. e.g. 0947,00

If you need to authenticate again you can select the refresh option

Using the Android Client with ChangePIN

The client can be used in conjunction with the Swivel changePIN application to allow a user to change their PIN.

For the Swivel version 2 Android Client, the ChangePIN feature is deprecated. To use ChangePIN, view a security string and use the details to obtain an OTC and generate a new OTC.

For the version 1 client the user first accesses the change pin application in their computer browser then selects the Change PIN option on the Android Client

On the Swivel client page you first enter your current PIN, then on the next screen you enter you New PIN.

The next screen then displays the two OTCs you need to enter within the Change PIN dialogue in your browser.

Updating Keys

The client downloads 99 keys at a time and these keys are used one at a time until there are none left. However a new set of 99 keys can be downloaded at any time by using the Update Keys. Downloading keys requires network connectivity so it is recommended that you download a new set of keys before the Android Client is likely to be without network connectivity for any length of time.

Testing

When downloading security strings, the following messages should be seen Security strings fetched for user:

Known Issues and limitations

The current version only supports one device per user.

Older versions of the Android client only supports numbers for the authentication string rather than letters. If letters are set on the Swivel virtual or hardware appliance then a security string of -1,-1,-1,-1,00 is displayed. The current version supports numbers and letters.

PIN numbers may be from 4 to 8 digits in length

Version 2.0 of the client has a changePIN button, but pressing it has no effect. The ChangePIN button has been deprecated, see ChangePIN above.

Troubleshooting

Is the Swivel virtual or hardware appliance accessible on the internet

Check the connection settings to the Swivel virtual or hardware appliance

Check the Swivel logs for any error messages

Can the phone access the internet

If a RADIUS connection is seen from the access device to the Swivel virtual or hardware appliance but authentication fails, try using PAP

Download new security strings to the phone and retest

Is the OTC being entered with the comma and last two digits. E.g. 7329,62

If the proxy port (8443) on the virtual or hardware appliance is being used, ensure that it supports the proxy request of the key retrieval using AgentXML. If this is the case then contact Support for an updated version of the Proxy.

The PIN cannot be entered, version 2 of the client. For security the option to enter the PIN has been removed, instead a security string is displayed.

Login fails and User receives a security string or One Time Code by SMS or email at each login attempt. The index is required to be entered as nn or ,nn example 2924,01 otherwise it will see it as a dual channel authentication.

Error Messages

Incorrect settings - please check your settings

The settings for downloading the security strings are incorrect. Verify what has been entered, and check what the values should be.

Timed Out

The settings for connecting to the Swivel virtual or hardware appliance may be incorrect or the port is being blocked.

Failure Please check your settings or try again later. Message: At line 1, column 0: no element found

Mobile Client cannot connect to the Swivel server. Check network setting and that client has network access.

Error occurred whilst fetching security strings for user: graham, error: The user does not belong in the correct group within the user repository to continue the authentication attempt.

The user does not have permissions to use the Mobile client or Swivlet.

Host is unresolved

Hostname cannot be found, check the settings

Message Connection to http://IP_or_Hostname:8080 refused

The IP address, hostname, or port may be incorrect and the server has refused to allow a connection from the client

Failure Please check your settings or try again later

This can be caused by a Swivel Android Client configured to use Swivel 3.7 accessing Swivel version 3.8.

Message: SSL handshake failure: I/O error during system call, Unknown error: 0

This is caused by an SSL request being made against a non SSL server, check the Swivel Android Client Settings.

Failure Please check your settings or try again later Message: com.android.org.bouncycastle.jce.exception.ExtCertPathValidatorException: Could not validate certificate: current time: Tue Jun 19 11:54:52 GMT+01:00 2012, expiration time: Thu Mar 03 23:59:59 GMT 2011

SSL Certificate has expired. Install a valid certificate on the Swivel server.

AGENT_ERROR_NO_SECURITY_STRINGS, AGENT ERROR NO SECURITY STRINGS

See AGENT ERROR NO SECURITY STRINGS

Tested Mobile Phones

The following phones have been tested

Mobile Phone Compatibility

Manufacturer	Model	Version	OS Version	Operator	Compatible Y/N	Applet Version
Samsung	Galaxy	i9100	Android 2.3.3	O2	Y	1
Samsung	Galaxy	i9100	Android 2.3.3	O2	Y	2
Samsung	Galaxy	i9100	Android 4.0.3	O2	Y	2
Samsung	Galaxy	Note GF-7000	Android Ice Cream Sandwich 4.0.2	-	Y	2
Samsung	Galaxy	Mega GT - I9205	Android 4.2.2	O2	Y	-
Samsung	Galaxy	GT - I9195	Android 4.2.2	EE	Y	-

Keywords: Android, Client, Swivlet, App, marketplace