Implementation Documentation for Keystroke Authentication API

This repository contains codes for keystroke authentication API, keystrokes logger and the swagger API documentation.

Keystroke Authentication API

The keystroke authentication api is the official api for interfacing with our keystrokes dynamics authentication which is built with Flask.

Retrieving Secrets From Google Secret Manager

We wrote a function that calls the secret.py file to retrieve secrets as shown below.

from secret import GoogleSecret
def getSecrets(key1, key2):
    result = GoogleSecret.get_all()
    secret1, secret2 = result.get(key1), result.get(key2)
    return secret1, secret2

Basically, we would be retrieving two secrets from Google Secret Manager. First is the salt_iv_B and the second is DB_password. This function is called in our code as shown below:

salt_iv_B_key = ''
db_key = ''
salt_iv_key, DB_password = getSecrets(salt_iv_B_key, db_key)

Setting Up Flask and Database Connection

The API was built with Flask running with MYSQL database. It is important to update the DB_name, DB_user and host in order to establish a connection to the database.

app = Flask(__name__)
DB_name = 'soteria'
DB_user = 'root'
host = 'localhost'
CORS(app)
logging.getLogger('flask_cors').level = logging.DEBUG
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
app.config['SQLALCHEMY_DATABASE_URI'] = 'mysql://'+DB_user+':'+DB_password+'@'+host+'/'+DB_name
db = SQLAlchemy(app)

Launching the API

1. Run the keystroke_auth_api.py file. If at production, you should change debug=True to debug=False before running the file.
2. To automatically create the database tables, enter the below codes in the terminal.

export FLASK_APP=keystroke_auth_api
flask shell
from keystroke_auth_api import db
db.create_all()

Keystrokes Logger File

Two javascript files have been provided to unintrusively capture user's keystrokes data while they attempt to login. The logger_username.js is used to capture keystrokes data from the username field, while the logger_pwd.js capture keystrokes data from the password field. Each of the javascript files will be added to their respective HTML pages. To use this code, please follow the steps below.

1. Add the line below into the html code. Kindly change the "path" to the path where the logger_username.js file is. Do the same on the password login page.

<script src="<path>/logger_username.js"></script>

2. For the scripts to work, these IDs must be used for the username, password and the form: login_form, username and pwd. See example below.

# In the username login page.
<form id="login_form" method="POST">
   <input type="text" id="username" name="username" placeholder="Username">
   <input type="submit" id="login" value="Login">
</form>

# In the password login page
<form id="login_form" method="POST">
    <input type="password" id="pwd" name="pwd" placeholder="Password">
    <input type="submit" id="login" value="Login">
</form>

3. You can add code to make POST request to Gluu endpoint in the function below. The captured user's keystrokes data can be accessed with the variable name k_data in the function. This function can be found in the logger.js file.

// Handle the login form submit
lform.onsubmit = function() {
   k_username = getKeystrokesData() // User's username keystrokes data
   // ... Add codes to send POST request to Gluu endpoint if neccessary
};

Automated Unit Tests

The automated unit tests can be done by running the api_test.py file. This test script contains a total of 7 tests.

• Test 1: is for enrollment (creating user's profile) when `/validate` is called.
• Test 2: is for a successful keystroke authentication.
• Test 3: is for a failed keystroke authentication.
• Test 4: is for testing how the api responds when invalid data is posted.
• Test 5: is for a successful profile updating when the `/notify` endpoint is called.
• Test 6: is a failed profile updating attempt because there was nothing to update.
• Test 7: is also a failed profile updating attempt because invalid input was posted.

Swagger API Documentation

The Swagger api documentation can be found here https://8f1e-67-249-20-200.ngrok.io/swagger_api/.