index.bs

<pre class='metadata'>
Title: Use Cases and Requirements on HTTPS-enabled Local Network Servers
Shortname: httpslocal-usecases-requirements
Level: 1
Status: CG-DRAFT
Group: httpslocal
URL: https://httpslocal.github.io/usecases/
Editor: Contributors on GitHub, https://github.com/httpslocal/usecases/graphs/contributors
Abstract: This document describes use cases of HTTPS-enabled local network servers and requirements for their HTTPS deployment.
Repository: https://github.com/httpslocal/usecases
Markup Shorthands: markdown yes
</pre>

Introduction {#intro}
=====================

This document describes use cases where browsers communicate with
web-server-capable devices in local network via HTTP (`https://`) and/or
WebSocket over TLS (`wss://`), as well as network, security, and privacy
requirements on these usage.

Nowadays, a lot of devices like Internet-of-Things (IoT) devices and home
gateways often have their own built-in HTTP server so that they can provide
interfaces to configure and/or control them remotely via IPv4/IPv6 local
network. Modern web browsers, however, usually regard those local servers as not
trustworthy due to lack of authenticity of device's identity. As a result,
browsers would prevent trustworthy web sites from communicating to local network
devices [[MIXED-CONTENT]] and prohibit web pages on the servers from accessing
powerful features on browsers [[SECURE-CONTEXTS]].

Therefore, this document illustrates potential use cases that need access to
local network servers and clarifies requirements for use of these servers.

Use cases {#usecases}
=====================

## UC-01: Playing audio content in a home storage device from a cloud service ## {#uc-01}

Users can store their audio contents in their storage device, or set-top boxes,
in their home. They access online music web services with web browsers, and use
a music player implemented as a web application in the web services to play
music stored in their home network. The music player send metadata of the music
to the web service, to recommend another music content.

## UC-02: Video streaming with cache storage in local network ## {#uc-02}

A user has a video cache storage server for home to enjoy online video streaming
services at UHDTV quality. When she opens the web site of one of the streaming
services on her TV browser, the web page tries to find her cache storage and
displays a list of storages via a popup window. She picks up one storage from
the list to store caches of UHDTV video stream segments. After her permission,
the streaming web application of the service can start prefetching or fetching
UHDTV movies purchased or bookmarked by her and upload those segments to the
storage. When she wants to watch one of the movies cached in the storage, the
online service fetches the movie from the home storage to avoid consuming WAN
traffic, and finally she can comfortably enjoy the movie.

<figure id="fig-uc02"><img src="figs/uc02.jpg"></figure>

## UC-03: Web-based UI for home appliances (input/output constrained devices) ## {#uc-03}

A user controls home appliances (e.g. air conditioner, microwave oven,
refrigerator) with an online GUI service on the internet. The home appliances
are designed natively to be used via the online GUI loaded in a browser on her
smartphone or tablet. As with the use cases mentioned above, when she signs in
to the online service, the service finds a home appliance through the browser.
Under her approval, the service can be granted access privileges for the
appliance and she can control it through the GUI service.

<figure id="fig-uc03"><img src="figs/uc03.jpg"></figure>

## UC-04: Embedded system monitoring and controlling for display-capable devices ## {#uc-04}

A field engineer of a digital signage service provider sets up an
internet-capable display device. The engineer makes the device display a
specific website as a signage content by using a browser on the device. After
that, the website is monitoring the status of the embedded system (e.g.
collecting logs, monitoring system resource utilization) continuously via the
browser by using internal REST APIs provided by an internal web server (e.g.
https://localhost) of the device. If the device provides the website with reboot
functionality as one of the REST APIs, the service provider is able to not only
check the health of the device, if necessary, but also reboot the device
remotely via the website. This use case is about Network based API described in
NetworkedBasedAPI.md

<figure id="fig-uc04"><img src="figs/uc04.jpg"></figure>

## UC-05: Data analysis from analytical and measuring instruments in local network ## {#uc-05}

An analytical and measuring instrument in local network outputs a large amount
of raw data as the result of an experiment. An experimenter (a user of the
instrument) signs in to a web-based analytical service provided by the vender of
the instrument by using a browser in her PC. The experimenter analyzes the raw
data by using the web service and the service fetches the raw data from the
instrument directly in local network.

<figure id="fig-uc05"><img src="figs/uc05.jpg"></figure>

## UC-06: Photo sharing between online services and home NAS devices ## {#uc-06}

A user usually stores her private photos and videos in a home NAS device. She
opens an online photo sharing service in a browser on her smartphone. The online
service finds her home NAS device through the browser and shows her the NAS via
a popup window. She selects the NAS and the browser shows her private photos in
the NAS as well as the ones already stored in the online service. She then
selects and posts some photos that she would like to share with her friends or,
if she usually posts photos to the online service from her smartphone directly,
she downloads the photos and posts them to the NAS device.

<figure id="fig-uc06"><img src="figs/uc06.jpg"></figure>

## UC-07: Secure offline communication for home automation ## {#uc-07}

A user wants to set up a new home device (e.g., a Wi-Fi access point/router,
home automation gateway) in his/her home via its web interface.
User typically opens a given URL for the device (e.g., https://home-router.local, or https://192.168.1.1)
in a laptop or smart phone’s web browser. Since the new device does not have
a valid web PKI certificate, the web browser displays a warning like 
“The connection is not secure” but provides an option to ask the user to
approve the access or add the URL as an exception to the whitelist.
Once user takes the action, the web browser treats the device as a trusted one
and does not display the warning in subsequent attempts. Additionally, if the
home device supports functionality such as, SSO (Single Sign-On) the user can
use an identity (ID) provider's account (e.g., Google, Facebook, and so on)
to sign in the device’s web interface and provide the needed trust.

Similar secure access is required when a home gateway, which is typically
controlling other home devices (e.g., door locks, security cameras), 
uses HTTPS for securely accepting commands via a remote server. 
However, when a home gateway happens to get temporarily disconnected
from the internet, those home devices become inaccessible. 
In such scenarios, a local HTTPS communication from user’s
local device (e.g., smart phone or a control device) is essential to control
and operate the home devices directly through HTTPS connections over the local network.

## UC-08: Companion Device for Broadcast Interactive Service ## {#uc-08}

A user is watching a broadcast interactive service which is enhanced by a
broadcaster’s web app running on the user agent of TV. The user hands a
companion device, e.g. Smartphone, and launches a user agent with the Frontend
page from the broadcaster web server. The Frontend page discovers the user-agent
of TV and securely communicates with the broadcaster’s web application via the
Web Socket Server on TV in order to provide GUI for the interactive broadcast
service. Note that this use case is similar to the 2-UA of the Presentation API
but the difference is that the broadcaster’s web application on TV is running on
UA of TV in advance.

<figure id="fig-uc08"><img src="figs/uc08.jpg"></figure>

## UC-09: Presenting with Projector at office ## {#uc-09}

A user is attending a meeting at office (outside home). The user logs on an
online document sharing service on PC and present his document file on the
service with the Projector connected via local network. FrontEnd page on UA1 at
PC initiates to launch 2nd frontend page on 2nd UA at the projector to let the
2nd frontend page present the document. Note that this use case is similar to
2-UA of Presentation API but the communication between 2-UA should be secured to
prevent the MITM attack in the local network and also the regular WebSocket API
is used for the communication, e.g. file transfer.

<figure id="fig-uc09"><img src="figs/uc09.jpg"></figure>

Requirements {#requirements}
============================

This section outlines functional and non-functional requirements of HTTPS/WSS
usage in local network represented in [[#usecases]].

Functional requirements consist of guarantee of device trustworthiness,
device identification, alerting user and user consent, device discovery,
and certificate management.

Non-functional requirements address security, privacy, availability, scalability,
and user experience aspects of HTTPS/WSS usage in local network.

## Terminology ## {#req-terminology}

A user agent (<dfn>UA</dfn>) is a web browser on a user’s PC, smartphone, tablet
and so on, which is connected to a local network.

A <dfn>device</dfn> is in the same local network as the [=UA=], capable of HTTPS/WSS server.

A <dfn>web service</dfn> is a service hosted on the internet and whose frontend is
loaded on the [=UA=], which accesses to the [=device=] with HTTPS or WSS on the local network.

A <dfn>Web PKI certificate</dfn> is a TLS server certificate that can chain up to
a root CA (Certificate Authority) trusted by the [=UA=]  (preinstalled on the [=UA=]).

A <dfn>non-Web PKI certificate</dfn> is a TLS server certificate that cannot chain
up to a root CA, or a self-signed certificate.

A <dfn>CA</dfn> (merely called `CA` in this document) is a CA responsible for issuing the [=Web PKI certificate=]s or [=non-Web PKI certificate=]s.
It is not restricted to a CA responsible only for issuing the [=Web PKI certificate=]s.

A <dfn>private CA</dfn> is a CA responsible for issuing the [=non-Web PKI certificate=]s.

## Functional Requirements ## {#req-functional}

The functional requirements are listed below:

- Guarantee of Device Trustworthiness
- Device Identification
- Alerting User and User Consent
- Certificate Management
- Device Discovery

In the following, we elaborate on individual requirements as mentioned above.

### Guarantee of Device Trustworthiness ### {#req-guarantee-of-device-trustworthiness}

The [=UA=] accesses the [=device=] with TLS (HTTPS or WSS) in all of the use cases envisioned so far.
If the [=UA=] cannot trust the [=device=]’s TLS server certificate,
the [=UA=] shows a warning message that means the [=device=] cannot be trusted.
To avoid it, the [=device=] shall have a way to prove its trustworthiness to the [=UA=].

Getting a [=Web PKI certificate=] is one of the ways to prove the [=device=] trustworthiness
but the [=Web PKI certificate=] only works for globally unique domains,
which must be registered in public DNS servers. For this scenario, the requirement is that
- The [=device=] has a [=Web PKI certificate=] and has a way to obtain it.

However, one may choose to use a memorable simple private domain name (e.g., “myprinter.local”)
or may not want to register the [=device=] name to the public DNS server because of
privacy concerns. In such scenarios, it is better not to use the [=Web PKI certificate=] for the [=device=],
however, the [=device=] and/or the [=UA=] shall have one of the following features or methods:
- The [=device=] has a way to obtain and use a [=non-Web PKI certificate=] and
    the [=UA=] has some out-of-band mechanisms to validate the certificate as a trusted one
    (e.g., the user and/or the web service’s approval).
- The [=device=] does not have a certificate but the [=UA=] has a way to validate
    and trust the [=device=] without any certificates (e.g., by using a PSK (pre-shared key)
    or an RPK (raw public key)), which is shared to the [=UA=] in a secure way.

### <dfn>Device Identification</dfn> ### {#req-device-identification}

In case that the user inputs the device URL to the address bar of the [=UA=] directly ([[#uc-07]])
or the [=UA=] shows the popup window to the user to get the user's consent ([[#uc-02]], [[#uc-03]]),
the user may be able to recognize that the device URL displayed or input on the [=UA=]
indicates the real device on the local network. In such cases, the [=device=] and/or
the [=UA=] shall meet the following requirements:
- The device identifier (domain name) should be easy to remember and short enough but
    not to recognize as fraudulent by anti-phishing.
- The [=device=] and the [=UA=] should have a pairing method by using the device
    interface (e.g., pushing a specific button on the [=device=] to start the pairing,
    showing the PIN code for the pairing on the [=device=]’s display).

### Alerting User and User Consent ### {#req-alerting-user}

The frontend of the [=web service=]  loaded on the [=UA=] should not be able to access the [=device=]
without an explicit approval from the user especially during its first time access.
This is essential in cases where the [=device=] is not capable of using a [=Web PKI certificate=].
In such cases, the [=UA=] will possibly use an alternative identifier (e.g., [=non-Web PKI certificate=], PSK, RPK)
but it must not be trusted without the user’s consent.
Therefore, considering the [=UA=] shall meet the following requirement:
- When the frontend of the [=web service=] requests the [=UA=] to access the [=device=] in local network,
    the [=UA=] shall show a popup window to obtain the user’s consent and shall permit
    the access only if the user approve the access.
- When the [=device=] does not use a [=Web PKI certificate=] for HTTPS/WSS communication,
    the [=UA=] shall have a way to obtain user’s consent to trust an alternative identifier
    (e.g., [=non-Web PKI certificate=], PSK, RPK).

### Certificate Management ### {#req-certificate-management}

When the [=device=] obtains a TLS server certificate for HTTPS/WSS communication,
the [=CA=], [=UA=] and the [=device=] shall meet the following requirements:
- The [=CA=] that issues certificates for [=device=]s shall be able to revoke the certificates.
- The [=UA=] shall be able to detect the revocation of the [=device=]’s certificate.
- The [=device=] shall be able to refresh the certificate at any time.

### <dfn>Device Discovery</dfn> ### {#req-device-discovery}

As described in [[#uc-02]] and [[#uc-03]], when the [=web service=] does not know the device URL in advance,
the [=device=] needs to be discovered. That means the discovery process must meet the following requirements:
- The [=UA=] shall be able to discover the presence of [=device=]s in the same local network.
- The [=UA=] shall be able to obtain the endpoint URL of the [=device=] that has the scheme `https://` or `wss://`.
- When the [=UA=] finds multiple [=device=]s, the [=UA=] shall be able to present the selector interface
    to display the list of the [=device=]s and allow the user to select one specific [=device=].

## Non-Functional Requirements ## {#req-non-funcational-req}

The non-functional requirements are listed below:
- Security
- Privacy
- Availability
- Scalability
- User Experience

### Security ### {#req-security}

It is essential to take care of the following security considerations:
- If the [=device=] uses a TLS server certificate for HTTPS/WSS communication,
    the certificate issuance and renewal steps shall prevent passive network
    eavesdroppers from learning information related to the identification or certificate
    exchanged among the system components (the CA, the [=device=], the [=UA=] and the [=web service=]).
- If the [=device=] uses a TLS server certificate for HTTPS/WSS communication,
    the certificate issuance and renewal steps shall prevent active network attackers
    from impersonating a [=device=] and observing or altering data intended for the [=CA=] or for the [=UA=].
- If the [=device=] does not use a TLS server certificate, alternate steps for the [=UA=]
    to initiate a TLS session to the [=device=] (e.g., sharing and using a PSK or a RPK)
    shall prevent passive network eavesdroppers from getting the PSK or the private key of the RPK.
- If the [=device=] does not use a TLS server certificate, alternate steps for the [=UA=]
    to initiate a TLS session to the [=device=] (e.g., sharing and using a PSK or a RPK)
    shall prevent active network attackers from impersonating a [=device=] and observing or
    altering the keys for the [=UA=].
- [=Device identification=]  (e.g., the pairing method mentioned above) shall prevent
    passive network eavesdroppers from learning information related to identification.
- [=Device identification=] and [=device discovery=]  (if the [=UA=] supports it) shall prevent
    active network attackers from impersonating a [=device=] and observing or altering
    data intended for the [=CA=] or for the [=UA=].

### Privacy ### {#req-privacy}

The user privacy shall be preserved against the [=web service=] especially when the user
allows the frontend of the [=web service=] to access the [=device=] for private use.  In such scenarios,
the [=UA=] and the [=device=] shall meet the following requirements:
- When the [=UA=] supports [=device discovery=] functionality mentioned above and the [=UA=] finds
    multiple [=device=]s, [=UA=] shall disclose only one [=device=] selected by the user.
- To avoid disclosing the device name and the IP address to the internet,
    the [=device=] should be able to use a private domain name.
- To avoid user tracking by means of using the [=device=], the evice identifier
    (e.g., a TLS server certificate for the [=device=]) should not be static and preinstalled.
    The [=device=] should be capable of obtaining the TLS server certificate dynamically
    for HTTPS/WSS communication during commissioning.

### Availability ### {#req-availability}

In scenarios (e.g., [[#uc-07]]) when the [=device=] and the [=UA=] gets temporarily disconnected from the internet,
the [=UA=] and the [=device=] should be able to communicate with each other on the local network.
Therefore, the [=device=] and the local network system shall meet the following requirements:
- When the [=device=] has a private domain name (e.g., *.local, *.home.arpa)
    or a private IP address, a [=private CA=] shall be able to issue a TLS server certificate for the [=device=].
- If the [=device=] has a public domain name, the local network system should have a way to help
    the [=UA=] with resolving the public domain name without an internet connection
    (e.g., without querying a public DNS server).

### Scalability ### {#req-scalability}

If all IoT devices started using [=Web PKI certificate=]s for HTTPS/WSS communication,
the number of certificates required will be significantly larger than the total number
of certificates exists today for public web servers.
Therefore, following exemption may be required:
- If the [=device=] uses a [=Web PKI certificate=] for HTTPS/WSS communication,
    the [=CA=] should be exempt to preserve CT (certificate transparency) logs for the [=device=]s.

### User Experience ### {#req-user-experience}

While the user interaction is required in certain scenarios, it should not be
a hindrance to providing a better user experience. Following requirements should be considered:
- The [=UA=] should minimize user’s interaction for [=device identification=]
    as much as possible.
- If the [=device=] uses a TLS server certificate for HTTPS/WSS communication,
    the procedure of certificate grant and issuance and renewal should be automated
    as much as possible so that the users' interaction can be greatly minimized.

<pre class="biblio">
{
}
</pre>