Sitelet https://github.com/httpslocal/usecases/commit/b6aebdb233b67b65230c71dfb433fc97bf257c46
Skip to content

Commit b6aebdb

Browse files
tomoyukilabstomoyukilabs
committed
separate and refine requirements
1 parent 881ae34 commit b6aebdb

2 files changed

Lines changed: 67 additions & 44 deletions

File tree

‎Requirements.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Requirements for HTTPS/WSS in Local Network
2+
3+
This section outlines functional and non-functional requirements of HTTPS/WSS usage in local network represented in [UseCases.md](UseCases.md).
4+
5+
Functional requirements consist of device discovery, device authentication, certificate issuance, and certificate management and lifecycle.
6+
7+
Non-functional requirements address user experience and security aspects of HTTPS/WSS usage in local network.
8+
9+
## <a name=“functional-requirements”></a>Functional Requirements
10+
11+
### <a name=“terminology”></a>Terminology
12+
13+
A device is in the same local network as the user agent (UA), capable of HTTPS/WSS server, compliant with [certificate grant and issuance](#certificate-grant-and-issuance) and [certificate management](#certificate-management), and notifies the UA of the capability during [device discovery](#device-discovery).
14+
15+
A device delegate is in the public IP address network, has the certificate issued for the device, and relays messages between the UA and the device. Device discovery through the device delegate is out of scope.
16+
17+
### <a name=“device-discovery”></a>Device Discovery
18+
19+
- The UA shall be able to discover the presence of devices in the same local network.
20+
- The UA shall be able to obtain the endpoint URL of the device which has the scheme `https:` or `wss:` and its compliance with [certificate grant and issuance](#certificate-grant-and-issuance) and [certificate management](#certificate-management).
21+
22+
### <a name=“device-authenticaion”></a>Device Authentication
23+
24+
- The UA shall authenticate one of the [discovered](#device-discovery) device selected by the user.
25+
- The UA shall authenticate one of the devices registered in the device delegate selected on the web application.
26+
- The UA shall ask the user to input information such as PIN code or passphrase when the device requests to do so, and notify the device of the information, so that the UA and the device or the device delegate can properly authenticate with each other.
27+
- The UA shall only expose the interface to the authenticated device to web applications.
28+
- The UA shall initiate [certificate grant and issuance](#certificate-grant-and-issuance) procedure when the device or the device delegate is authenticated successfully.
29+
- The UA shall be able to authenticate the device or the device delegate automatically without the user’s grant when it has been authenticated once and its certificate has not been expired or revoked yet.
30+
31+
### <a name=“certificate-grant-and-issuance”></a>Certificate Grant and Issuance
32+
33+
#### <a name=“local-network-certificate”></a>Certificate for Local Network
34+
35+
- The device shall be able to have at least one of the following types of TLS server certificates so that an origin of the connection with the device becomes [potentially trustworthy](https://w3c.github.io/webappsec-secure-contexts/#potentially-trustworthy-origin) in a certain period:
36+
- a self-signed certificate explicitly granted by the user (*TODO: consider whether this item is appropriate or not in terms of security*)
37+
- a self-signed certificate granted on the web application’s origin explicitly by the user
38+
- a certificate issued by a private certificate authority for devices (device CA) explicitly granted by the user
39+
- The device shall be able to verify whether or not the certificate is either granted by the user or properly issued by the device CA.
40+
- The web server shall be able to provide the UA with a hint about the certificates to be granted on the web application’s origin.
41+
- The device CA shall automatically issue a certificate for the device when the user grants and the device requests.
42+
- The device CA shall verify certificate issuing request from both the device and the UA before issuing a certificate to the device.
43+
- The certificate shall have a reasonably short expiration period.
44+
45+
#### <a name=“certificate-for-delegate”></a>Certificate for Device Delegate
46+
47+
- The device delegate shall be able to have a TLS server certificate issued by the publicly trusted certificate authority (public CA) through an automated procedure so that an origin of the connection with the device becomes [potentially trustworthy](https://w3c.github.io/webappsec-secure-contexts/#potentially-trustworthy-origin).
48+
- The public CA shall automatically issue a certificate for the device delegate when the user grants and the device behind the device delegate requests.
49+
- The certificate shall have a reasonably short expiration period.
50+
51+
### <a name=“certificate-management”></a>Certificate Management
52+
53+
- The UA shall ask the user if the user grants the renewal of the certificate when the certificate is expired during [device authentication](#device-authentication), [certificate grant and issuance](#certificate-grant-and-issuance), or communication with the device.
54+
- The UA shall be able to revoke the certificate when the user decides to do so.
55+
- The certificate issued by the device CA shall be able to be revoked by the device CA when necessary. (Note that the root CA can revoke the ceritficate issued by it through OCSP.)
56+
57+
## <a name=“non-funcational-requirements”>Non-Functional Requirements
58+
59+
### <a name=“privacy-and-security></a>Privacy and Security
60+
61+
- [Device authentication](#device-authentication) and [certificate grant and issuance](#certificate-grant-and-issuance) should prevent passive network eavesdroppers from learning messages related to authentication or certificate passed between the UA and the device.
62+
- [Device authentication](#device-authentication) and [certificate grant and issuance](#certificate-grant-and-issuance) should prevent active network attackers from impersonating a device and observing or altering data intended for the UA.
63+
64+
### <a name=“user-experience”></a>User Experience
65+
66+
- The UA should minimize user’s interaction for authentication as much as possible.
67+
- The procedure of [certificate grant and issuance](#certificate-grant-and-issuance) should be automated as much as possible so that the user’s interaction can be minimized.

‎UseCases.md‎

Lines changed: 0 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -68,47 +68,3 @@ if she usually posts photos to the online service from her smartphone directly,
6868
A user sets up a home automation gateway is under normal circumstances using HTTPS to securely accept commands via a remote server.
6969
In some cases the gateways internet connection is interrupted but local communication between a wall mounted control surface, app, or similar should stil be given.
7070
This becomes very important when we consider that devices that can be controlled this way include door locks and security cameras.
71-
72-
# Requirements for HTTPS/WSS in Local Network
73-
74-
This section collects requirements derived from use cases listed above.
75-
76-
## <a name="req-01"></a>REQ-01: Device Discovery
77-
78-
- The UA (the web browser mentioned in the use cases above) shall be able to securely discover the presence of HTTPS/WSS server capable devices (hereinafter just called 'device') that are connected to the local network.
79-
- A secure context loaded from the internet to the UA (hereinafter just called 'secure context') should also be able to discover target device capabilities that are actively (e.g., turned on) connected to the local network (e.g., device type, identity of a set of Web APIs, and so on).
80-
- A secure context shall be able to get access to the locally discovered device based on the user consent.
81-
- If there are multiple devices in local network, the UA shall be able to provide the user with a way to select one device at a time which she intends to use on the secure context.
82-
- The list of devices in local network must not be exposed directly to web applications. The UA must provide web applicatons with only information or interface related to the device selected by a user.
83-
- etc.
84-
85-
## <a name="req-02"></a>REQ-02: Mutual authentication between device and secure context
86-
87-
- The secure context must have a way to verify whether the device to which it tries getting access is reliable or not.
88-
- The device should have a way to verify whether the origin of the secure context which tries getting access to the device is reliable or not.
89-
- etc.
90-
91-
## <a name="req-03"></a>REQ-03: Issuing TLS server certificate for device
92-
93-
NOTE: Are there any solution to realize the use cases above without issuing a TLS server certificate to the device ?
94-
95-
- The device must have a way to get a server certificate which the UA can trust after connecting to the local network because an IP address and a domain name of a device in local network is subject to change.
96-
- The device must have a way to verify the server certificate issuer’s trust.
97-
- A server certificate issuer for devices (hereinafter called 'Device CA') must have a way to verify whether the target device is eligible for having a server certificate or not.
98-
- The device should have a cryptographically secure way to keep the private key of the server certificate secret.
99-
- The server certificate for the device should be issued without manual configuration by the user because local network (e.g., home network, small office network) usually does not have any network administrators.
100-
- etc.
101-
102-
## <a name="req-04"></a>REQ-04: Cross-origin access from secure context to device
103-
104-
- The UA shall be able to allow secure contexts to get access to HTTPS/WSS server capable devices in local network based on user granting authorization to the device.
105-
- The device in local network should be able to accept access requests from secure contexts based on user granting authorization.
106-
- etc.
107-
108-
## <a name="req-05"></a>REQ-05: Managing (reissuing and revoking) TLS server certificate for device
109-
110-
NOTE: There haven't been use cases for the requirements yet but we will have to discuss this topic eventually.
111-
112-
- The UA shall be able to revoke access privilege for the secure context to the device if the user decides to do that.
113-
- The UA should be able to revoke access privilege for the secure context to the device if the UA finds out the device has already become insecure, is malicious or is vulnerable (based on user granting authorization).
114-
- etc.

0 commit comments

Comments
 (0)