2.6. Security model

This section provides the rules and recommendations to secure the FDS specifications for the Push and Pull Models.

FDS is not defining a security API specification. It leverages the existing widely used security protocols and provides a minimum set of requirements to configure these protocols

  • TLS

  • OAuth2

It is also strongly discouraged for anyone to implement their own security model. To do it correctly requires a lot of skills and significant resources, and there are numerous third-party providers and libraries available that supply certified implementation of the protocols.

2.6.1. Definitions

Common definitions

2.6.1.1. Security

Threat Agent
An individual or group that can manifest a threat to exploit the assets of a company and use them against the company

The hacker was the threat agent who accessed the private files

Threat Vector
A path or a means by which a threat agent gains access to assets by exploiting computer systems’ vulnerabilities

The ransomware attack was the threat vector that seized control of the database

Shared Responsibility Model
A security framework that dictates the security obligations of all actors and infrastructure in a computer transaction to ensure accountability for different aspects of security and how they must work together to ensure full coverage

Our shared responsibility model includes the system administrator implementing the firewall and all users changing their passwords frequently

Authentication
The process of verifying the identity of a person or device

Providing a username and password authenticate who you are

Authorization
A security mechanism to determine access levels related to the information provider’s resources

Only machine’s owner is authorized to access information about this cleaning machine

Certificate
A unique, digitally signed document which authoritatively identifies the identity of an individual or organization.

The google certificate ensures that you are accessing the google web site

X.509 Certificate
A digital certificate based on the X.509 standard which defines the format of public key infrastructure certificates. They are the certificates used in internet communication security

The google certificate is a X.509 certificate

TLS
Transport Layer Security is a cryptographic protocol designed to provide communications security over a computer network

HTTPS connection uses TLS to encrypt the data

2.6.2. Security Threats

Digital security threats and risks are constantly evolving, and multiple global organizations are dedicated to constantly monitor new threats and provide standards, guidance, and best practices to mitigate them. Some of the organizations FDS will monitor include

  • The Open Web Application Security Project foundation (OWASP)

  • The Common Weakness Enumeration list (CWE)

FDS will monitor the work of these organization to assess its level of responsibility in a shared responsibility model and to ensure compliance at its level of responsibility. The following matrix provides the shared responsibility model based on the threat agents in the FDS specific ecosystem

../_images/security_shared_responsibility_matrix.png

2.6.3. Resources

It is assumed that the reader is familiar with the mainstream security protocols including TLS, OAuth2, and OpenID Connect. For more information the following provides additional resources that were recommended by the FDS members:

2.6.4. FDS compliance requirements

2.6.4.1. Web API

These requirements apply to

  • Information providers who expose endpoints through the Web API (Pull Model)

  • Client Applications that expose Webhooks endpoints through a Web API when implementing publish/subscribe architecture (Push Model)


  • All communication to a web server must be secure through a HTTPS connection

  • All data must be encrypted using the TLS 1.2 protocol

  • When exposing endpoints through a web server, the provider must manage access to the endpoints through a dedicated Authentication and Authorization Server

    • The provider must authenticate the client application accessing the web server through the Authentication and Authorization Server

    • The provider must identify and authorize the resource owner accessing an endpoint through an OAuth2 token

  • The information provider must identify a resource owner through a subscription ID

    • The subscription ID must have a UUID V4 format

  • The OAuth2 token must include the subscription ID

2.6.4.2. MQTT

Note

FDS mentioned that it will not specify any underlying technology for the Push Model, such as MQTT. However, when it comes to security, there are few requirements in order to maintain shared security responsibility

  • All data must be encrypted using the TLS 1.2 protocol

  • Both publisher and subscriber MQTT clients must use X.509 certificates for authentication with the Broker

  • Whoever manages the MQTT Broker must issue and manage the X.509 certificates for the clients

  • Client applications subscribing to MQTT topics must open a separate connection for each resource owner it manages information on behalf of

    • The MQTT client ID required in the connection process must be the subscription ID provided by the information provider

  • Whoever manages the MQTT Broker must implement topic permissions to ensure that a subscriber MQTT client can only subscribe to topics that contain its own client ID (subscription ID)

  • Whoever manages the MQTT Broker must only allow publish operation for information providers

  • Whoever manages the MQTT Broker must only allow subscribe operation for information consumers/client applications

