Index

TN-SWEKEY-001
Enabling Swekey Authentication for your Web Site

Targeted Audience

 This document is intended for to web masters who want to use Swekey Authentication in their web sites.

Introduction

The Swekey is a USB dongle that can be authenticated from any web site.
This document describes how to modify your web site in order to be able to verify the physical presence of a Swekey on the user’s computer.

Swekey Authentication Explained

Basics

Each Swekey has a unique identifier (Swekey ID).
Swekey authentication is based on One Time Passwords (OTP).
OTP are generated by the Swekey and are verified by an Authentication Server.
For obvious security reasons, the Swekey must generates a unique OTP each time.
To make sure the OTP will be unique, the Swekey requires a random token (RT) to generate an OTP.
The RT is generated by a Token Server.

The 4 authentication steps

Check if a Swekey is connected to the PC and get its Swekey ID
Get a Random Token (RT) from the Token Server
Ask the connected Swekey to calculate the OTP from the RT.
Send the Swekey ID, RT, OTP triplet to the Authentication Server for validation.

The 3 authentication elements

The Swekey Identifier (Swekey ID)

The Swekey identifier is a 128 bits value.
It is encoded in a 32 char long hexadecimal string.
The hexadecimal digits are always upper case.
A typical Swekey ID will look like this:
0100000000000000000013D90003F962

The Random Token (RT)

A random token is a 256 bits value.
It is encoded in a 64 char long hexadecimal string.
The hexadecimal digits are always upper case.
A Random Token has a limited validity period.
Once generated by the token server it remains valid only 2 minutes.
A typical RT will look like this:
8B8373D4952B58CC598DD60CF6D9A3D88B465771A59EC4DC45C311501D7C15A9

The One Time Password (OTP)

A one time password is a 256 bits value.
It is encoded in a 64 char long hexadecimal string.
The hexadecimal digits are always upper case.
Since the Random Token has a limited validity period,
the OTP remains valid only while its RT is valid.
A typical OTP will look like this:
A3D88B465771A59EC4DC45C311501D7C15A98B8373D4952B58CC598DD60CF6D9

Communicating with the Swekey

To get the Swekey ID of the connected Swekeys and to query the OTP from them you must use an Activex or a Netscape plugin depending on the used browser.
Both Activex and Plugin are automatically installed on the PC when a Swekey is plugged in.  
So if your page doesn’t detect those components, it means that no Swekey is plugged.
Mac and Linux users have to install it manually from here.

To ease communnication with the swekey via the plugin, a fully documented Java Script file (swekey.js) is provided in the Swekey SDK. Feel free to include it in your pages.
If you don't want to use this file, you must embed the swekey plugin in your page yourself using the following line:
    <embed type="application/fbauth-plugin" width=1 height=1 hidden="true" id="swekeyplugin"><br>

Communicating with the Authentication Servers

Communication with Authentication and Token Servers is done using simple HTTP requests.

Asking for a RT

To get a RT, you must send a query to the “auth-rnd-gen.musbe.net” server.
The complete URL is: http://auth-rnd-gen.musbe.net/FULL-RND-TOKEN
The reply to the query will be a 64 char string containing the RT.
You can try it directly from your web browser to see the result.

Verifying an OTP

To verify an OTP, you must send a query to the “auth-check.musbe.net” server.
The complete URL is: http://auth-check.musbe.net/ CHECK-OTP/<Swekey ID>/<RT>/<OTP>
 The reply to the query will be the text “OK” or “ERROR:xxx”.
You can try the following URL directly from your web browser to see the result: http://auth-check.musbe.net/CHECK-OTP/0100000000000000000013D90003F962/8B8373D4952B58CC598DD60CF6D9A3D88B465771A59EC4DC45C311501D7C15A9/A3D88B465771A59EC4DC45C311501D7C15A98B8373D4952B58CC598DD60CF6D9 You should get: ERROR:910
This means that the used RT is no longer valid.
The possible errors are as follows:

PHP api

To facilitate the conception of php sites we provide in the Swekey SDK a fully documented php include that contains APIs to connect the servers.

Security and Performance Issues

HTTP is not very secure, nor scalable. If your site requires higher security level, lower authentication time or thousands of authentications per second you can have access to dedicated servers with secured and asynchronous protocols. Please contact Musbe, Inc. (info@musbe.com) to get access to those servers, and the according documentation.

Use the SDK

To make the integration of the Swekey technology in your web site easier, you should download the Swekey SDK. It contains fully documented include files and sample html pages.