CS3205

This project is to develop a security-focused component subsystem of a prototype web/internet based software system for health care, responsible for maintaining, inputting and displaying timestamped health records of various types.

CS3205 SubSystem 3

• This subsystem is on involving data collection from sensors.
• A smartphone based interface will be used to access the database, which provides for authentic generation of data, associated with a particular patient.

Introduction

Stack: Jersey Server / Java Tomcat / CentOS

This application server is most of the part a proxy to server 4. Resource Server Connector proxies two main subsets of functionalities in the two sub-resources (Authorization and Health Session) to the authentication endpoints and the health session upload endpoints. Authorization sub-resource also internally/independently handles authorization for a login session of the mobile app through the issuance, verification, and refresh (sliding-session style) of a short-lived bearer token, which is handled by the Security Util module. This Security Util module is also responsible for generating fake salts and challenges for the Authenticator module in an attempt to protect against username probing.

1. Main Resource

   This is a router to redirect requests to the appropriate module (Authorization or Health Session sub-resource). Before being handled by these module, though, clients are verified against an authenticator to ensure the identity of the client entity.

2. Authenticator

   Authenticator authenticates clients trying to log in (with the use of challenge-response schemes described in the Mobile App section) and ensures that they are authenticated and authorized to access the resources being requested. Requests into protected sub-resources without correct authentication are rejected with Unauthorized responses (status code 401).

   a. Authenticating for Authorization Sub-resource

   The module, through the Resource Server Connector, proxies requests to server 4 to authenticate clients using 2 challenge-response schemes for 2 authenticating factors - password and NFC secret (refer to the authentication schemes section for more details). Clients need to provide valid responses for both the one-time password challenge and the one-time NFC challenge to be able to get granted access to the Authorization Sub-resource, otherwise the application server 3 proxies other requests to server 4 to generate new challenges for client, also passing back rate-limiting controls to the client. Failure to authentication oneself will results in a 401 response along with an error message.

   b. Authenticating for Health Session Sub-resource

   For authentication into Health Session Sub-resource, clients need to provide the password authentication claim in the form of the bearer token granted by the Authorization Sub-resource in order to request a new one-time challenge for the NFC authentication, again, through proxying to server 4, and response correctly to this challenge, and still, together with the bearer token aforementioned, so as to be granted access. Otherwise, a 401 response is returned along with an error detail message.

3. Authorization Sub-resource

   Authorization Sub-resource issues, verifies, and reissues/refreshes JWTs used as a Bearer token to grant to clients the password authorization factor, which needs to be used in conjunction with the NFC authentication factor to make requests to the Health Session Sub-resource. The tokens are short-lived and if not refreshed in due time, will expire, and clients will have to re-authenticate with this module again.

4. Health Session Sub-resource

   Authenticated and authorized clients make POST requests here to upload health session data to server 4, providing metadata as query parameters and passing the file content as octet stream directly in request body.

5. Security Utilities

   This module generates and verifies (the signature, the claim payload, and the expiration of) the JWTs as well as generating hashed strings for use as fake salt/fake challenge for non-existing username. Java’s security and crypto classes are used for hashing and Base64 is used as the encoding format.

6. Resource Server (Server 4) Connector

   The Application Server makes use of self-signed SSL truststore/keystore context in all connections to server 4’s https server to ensure the identity of the remote resource server. All the request APIs also support asynchronous invokers in order to optimize traffic to the get challenge endpoint by issuing multiple requests to server 4 at the same time.

APIs

Note that a) all paths can be prefixed with /api, e.g. /api/oauth/token or /api/session;

1. /oauth/token Body

{
    "grant_type": "password",
    "username": "theusername"
}

Headers:

• Authorization: Basic <Base64EncodedResponseForPasswordChallenge>
• X-NFC-Response: <Based64EncodedResponseForNFCChallenge>

Response:

• No header: 401 along with headers WWW-Authenticaticate and NFC-Challenge
• With correct headers: 200 with a json with token_type = Bearer and access_token=access.token.here. This token is valid for 15 minutes and will be refreshed for each subsequent requests to endpoints in protected realm session

2. Authenticate yourself when sending GET/POST request to /session/{type} endpoint by
   a. including the header Authorization: Bearer access.Token.Here
   b. including the header X-NFC-Response: <Based64EncodedResponseForNFCChallenge>

   2.1. GET https://cs3205-3.comp.nus.edu.sg/session: -> links (not used)

   2.2. GET https://cs3205-3.comp.nus.edu.sg/session/{type} with {type} as a string that begins with either step, heart, image or video (i.e. /steps or /heartrate also works) -> Retrieve session

   2.3. POST https://cs3205-3.comp.nus.edu.sg/session/{type}?timestamp={timestamp}

Body: the content of the files (steps,image,video) or the heartrate (heart) -> Upload data

About this repository

This repository is on the web server of subsystem 3.

Site Map

• Google Docs for consolidating documents
• Google Docs for the report
• Repository for mobile application