Introduction

Pre-requisites

In order to understand the next sections of this document and to successfully integrate an application with the TOTP features, it is assumed that the following pre-requisistes are met:

Have a good knowledge of the SOAP messaging protocoll.
Have a good knowldedge of the FMoP APIs and flows.
Have the ability to create proxy classes from the FMoP WSDLs.
Have access to a development environment to deploy the TOTP MCF plugin and perform integration testing.

TOTP Implementation

This MCF plugin implements the TOTP protocol as defined in RFC 6238. The plugin allows an end-user to enroll multiple mobile devices to generate a TOTP that is then to be used as part of a FMoP step-up authentication cycle.

While the TOTP MCF plugin supports a variety of intervals, OTP length and HMCAs, most TOTP applications only seem to honor 6 digits, 30 seconds and SHA-1 HMACs.

In most use cases, a TOTP instance will map to an end user’s mobile device. The maximum number of instances an end-user is allowed to enroll to is set in the configuration parameter max_totp_instances_per_user.

Each instance will be associated with the following attributes:

Attribute Name (SOAP Element)	Description
uniqueID	An alpha numeric unique identifier for a TOTP instance.
deviceName	An optional user-friendly name set by the end-user.
issuedTimeStamp	When the instance was issued, UTC timestamp.
remainingAttempts	Authentication attempts remaining before the instance is suspended.
hmacAlgorithm	The HMAC algorithm used to compute the OTP.
intervalSeconds	How frequently a new OTP is generated.
digits	The length of the OTP.
status	Lifecycle status, see next section for in-depth description.

TOTP Instance lifecycle status

Each TOTP instance is assigned a lifecycle status, as defined by the StatusType Type defined in TOTP.xsd.

This diagram summarizes the status transitions:


graph
PROVISIONED-->ACTIVE;
ACTIVE-->SUSPENDED_FAILED_AUTHENTICATIONS;
SUSPENDED_FAILED_AUTHENTICATIONS-->ACTIVE;
SUSPENDED_*-->ACTIVE;
PROVISIONED-->SUSPENDED_*;
SUSPENDED_FAILED_AUTHENTICATIONS--->SUSPENDED_*;

The meaning of the various lifecycle statuses is as follows:

Status	Can be programmatically set?	Description
PROVISIONED	No	The initial status of a TOTP instance. This status indicates that the user hasn’t successfully passed and authentication cycle yet.
ACTIVE	Yes	Once an end-user provided the correct OTP at least once, the TOTP instance will be in this status.
SUSPENDED_FAILED_AUTHENTICATIONS	No	If the end-user fails to provided the correct TOTP consecutively more than what specific in the TOTP configuratio parameter max_failures, the TOTP instance will be set in this status. The instance cannot be used for authentication until it is programmatically set back to the ACTIVE status.
SUSPENDED_LOST SUSPENDED_STOLEN SUSPENDED_FRAUD SUSPENDED_OTHER1 SUSPENDED_OTHER2 SUSPENDED_OTHER3 SUSPENDED_OTHER4	Yes	Various other statuses a TOTP instance can be programmatically set to. When in any of these statuses, the instance cannot be used to authenticate.