finger-printer v1.1.1

Finger-Printer

Finger Printer is a mobile application that can authenticate desktop applications using a device's fingerprint reader.

Download the app here.

Checkout the npm repository here.

Documentation

NPM Package

To install: npm install finger-printer

To require: let fingerprinter = require('finger-printer');

Locate Device

Add Device

Callback Parameters:

• device describes the device as an object with three variables.

device.endpoint	device.hardwareID	device.deviceName
describes the ip address as a string	a unique string describing the device	a name representing the device
"10.0.1.23"	"9696a472835e0d3d"	"SAMSUNG-SM-G930V"

Example:

fingerprinter.on('addDevice', function(device) {
     //add device
});

Remove Device

Callback Parameters

• endpoint

endpoint
describes the ip address as a string
"10.0.1.23"

Example:

fingerprinter.on('removeDevice', function(endpoint) {
     //remove device
});

Find Devices

Example:

fingerprinter.findDevices();

Pair Device

Function Parameters:

• endpoint

endpoint
describes the ip address as a string
"10.0.1.23"

• applicationID

applicationID
unique string associated to an application
"ASDF34JDBN2H..."

• label

label
A string describing the application
"My Application"

• username

username
Desired username for user
"User1234"

• salt

salt
A random string that is included during the hashing process of the pairing
"My Application"

Callback Parameters:

• success

success
describes the success of the pairing process
true | false

• data describes the data associated with the request.

data.success	data.username	data.command	data.message	data.uniqueKey	data.hardwareID
describes the success of the pairing process	username paired with application	request command	additional message data	uniqueKey associated with user and application	a unique string describing the device
true | false	"user1234"	"pair"	"ran pair"	"BF5C9D7ASDF32NDFNU31..."	"9696a472835e0d3d"

Example:

fingerprinter.pair(endpoint, applicationID, label, username, salt, function(success, data) {
     if (success) {
          success();
     } else if (data.message == "already paired") {
          error("Device is already paired with this application. Maybe you want to login?");
     } else if (data.message == "i am already connected") {
          error("Device became unavailable.");
     } else if (data.message == "close" || data.message == "error" || data.message == "ran pair") {
          error("Device timed out. Please try again.");
     } else {
          error("Unexpected response. Please contact an administrator.");
     }
});

Authenticate Device

Function Parameters:

• endpoint

endpoint
describes the ip address as a string
"10.0.1.23"

• applicationID

applicationID
unique string associated to an application
"ASDF34JDBN2H..."

Callback Parameters:

• success

success
describes the success of the authentication process
true | false

• data describes the data associated with the request.

data.success	data.username	data.command	data.message	data.uniqueKey	data.hardwareID
describes the success of the authentication process	username authenticated with application	request command	additional message data	uniqueKey associated with user and application	a unique string describing the device
true | false	"user1234"	"authenticate"	"ran authentication"	"BF5C9D7ASDF32NDFNU31..."	"9696a472835e0d3d"

Example:

fingerprinter.authenticate(endpoint, applicationID, function(success, data) {
     if (success) {
          success();
     } else if (data.message == "i do not know that applicationID") {
          error("Device does not know this application. Maybe you want to register?");
     } else if (data.message == "i am already connected") {
          error("Device became unavailable.");
     } else if (data.message == "close" || data.message == "error" || data.message == "ran authentication") {
         error("Device timed out. Please try again.");
     } else {
          error("Unexpected response. Please contact an administrator.");
     }
});

Finger Printer Protocol

Protocol Guidelines

• The Finger Printer socket will timeout after 30 seconds.
• All Finger Printer sockets communicate on port 61597.
• Only one application can connect to Finger Printer at a time.
• If not already connected with another device, Finger Printer will send a knock-knock response per connection.
• If already connected, Finger Printer will respond with {"success":false,"message":"i am already connected"} and disconnect.

Requests

knock-knock

knock-knock responds with a unique hardwareID for the device and deviceName describing the devices name to the network. If not already connected with another device, Finger Printer will automatically respond with a knock-knock response when a connection is initialized.

Request:

{
     "command": "knock-knock"
}

Response:

{
     "success": true,
     "command": "knock-knock",
     "hardwareID": "9696a472835e0d3d",
     "deviceName": "SAMSUNG-SM-G930V"
}

pair

A pair request will add a new user to the Finger Printer device's local database. The user's application will also be added to the local database if not done so already. A user can only be paired once.

Parameters:

• applicationID is a unique string used to identify an application for authentication requests. This is hidden from the user.

• username is the given username of the user.

• label is the name of the application. This is displayed to the user.

• salt is a random string that is included during the hashing process of the pairing.

Request:

{
     "command": "pair",
     "applicationID": "213af32",
     "label": "Example Application",
     "username": "user1234",
     "salt": "ejin2ns12"
}

Successful Response:

{
     "success": true,
     "username": "user1234",
     "command": "pair",
     "message": "ran pair",
     "uniqueKey": "BF5C9D78A667D8E8D8BD741422AB6027CA7E7A72F8FF3EAB9AF84CC32C841214",
     "hardwareID": "9696a472835e0d3d"
}

Unsuccessful Response (already paired):

{
     "success": false,
     "command": "pair",
     "message": "already paired"
}

Treat the uniqueKey and hardwareID as a password. Hash and salt it in your database. Every successful authentication response will contain an identical uniqueKey and hardwareID.

authenticate

An authenticate request will authenticate an application. Because Finger Printer can contain multiple users per application, the username to authenticate with will be selected by the user in the app.

Parameters:

• applicationID is a unique string used to identify an application for authentication requests. This is hidden from the user.

Request:

{
     "command": "authenticate",
     "applicationID": "213af32"
}

Successful Response:

{
     "success": true,
     "username": "user1234",
     "command": "authenticate",
     "message": "ran authentication",
     "uniqueKey": "BF5C9D78A667D8E8D8BD741422AB6027CA7E7A72F8FF3EAB9AF84CC32C841214",
     "hardwareID": "9696a472835e0d3d"
}

Unsuccessful Response: (Unknown applicationID)

{
     "success": false,
     "command": "authenticate",
     "message": "i do not know that applicationID"
}

Treat the uniqueKey and hardwareID as a password. Hash and salt it in your database. Every successful authentication response will contain an identical uniqueKey and hardwareID.

Other Responses

Unkown Command:

{
     "success": false,
     "message": "i do not understand that command"
}

Internal Error:

{
     "success": false,
     "message": "java.lang.IllegalStateException: Not a JSON Object...'"
}