Key Service overview

The Keyservice is service for creating, storing and accessing 128 bit keys. The keys issued by the service are meant for encrypting users Refresh Token and/ or Client Credentials obtained from a successful login flow, in order to store the tokens securely on a device, in way that leaves accessing the tokens by brute force attacks infeasible.

The service exposes the following endpoints for creating and accessing keys:

• createKey - create a 128 bit key from a user chosen password

• getKey - access a key from a key ID and password

• getLongKey - acesss a key from a key ID and long secret

and the following endpoints for maintaining keys:

• getDevices - list keys associated with a user

• deleteDevices - delete a key associated with a key ID

Motivation

If an attacker obtained a users Refresh Token, the person could exchange the token for an Access Token (AT) from the Authorization Server, and maliciously act as the user. Therefore the Refresh Token (RT) needs to be stored securely on a users device. A naive approach is to encrypt the Refresh Token with a user chosen password. This password is usually vulnerable to brute force attacks. Therefore, we encrypt the Refresh Token with a 128 bit key, which the user can access from a web service, in such a way, that the service locks the key, if numerous invalid attempts are made at accessing the key. Thus leaving brute force attacks on getting access to the key infeasible.

Most mobile devices have a safe storage managed by the OS and protected by biometrics (finger print etc.). We would like to use this storage in some way, in order for users to authenticate using biometrics instead of a user chosen password. A naive way of supporting this would be to store the Refresh Token here. This, however, leaves us with different ways of accessing the Refresh Token, depending on if the user is authenticating using password or biometrics. Another option is to store the user chosen password in the safe storage. The app could then have the user authenticate using biometrics, retrieve the user chosen password, access the key from Keyservice, decrypt the Refresh Token and have the Authorization Server exchange this for an Access Token.

Since people generally only use one or two passwords across all their applications, a mechanism is needed to reduce the likelihood of such a security breach. Therefore, storing the user chosen password on the device is not an option, not even encrypted in some way (an attacker could also intercept the password after it is decrypted, when it is sent to Keyservice). 

When the Keyservice generates a new Key, the service also generates a 128 bit long secret. This long secret can also be used to retrieve the users Key from Keyservice, in the same way as the user chosen password. By storing the long secret in the biometrically secured safe storage on a device, if an attacker managed to access the safe storage, the potentially long list of other applications secured by the users password would not be compromised.

Usage

The following diagram illustrates how an app obtains a valid set of tokens and client credentials from an Authorization Server (Keycloak), creates a key on the Keyservice for encrypting and securely storing the client credentials and RT on a users device, and successfully uses the AT for interacting with the FUT infrastructure.

The user can now access the key and decrypt the User Credentials and Refresh Token, by interacting with the Keyservice:

Or by authenticating using bio-metrics on a mobile device, and decrypt the Client Credentials and Refresh Token using the long secret:

Keyservice management

There are 2 types of management,

1. The cleanup of keys, which can be configured (say after 2 months of inactive / not using a key), where it is simply deleted it, or that the maximum lifetime of a key is for example 1 year, that means no matter how much it is being used, it will be deleted after a year, forcing the user to do a new login.

2. The management from the users perspective, respectively to be able to view his/her's devices, and to be able to delete them.