2.6.5. Workflow

2.6.5.1. Securing the Web API

OAuth2 specifies four ways for a client application to obtain an access token on behalf of the resource owner: authorization code flow, implicit, resource owner password, and client credential. Which grant method to use is negotiated between the information provider and the client application.

FDS strongly recommends to use the OAuth2 authorization code flow to obtain the access token

  • When the resource owner enters a business agreement with the information provider, the information provider supplies the credentials for a resource owner’s user to authenticate on the information provider’s Authentication and Authorization Server.

  • As part of the business agreement, the resource owner gives its consent for the client application of its choice to access the information on behalf of the resource owner

  • The information provider generates the credentials for the client application to connect to the Authentication and Authorization server

    • FDS recommends that, at a minimum, the information provider generates a client ID/Client Secret credentials, and strongly recommend to use a X.509 certificate instead of a client ID/Secret

  • The information provider supplies the client application credentials to the client application’s system administrator

  • During an initialization and setup process, the resource owner’s user logins to the client application

  • This triggers the OAuth 2 code flow sequence

    • The client application connects and authenticates with the Authentication and Authorization Server

    • The resource owner’s user is asked to enter the credentials to access the resources from the information provider

    • Once authenticated and after a sequence of exchanges between the client application and the Authentication and Authorization Server, the client application receives

      • an access token

      • a refresh token

  • The access token is provided in the header to all web requests and is used by the information provider to authorize the request

  • The refresh token is used by the client application to request a new access token when it is about to expire

As long as the client application manages the renewal of the access token, the resource owner’s user only has to authenticate once. This flow provides an efficient way

  • for the information provider to ensure that only the resource owner is authenticated and authorized to access the information

  • for the resource owner’s user to have to authenticate just once

  • for the client application to make web API requests on behalf of the resource owner by providing the access token

  • and for the information provider to authorize each request by checking the subscription ID in the access token

The following diagram provides the description of this recommended security workflow.

../_images/security_pull_model_workflow.png

2.6.5.2. Securing a MQTT environment

The MQTT specifications only contain guidelines in terms of security. The FDS specifications provide some added requirements and do not impose any implementation.

FDS strongly recommend to only use MQTT implementation providers that comply with the FDS requirements

  • Ensure that the MQTT implementation only support TLS 1.2 encryption on top of the TCP transport Protocol

  • Ensure that the Broker can be configured to allow MQTT clients to be publisher only, subscriber only, or both

  • Ensure that the Broker has the capability to segregate which topics can be accessed by which MQTT client

  • Ensure that the client ID can be defined as a subscription ID UUID

When the resource owner enters a business agreement with the information provider, the client application used by the resource owner and the information provider agree to use MQTT to implement the push model. The MQTT Broker can be administered either on the client application side or the information provider side, and the term Broker Administrator will be used for the rest of this workflow. In order to initialize and setup the MQTT environment

  • The information provider supplies the subscription ID to the Broker administrator

  • It is strongly recommended that the information provider also issues and manages the X.509 certificate for the resource owner

  • The Broker administrator configures the Broker such that

    • the client application can only connect to the Broker as a subscriber

    • the information provider’s server can only connect to the Broker as a publisher

  • The Broker administrator configures an Access Control List (ACL) or equivalent such that

    • any MQTT connection from client with the ID <subscription_id> can only subscribe to topics that start with

fds/v2/<subscription_id>/...

  • Once the environment is configured, both the client application and the information provider server can open their MQTT client connection to the Broker

The following diagram provides the description of this recommended security workflow.

../_images/security_push_model_workflow.png

2.6.6. Use case example

Note

Join FDS to get access to examples and use cases.