diff --git a/website/docs/background/_category_.yml b/website/docs/background/_category_.yml index 2883bb2..223a814 100644 --- a/website/docs/background/_category_.yml +++ b/website/docs/background/_category_.yml @@ -1 +1,2 @@ -label: Background \ No newline at end of file +label: Background +position: 2 diff --git a/website/docs/communication-layer/_category_.yml b/website/docs/communication-layer/_category_.yml new file mode 100644 index 0000000..b819070 --- /dev/null +++ b/website/docs/communication-layer/_category_.yml @@ -0,0 +1,2 @@ +label: Communication layer +position: 5 \ No newline at end of file diff --git a/website/docs/communication-layer/accepted-crypto.md b/website/docs/communication-layer/accepted-crypto.md new file mode 100644 index 0000000..31faf79 --- /dev/null +++ b/website/docs/communication-layer/accepted-crypto.md @@ -0,0 +1,20 @@ +--- +title: Accepted crypto algorithms +sidebar_position: 4 +--- + +## Introduction + +In the [discovery and pairing specification](./discovery-pairing-authentication.md) a description is given of the required communication layer. This layer includes a description of encryption requirements. Because the security levels given by different crypto algorithms change continuously, this page contains the accepted crypto algorithms for the S2 protocol. Keep in mind that this will change over time. + +At the moment, we refer to the Mozilla guidelines in: [Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS). In the future these Mozilla guidelines will change, and S2 might have it's own list of accepted algorithms. + +## Accepted algorithms will change + +As mentioned in the introduction, due developments in crypto technologies, security levels of known crypto algorithms will change over time. Algorithms that were considered safe 10 years ago, are unsafe at the moment. And algorithms that are considered safe today, might be vulnerable to new attacks in 5 years, or even tomorrow. And as we prepare for the imminent transition to post-quantum cryptography, our perception of the security of algorithms will most likely change. + +Therefore, this list will continuously change, and kept up to date. However, to engineer future proof systems, S2-nodes **SHOULD** be able to update their used crypto libraries, and hardware **SHOULD** be over-dimensioned. So, if the used crypto becomes obsolete newer, and possibly heavier, algorithms can be installed on the S2-node. When changes are made to the list of accepted crypto libraries, all S2Nodes **MUST** follow these changes within half a year. + +## Accepted algorithms + +At the moment, we consider the guidelines give by Mozilla in [Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS) on the level **Modern** as secure for usage in S2. \ No newline at end of file diff --git a/website/docs/communication-layer/discovery-pairing-authentication.md b/website/docs/communication-layer/discovery-pairing-authentication.md new file mode 100644 index 0000000..2d60d02 --- /dev/null +++ b/website/docs/communication-layer/discovery-pairing-authentication.md @@ -0,0 +1,391 @@ +--- +title: The Specification +sidebar_position: 2 +--- + +## Introduction + +s2-ws-json is a WebSocket and JSON based protocol specification implementing the EN50491-12-2 "S2" standard for home and building energy management. + +This specification addresses everything needed to created a secure and interoperable implementation of the S2 standard. The communication layer concerns the discovery, the pairing, the application layer communication protocol, the authentication, the message data model and the serialization. + +The protocol is designed to specify communication between two devices, a resource (e.g. a heat pump or EV charger) and (home) energy management system. It is worth noting that, while this specification focuses on describing the interaction between two components, a (home) energy management is likely to be communicating with multiple resources at the same time. + +## List of abbreviations + +|Abbreviation | Meaning +|---|---| +|S2| European standard on Energy Flexibility EN50491-12-2| +|RM| Resource Manager | +|CEM| Customer Energy Manager | + +## Background + +### Requirements +The communication layer meets the following requirements: + +The Customer Energy Manager (CEM) and Resource Manager (RM) are logical concepts within the S2 architecture, therefore the S2 standard does not make any assumptions on how and where the CEM and RM are deployed in a real life situation. In practice, the CEM could be deployed on a local gateway or as a server in the cloud, while the RM could be part of the device itself, deployed on an add-on module or in the cloud as well. This means that the S2 communication layer **MUST** be able to deal with multiple scenarios that are depicted in the figure below. + +![Deployment_options](/img/communication-layer/deployment-options.png) + +In addition to - and partly because of - supporting the various deployment options, the S2 communication layer has the following generic requirements: + +- Support for full duplex communication. Both sides **MUST** be able to send and receive data simultaneously. +- Communication **MUST** be IP based. +- Communication **MUST** be encrypted. +- Communication latency between CEM and RM or vice versa **MUST** be ≤ 1 second. +- Communication **MUST** work without additional firewall configuration by the end user. +- Implementation of the communication layer **MUST** be based on a widely accepted technology and must be relatively easy to implement. +- The pairing process **SHOULD** support extensibility for other application layer communication protocols. + +### Technical decisions +Given the requirements, this specification is build on the following high-level technical choices: + +Application layer communication protocol: WebSocket Secure with bearer token authentication. + +Pairing: Custom HTTP API specified in OpenAPI. + +Discovery: DNS-SD in combination with a central registry. + +Serialization: json. + +**Why not oAuth 2.0?** + +The short answer is: oAuth is mainly designed for accessing protected resources in the cloud and since the S2 CEM and RM would also need to be able to pair on a local network (even without requiring internet access) oAuth 2.0 is simply not a good fit. We have identified a way to make it work but since it is such non-typical way, we choose not to use oAuth 2.0. +For the long answer, please refer to [this page](why-not-oauth.md). + + +# List of definitions + +This specification uses the concepts that are defined below. + +**S2 node (S2Node)** + +Refers to either a CEM or a RM as defined in EN 50491-12-1. S2 communication between two S2 nodes can only be established if one of the S2 nodes is a CEM and the other a RM. These S2 nodes must also have the same end user. + +**S2 node UI (S2NodeUI)** + +A user interface through which an end user can interact with a S2 node. Interaction between the end user and the user interface must be secure, but this is out of scope for this specification. Examples of a user interface are a web interface, an app or a physical interface (HMI) on a device. + +**S2 server node (S2ServerNode)** + +A S2 node that implemented a WebSocket Secure server that can be used for establishing S2 communication between itself and another S2 node. The other S2 node must act as a S2 client node. + +**S2 client node (S2ClientNode)** + +A S2 Node that implemented a WebSocket Secure client that can be used for establishing S2 communication between itself and another S2 node. The other S2 node must act as a S2 server node. + +**S2 server node UI (S2ServerNodeUI)** + +This is the S2 node UI of a S2 server node. Through this user interface the end user should be able to obtain the WebSocket Secure URI and configure or generate a token to be used by a S2 client node. + +**S2 client node UI (S2ClientNodeUI)** + +This is the S2 node UI of a S2 client node. Through this user interface the end user must be able to retrieve a token (unless the S2 client node has a fixed string that must be configured as a token on the S2 server node UI) and configure the WebSocket Secure URI of an S2 server node that this S2 client node wants to establish S2 communication with. + +**S2 server node REST API (S2ServerNodeRestAPI)** + +The S2 server node features a REST API that facilitates the pairing process of a S2 client node and a S2 server node. It is also plays a role in the initiation of a WebSocket Secure connection between the client and server node. + +The implementation of this REST API **MUST** follow the OpenAPI definition that can be found [here.](https://github.com/flexiblepower/s2-ws-json/blob/e238819dfb8bc0310be61c372294d6eaa316c51e/s2-pairing/s2-pairing-openapi-spec.yml) + +**S2 server node endpoint (S2ServerNodeWSSEndpoint)** + +This is the endpoint of the WebSocket Secure server which can be addressed through its corresponding URL. + +**S2 client node endpoint (S2ClientNodeEndpoint)** + +This is used to denote the endpoint of both the REST API client and the WebSocket Secure client. + +**End user (EndUser)** + +A person or entity that manages S2 nodes. For the purpose of this specification it is assumed that there is already a trust relationship in place between this person and the S2 nodes. The means that the way the trust relationship has been established is out of scope for this specification. + +# Mapping the CEM and RM to S2 Server and Client Nodes + +The CEM and RM roles defined by the S2 protocol are distinct from the Server and Client roles of the S2 pairing process. The following rules apply to determine whether the RM or CEM acts as a Client or Server in the pairing process. + +* If a connection is set up between a cloud/WAN node and a local node, the cloud/WAN node must act as a S2 Server Node, and the local node must act as a S2 Client Node. +* If a connection is set up between two nodes that are similarly deployed (i.e. both in cloud/WAN, or both local), the CEM must act as a S2 Server Node, and the RM must act as a S2 Client Node. + +There are four scenarios for CEM and RM deployment, and applying the rules above yields the following: + +| CEM deployment | RM deployment | CEM acts as | RM acts as | +|----------------|---------------|-------------|------------| +| cloud/WAN | cloud/WAN | S2 Server Node | S2 Client Node | +| cloud/WAN | local | S2 Server Node | S2 Client Node | +| local | cloud/WAN | S2 Client Node | S2 Server Node | +| local | local | S2 Server Node | S2 Client Node | + +Note: A device developed solely for use as an RM in a local setup will never function as an S2 Server Node. Similarly, a device designed exclusively for use as a CEM in a cloud/WAN deployment will never operate as an S2 Client Node. + +## Hostname of S2 Server Nodes +In the case of S2 Server Nodes in LAN, the Node **MUST** advertise itself using **hostnames** rather than IP addresses and S2 Client Nodes need to identify and remember the Server using this hostname, not just the IP address as this may be subject to change. The hostname of a node **MUST** be stable and unique. + +## Discovery +In order to ease the pairing process, which is specified below, the discovery process provides a way for nodes to find each other without requiring a user to know the pairing endpoint of the other node. In other words, the discovery process is a way to provide an S2 Node with the URL of another node which is needed to start the pairing process. Alternatively, it is always possible to initiate the pairing by manually providing the URL by the end user. + +> NOTE: the discovery process specification is work in progress and will be updated soon. + +### Cloud-cloud +Both the S2 RM and CEM run in the cloud (for example communicating with the device via a manufacturer specific protocol). Discovery of the other node by lookup in a central registry. + +> NOTE: how the API of the registry will look like will be published soon + +### Cloud-local +A hybrid scenario where either the RM or CEM is deployed locally and the other in the cloud. Discovery of the cloud node by lookup in a central registry or DNS-SD in case the node is also present on the LAN. + +> NOTE: the DNS-SD service specification will be published soon + +### Local-local +A LAN scenario where both RM and CEM are running on the same local network. Discovery through DNS-SD. + +> NOTE: the DNS-SD service specification will be published soon + +## The pairing process + +The pairing process is based on the trust relation that the end user has with both the CEM and the RM. That trust relation is out of scope for this specification and is up to CEM and RM providers to implement. Given the deployment scenario, it [follows](# Mapping the CEM and RM to S2 Server and Client Nodes) which of the RM and the CEM is server and which is the client in the pairing process. + +The pairing process can either be initiated from the client or from the server. + +### Initiate pairing from the client + +#### Pairing with a discovered Server + +The user visits the S2ClientNodeUI and the S2ServerNode has been discovered (so the S2ServerNode base URL is known) by the the S2ClientNode per [discovery](#discovery) as specified above. The S2ClientNode does a preparePairing HTTP request to let the S2ServerNode know that there is a S2ClientNode that wants to pair. It is up to the S2ServerNode implementation to decide what to do with this signal. It can be used to display a pop-up with the pairing token in its UI to improve the user experience. It must be implemented by the client, but only when there is a clear distinction between the moment perparePairing is called and when requestPairing is called. When preparePairing is called, it is not guaranteed that a call to pairingRequest or cancelPreparePairing will follow so it is recommended to put a time-out on showing the pairing token in the S2ServerNodeUI. + +The S2ServerNodeUI **can** show the S2ServerNode URL to (also) allow clients that did not discover the server to connect but it does not need to because there is a client that already knows the S2ServerNode URL and that wants to pair. + +#### Pairing with server manually +If the S2ServerNode was not discovered, the process is as follows: + +![image](/img/communication-layer/pairing-manually.png) + +
+Image generated using the following PlantUML code: + +``` +@startuml +participant S2ClientNodeEndpoint +participant S2ClientNodeUI +participant EndUser +participant S2ServerNodeUI +participant S2ServerNodeRestAPI + +note over S2ServerNodeRestAPI, S2ServerNodeUI: S2ServerNode +note over S2ClientNodeEndpoint, S2ClientNodeUI: S2ClientNode + +EndUser->S2ServerNodeUI: 1. Request pairingInfo +note over S2ServerNodeUI: The pairing token that is part\nof the pairingInfo object expires\nafter 5 minutes +S2ServerNodeUI-->EndUser: 2. Provide pairingInfo + +EndUser->S2ClientNodeUI: 3. Provide pairingInfo + +S2ClientNodeEndpoint->S2ServerNodeRestAPI: 4. HTTPS requestPairing(pairingRequest) +S2ServerNodeRestAPI->S2ServerNodeRestAPI: 5. Check pairing token +S2ServerNodeRestAPI-->S2ClientNodeEndpoint: 6. HTTPS pairingResponse +@enduml +``` +
+ + +1. The end user visits the S2ServerNodeUI to retrieve the pairingInfo, i.e. the server URL and the pairingToken. It needs this information to enter it at the S2ClientNodeUI such that the client can initiate the pairing. +2. The S2ServerNodeUI shows the pairingInfo. A JSON object that specifies the information in the pairingInfo is defined in the [s2-over-ip-pairing OpenAPI definition](https://github.com/flexiblepower/s2-ws-json/blob/e238819dfb8bc0310be61c372294d6eaa316c51e/s2-pairing/s2-pairing-openapi-spec.yml). The schema for the pairingInfo is not associated with a REST path as this information is obtained from a User Interface and not by means of a REST call. +3. The end user submits the pairingInfo in the S2ClientNodeUI. +4. The client performs the requestPairing call as defined in the [s2-over-ip-pairing OpenAPI definition](https://github.com/flexiblepower/s2-ws-json/blob/e238819dfb8bc0310be61c372294d6eaa316c51e/s2-pairing/s2-pairing-openapi-spec.yml). +5. The server check if the pairingToken in the requestPairing call matches the token that it displays to the end user. +6. The pairingResponse informs the S2ClientNode whether the pairing was successful or not. + +### Initiate pairing from the server + +> NOTE: the specification for initiating the pairing from the server will be published soon + +## The unpairing process + +Unpairing can either be initiated by S2Node that runs the CEM or the RM. + +As the pairing and authorization process is based on a client/server model, the following applies to the unpairing process. + +If the client node takes the initiative to unpair, it first **should** close any active connections it has and subsequently call the unpair HTTP API endpoint of the server using its access token. Upon receiving the unpair call from a client, the S2 server node **must** remove all security information related to the paired node. After the response has been received by the client, the client **must** remove all security information of the server node. + +If the server takes the initiative to unpair, first it **must** remove all security information related to client node. After that, it **should** send a S2 [SessionRequest](/model-reference/Common/SessionRequest/) message with type [RECONNECT](/model-reference/Common/SessionRequestType/) to the client. The next initiateConnection HTTP API request **must** fail with the 'Unknown node ID' response to let the client know that it is not paired anymore. + +Client and server **can** keep other (non-security) information for user experience purposes. + +## S2 Connections + +After two nodes have been paired, the nodes exchange S2 messages over a secure connection. + +The following mechanism **must** be used to initiate a secure connection between two S2 nodes. Client authentication is based on a one-time use communication token that needs to be renewed every time a new S2 session is created. + + +### Initiation + +![connection initiation](/img/communication-layer/connection-initiation.png) + +
+Image generated using the following PlantUML code: + +``` +@startuml +Client -> Server : 1. initiateConnection(s2ClientNodeId, accessToken,\n supportedCommunicationProtocols, supportedS2Versions) +Server -> Server : 2. check protocol version, generate new token pair +Server -> Client : 3. initiateConnectionResponse(s2ServerNodeId,\npendingAccessToken, commToken, connectionUrl,\nselectedCommunicationProtocol, selectedS2Version) +Client -> Client : 4. store new accessToken +Client -> Server : 5. setUpConnection(commToken) +Server -> Server : 6. activate new accessToken for this NodeId +Client <-> Server : 7. Successful S2 session +Client -> Client : 8. accept new accessToken +@enduml +``` + +
+ +**1. initiateConnection** + +The client has a list of pairs of accessTokens and commTokens. After the initial initiateConnection call, the list always contains at least one pair (initially there is only an accessToken as result of the pairing process). It uses one of the accessTokens to make an authorized request to retrieve a commToken and new accessToken form the server. + +**2. generate new token pair** + +For each paired NodeId the server saves an active accessToken and active commToken. In addition to that, the server also has a list for pending tokens. This list contains entries, each consisting of an accessToken, a commToken, a NodeId and a timestamp. +The server checks the provided accessToken from the client with the active accessToken it has saved for this node. If the provided accessToken was valid, the server generates a new accessToken and commToken and saves this together with the S2NodeId and the current time as in entry in the list of pending tokens. + +**3. initiateConnection response** + +a. If the provided accessToken was valid, the server sends the generated pending accessToken, commToken and connectionUrl to the client. + +b. If the provided accesToken was not valid, the server responds with an error. The process terminates. If the client has multiple accessTokens stored, it can retry with another one. + +**4. store new accessToken** + +a. The client has a list of accessTokens. It adds the new accessToken to the list, but does not yet remove the old one. + +b. If the client was not able to persist the new accessToken (e.g. because the storage device or the DBMS is not available) the client does not proceed with the process. Once the client is able to persist accessTokens again, it can retry to set up a connection from the start. + +**5. setUpConnection(commToken)** + +The client initiates the S2 session, and provides the commToken. + +**6. Activate new accessToken for this NodeId** + +This step is the implicit acknowledgement to the server that the client has saved the accessToken successfully. + +a. If the provided commToken is in the list pending tokens, and the token was generated not more than 30 seconds ago, the server replaces the associated accessToken for the associated NodeId as the active token. Also, the entry is removed from the list of pending tokens. + +b. If the provided commToken is not in the list of pending tokens, the server must not accept the connection and respond with an error code. + +c. If the server is not able to active the new tokens (e.g. because the storage device or the DBMS is not available), the server must not accept the connection and responds with an error code. + +**7. Successful S2 session?** + +a. The S2 session is successfully opened. This is an implicit acknowledgement that both server and the client are in possession of the new tokens. For the server it is an acknowledgement that is has activated the new access token successfully and for the client it means that it did correctly receive and persist the new accessToken. + +b. If for any reason the S2 session is not set up successfully, the process terminates. The client can restart the process from the beginning when desired. + +**8. Remove old tokens** + +a. Since the server implicitly acknowledged the new accessToken, all pairs of accessToken and commToken which do not contain the used commToken can be removed. + +b. If the client is not able to remove the old tokens (e.g. because the storage device or the DBMS is not available) it can continue working as normal. + +### WebSocket based communication + +This section specifies how to use WebSocket Secure as the S2-over-TCP/IP application layer protocol. + +The WebSocket client **must** run on the S2ClientNode and the WebSocket server on the S2ServerNode. + +The choice for a WebSocket as application layer communication protocol has the advantage that the session concept is intrinsically introduced with the communication protocol. All S2 communication happens in the context of a (stateful) S2 session which is catered for by the WebSocket session. So, the S2 session matches the WebSocket session. + +#### Authentication +For each S2 WebSocket session the client **must** authenticate itself using the commToken in the authorization header of the websocket connection request, following [RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://datatracker.ietf.org/doc/html/rfc6750). + +#### Encrypted connection (WSS) + +Communication over the WebSocket endpoint **must** be encrypted following [RFC 6455 The WebSocket Protocol](https://datatracker.ietf.org/doc/html/rfc6455). S2 **MUST NOT** be sent over unencrypted channels. Therefore a wss connection (the URL starting with wss://) must be used. + +#### Compression + +The WebSocket Protocol ([RFC6455](https://datatracker.ietf.org/doc/html/rfc6455)) has an extension for compression: [**RFC 7692**](https://datatracker.ietf.org/doc/html/rfc7692.html) implementing so called per-message-deflate compression. https://datatracker.ietf.org/doc/html/rfc7692 + +RFC 7692 is widely supported by WebSocket libraries and and we are exchanging JSON plain text messages, it is expected to save a large amount of data. Therefore, implementations of S2 WebSockets **SHOULD** support RFC 7692 and **SHOULD** enable it whenever possible. + +#### Keepalive & heartbeat (ping / pong) + +WebSockets by default have a **keepalive** and a **heartbeat mechanism**. Keepalive is designed to keep the connection open while heartbeat is designed to check the latency and check the connection is still working. This means that periodically a ping frame is sent to the server (endpoint) and in response a pong frame is sent. + +In order to reduce network traffic, S2 WebSocket implementations **SHOULD** not send ping frames more often than every 50 seconds. Ping & poing frames are control frames and **MAY** include payload of maximum 125 bytes. + +[https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2%5C%5C) + + +### State of communication + +![State of Communication](/img/communication-layer/state-of-communication.png) + +
+Image generated using the following PlantUML code: + +``` +@startuml + +hide empty description +[*] --> WebSocketConnected + +WebSocketConnected : ResourceManagerDetails, PowerMeasurement, \n PowerForecast can be exchanged + +WebSocketConnected --> ControlTypeActivated: Activate ControlType +ControlTypeActivated --> WebSocketConnected: Deactivate ControlType + +ControlTypeActivated: In addition to messages in\nthe "Initialized" state,\nControlType specific message\ncan now be exchanged as well + +WebSocketConnected --> WebSocketDisconnected: Termination of Session +ControlTypeActivated --> WebSocketDisconnected: Termination of Session + +WebSocketDisconnected --> [*] +@enduml +``` +
+ +| State | Messages that can be sent by CEM /received by RM | Messages that can be sent by RM / received by CEM | +| --- | --- | --- | +| WebSocket Connected | SelectControlType
SessionRequest
ReceptionStatus | ResourceManagerDetails
PowerMeasurement
PowerForecast
SessionRequest
ReceptionStatus | +| ControlType PEBC activated | PEBC.Instruction
SelectControlType
SessionRequest
ReceptionStatus | PEBC.EnergyConstraint
PEBC.PowerConstraint
RevokeObject InstructionStatusUpdate
ResourceManagerDetails
PowerMeasurement
PowerForecast
SessionRequest
ReceptionStatus | +| ControlType PPBC activated | PPBC.EndInterrptionInstruction
PPBC.ScheduleInstruction
PPBC.StartInterruptionInstruction
SelectControlType
SessionRequest
ReceptionStatus | PPBC.PowerProfileDefinition
PPBC.PowerPorfileStatus
RevokeObject
InstructionStatusUpdate
ResourceManagerDetails
PowerMeasurement
PowerForecast
SessionRequest
ReceptionStatus | +| ControlType OMBC activated | OMBC.Instruction
SelectControlType
SessionRequest
ReceptionStatus | OMBC.Status
OMBC.SystemDescription
OMBC.TimerStatus RevokeObject
InstructionStatusUpdate
ResourceManagerDetails
PowerMeasurement
PowerForecast
SessionRequest
ReceptionStatus | +| ControlType FRBC activated | FRBC.Instruction
SelectControlType
SessionRequest
ReceptionStatus | FRBC.ActuatorStatus
FRBC.FillLevelTargetProfile
FRBC.LeakageBehaviour
FRBC.StorageStatus
FRBC.SystemDescription
FRBC.UsageForecast
FRBC.TimerStatus
RevokeObject
InstructionStatusUpdate ResourceManagerDetails
PowerMeasurement
PowerForecast
SessionRequest
ReceptionStatus | +| ControlType DDBC activated | DDBC.Instruction
SelectControlType
SessionRequest
ReceptionStatus | DDBC.ActuatorStatus
DDBC.AverageDemandRateForecast
DDBC.SystemDescription
DDBC.TimerStatus
RevokeObject
InstructionStatusUpdate
ResourceManagerDetails
PowerMeasurement PowerForecast
SessionRequest
ReceptionStatus | + +### Termination + +A S2 session can be terminated in different ways: + +* In case a S2 node unexpectedly becomes unavailable, the WebSocket connection **CAN** timeout. This will cause an S2 session to be terminated. More details about the timeout can be found [in the heartbeat section](#keepalive--heartbeat-ping--pong) +* A S2 node **CAN** terminate the S2 session by sending the S2 terminate message, including an optional earliest time that the session can be restored. The other S2 node can take this into account in planning and (in the case of a client) deciding when to attempt to reconnect. +* After two S2 nodes have unpaired, the S2 WebSocket connection **MUST** be terminated immediately. + +### Reconnection strategy + +Once a S2 session is terminated it cannot be resumed and if further communication is required, a new session needs to be started. A S2 client node may try to establish a WebSocket connection. + +An exponential back-off strategy **SHOULD** be used, increasing the time between reconnection attempts at every failed attempt. If a reconnection time was included in any termination, S2 client nodes are permitted to make an attempt to reconnect before this time. At the specified time the delay between reconnection attempts **SHOULD** be reset. + +## Security + +Please refer to an extensive description of the security specifications to [Security considerations](./security-considerations.md). + +### Certificates + +For each S2 connection the server authenticates using a certificate. The cloud implementation certificates **MUST** be PKI certificates which are not self-signed. Only local servers can use a self-signed CA certificate, which is used to sign a server certificate. +If the S2 protocol is used in a local-local configuration, the server **CAN** use a self-signed CA certificate. In this case, the pairingInfo **MUST** include the first 9 bytes, encodes as 12 base64 encoded characters, of the fingerprint of this self-signed CA certificate and the client **MUST** check this fingerprint. + +Note that all communication use TLS. This is further explained in [Security considerations](./security-considerations.md). + +The server certificates **MUST** be exchanged and validated during the initiation of the connection (REST and WSS). This is default usage of most networking libraries. + +### Cipher suites + +Security levels of cipher suites will change over time. To stay secure, the used cipher suites should be updates regularly and adhere to regular updates. All S2Nodes **MUST** follow **ONLY** the accepted crypto libraries as defined in [Accepted crypto algorithms](./accepted-crypto.md). This list will be kept up-to-date. When changes are made to the list of accepted crypto libraries, all S2Nodes **MUST** follow these changes within half a year. + +## Communication - JSON messages + +The S2 standard has been encoded into a JSON schema and asyncapi specification, for details see: [JSON protocol specification for S2 WebSockets](https://github.com/flexiblepower/s2-ws-json) \ No newline at end of file diff --git a/website/docs/s2-json-over-websockets/introduction.md b/website/docs/communication-layer/introduction.md similarity index 96% rename from website/docs/s2-json-over-websockets/introduction.md rename to website/docs/communication-layer/introduction.md index 72d4098..08f255e 100644 --- a/website/docs/s2-json-over-websockets/introduction.md +++ b/website/docs/communication-layer/introduction.md @@ -1,3 +1,8 @@ +--- +title: "Introduction" +sidebar_position: 1 +--- + # Introduction S2 was designed as a semantic protocol, which can have multiple, mutually compatible, implementing protocols. Different devices might prefer a different form of communication. For example, you can have a version of S2 which uses bluetooth, and another version which uses KNX. These versions differ in the transport protocol they use, but typically also in the way they encode data. Since both protocols are based upon the same S2 specification, one S2 implementing protocol can easily be translated into the other version using a simple software adapter. diff --git a/website/docs/communication-layer/security-considerations.md b/website/docs/communication-layer/security-considerations.md new file mode 100644 index 0000000..3592b5c --- /dev/null +++ b/website/docs/communication-layer/security-considerations.md @@ -0,0 +1,211 @@ +--- +title: Security Considerations +sidebar_position: 3 +--- + +## Crypto requirements + +The described protocol, ensures the following 4 requirements: + +1. Mutual authentication +2. Integrity of communication +3. Confidentiality of communication +4. Forward secrecy + +There is one guarantee that explicitly is not given by this protocol: + +1. Non-repudiation + +## Pairing and connection initiation processes + +In the image below, the relevant security communication is visualized. Note that, the first part of the communication (in red) is not part of the S2 protocol. The developer of the corresponding Client / Server is responsible for relevant security mechanisms in this part of the communication. This is important to note because the trust between the end user and both systems is the basis for the trust in the further communication. + +The following sequence diagram focuses on validation of certificates and tokens. Please refer to the other sequence diagrams that contain more details about the pairing and connection initiation. + +![image](/img/communication-layer/pairing-security.png) + +
+Image generated using the following PlantUML code: + +``` +@startuml +participant Client +participant EndUser +participant Server +note over Client, Server : Pairing phase +note left of Client: The red part of the communication \nis not part of the S2 protocol. \n\nUsed crypto is defined by the developer \nof the Client/Server + + +'PRE-S2 communication +EndUser-[#red]>Server: Request pairingInfo +Server -[#red]> Server: Create a connection token +note over Server: The pairing token expires\nafter 5 minutes +Server-[#red]>EndUser: Provide pairingInfo (url, certificate fingerprint and pairing token) +EndUser-[#red]>Client: Provide pairingInfo (url, certificate fingerprint and pairing token) +note left of Client : From this point on, S2 is used + +'Setting up connection +Client-[#blue]> Server : Setup TLS connection +Client -[#blue]> Client : Check certificate +alt Self-signed CA certificate +Client -[#blue]> Client : Check if server is local +alt Server is not local +Client -[#blue]> Client : Disconnect. Pairing failed. +end +Client -[#blue]> Client : Check certificate fingerprint +alt Certificate fingerprint does not match +Client -[#blue]> Client : Disconnect. Pairing failed. +end +else Certificate does not validate +Client -[#blue]> Client : Disconnect. Pairing failed. +end + +'Pairing with server +Client-[#blue]> Server : HTTPS requestPairing(token, clientNodeId) +Server -[#blue]> Server: Check pairing token +alt Pairing token is not valid or expired +Server --[#blue]> Client: HTTPS requestPairingResponse(error) +else Pairing token valid +Server -[#blue]> Server: Generate accessToken +Server --[#blue]> Client : HTTPS requestPairingResponse(accessToken) +end + +'Setting up connection +note over Client, Server : Future connections +Client -[#blue]> Server: Setup TLS connection +Client -[#blue]> Client: Check certificate + +alt Self-signed CA certificate +Client -[#blue]> Client : Check if server is local +alt Server is not local +Client -[#blue]> Client : Disconnect. Connection failed. +end +Client -[#blue]> Client : Check if certificate fingerprint +alt Certificate unknown +Client -[#blue]> Client : Disconnect. Connection failed. +end +else Certificate does not validate +Client -[#blue]> Client : Disconnect. Connection failed. +end +Client -[#blue]> Server: HTTPS initiateConnection(accessToken, s2ClientNodeId) +Server -[#blue]> Server: Check accessToken + +alt accessToken valid +Server --[#blue]> Client: initiateConnectionResponse(connectionUrl, new accessToken, commToken) +else accessToken invalid +Server --[#blue]> Client: initiateConnectionResponse(401) +end + + +'Websocket connection +alt +Client -[#blue]> Server: Connect to websocket with commToken \nover existing TLS connection +else +Client -[#blue]> Server: Setup TLS connection +Client -[#blue]> Client: Check certificate + +alt Self-signed CA certificate +Client -[#blue]> Client : Check if server is local +alt Server is not local +Client -[#blue]> Client : Disconnect. Connection failed. +end +Client -[#blue]> Client : Check if certificate fingerprint +alt Certificate unknown +Client -[#blue]> Client : Disconnect. Connection failed. +end +else Certificate does not validate +Client -[#blue]> Client : Disconnect. Connection failed. +end +Client -[#blue]> Server: open WebSocket connection with commToken +end +Server -[#blue]> Server: Check commToken +alt Incorrect token +Server -[#blue]> Server : Disconnect. Connection failed. +end +Server -[#blue]> Client : Connection accepted. +@enduml + +``` + +
+ +## Certificates + +There are two possible types of certificates. The first option is a public server certificate, that is part of the public PKI infrastructure, (indirectly) signed by a public root CA. This protocol allows local servers to use a self signed CA certificate to sign its local server certificate. This is needed because a local server is not able to get a certificate from a public PKI infrastructure. + +In the following image, the difference is shown. On the left a public root CA that's publicly known and trusted, on the right, a self signed root certificate, that's unknown and it's trustworthiness has to be achieved in another way. + +![image.png](/img/communication-layer/certificate-chains.png) + +
+Image generated using the following PlantUML code: + +``` +@startuml +struct PublicRootCA +struct PublicIntermediateCA +struct PublicServerCertificate + +PublicRootCA --> PublicIntermediateCA +PublicIntermediateCA --> PublicServerCertificate + + +struct SelfSignedCA +struct LocalServerCertificate + +SelfSignedCA --> SelfSignedCA +SelfSignedCA --> LocalServerCertificate +@enduml +``` +
+ + +### Trusting aself signed root certificate + +The self signed root certificate is by default not trusted. However during the pairing phase, the server with the self signed root certificate will share part of the root's certificate fingerprint as part of the pairing token, via a second channel. This will enable the client to verify the self signed root certificate, and create trust. From this moment on, the client will store the complete fingerprint of the self signed root certificate, and use it to verify the server certificate for all future connections. + +Note that the `preparePairing` and `cancelPreparePairing` endpoints can be called before the pairing has happened. So in the case the server is running on a LAN (and thus uses self-signed certificates), the client can skip the certificate validation steps on those endpoint. + +### Updating the certificates + +A server can update its certificate. When a cloud server updates it's certificate, it **MUST** be signed by a CA, so a client can check it's validity. A server **SHOULD** update its server certificate at least once every 6 months. + +If the server is in local-local mode, and uses a self-signed CA certificate, the CA certificate **SHOULD** be created with a validity period which is long enough for the expected lifetime of the server. If the used crypto for the the CA certificate is broken, or the lifetime of the server is longer than the validity of the certificate, the server **MUST** create a new self-signed CA certificate and all clients need to be paired again. Like cloud servers, a local server **SHOULD** update its server certificate at least once every 6 months. + +## How are the requirements met? + +In the follow section, reasoning for each security requirement will be given. + +### Mutual authentication + +The mutual authentication is based on the trust relation between the user and the Client/Server. Since it is assumed that the user already had a trust relation with both of them, this existing trust can be used for mutual authentication between the client and the server. Note that the this communication is not part of the S2 protocol. + +The enduser requests an url, certificate fingerprint and token from the server, and gives these to the client. Based on these data, the client can connect to the server, using a TLS connection, check the certificate and authenticate himself with the token. Note that if the server uses a self-signed certificate, it will also give a certificate fingerprint to the user. The client needs to use this fingerprint to verify the certificate in the TLS connection. + +### Integrity of communication + +Using TLS will ensure the integrity of the data. + +### Confidentiality of communication + +Using TLS will ensure the confidentiality of the data. + +### Forward secrecy + +Using TLS1.3 will ensure the forward secrecy of the data. + +### Non-repudiation + +Non-repudiation is not guaranteed in this protocol. Individual messages are not signed by anyone and as a result both parties could deny sending a specific request. However, while no legal proof is given, since integrity and authenticity is guaranteed by TLS, each party always knows for sure which party made what statement. + +## Remaining risk + +There are two remaining vulnerable situations for the described protocol. In this section both will be explained. + +### Self signed certificates + +In the case that a local RM and a local SEM communication, it is not possible to generate a PKI-certificate that can be publicly validated. As a result, S2 accepts in **ONLY** this situation self-signed certificates. The risk for spoofing attacks are mitigated by sharing the certificate fingerprint and pinning the self signed certificate at the client side. As a result, the client can check for all future connections whether or not it is connected with the same server. + +### Trust relations between the end-user and the Client/Server + +The entire trust model of S2 is based on the fact that there is already a trust relation between the end-user and the client/server. If these clients/servers do not use adequate security mechanisms, it might be possible to attack the S2 system as well. \ No newline at end of file diff --git a/website/docs/communication-layer/why-not-oauth.md b/website/docs/communication-layer/why-not-oauth.md new file mode 100644 index 0000000..55e49b1 --- /dev/null +++ b/website/docs/communication-layer/why-not-oauth.md @@ -0,0 +1,134 @@ +--- +title: Why not oAuth 2.0? +--- + +Since oAuth 2.0 is the industry standard to authenticate clients for accessing protected server resources, it is very reasonable to question why the authorization of S2 clients is not using OAuth 2.0. + +Given our requirements on the pairing and authentication process, the following RFCs are needed to base the authentication on Oauth 2.0: + +* OAuth 2.0 Framework (RFC 6749) +* Device Authorization Grant (RFC 8628), this allows supporting S2 clients with very a limited user interface. +* Dynamic Client Registration Protocol (RFC 7591), this is needed because we don't want to preconfigure clients at the authorization server. + +The pairing and authentication process based on OAuth 2.0 would be specified as follows: + +![image](/img/communication-layer/oauth2-s2.png) +
+Image generated using the following PlantUML code: + +``` +@startuml +participant S2ClientNode +participant S2ClientNodeUI +participant EndUser +participant S2ServerNodeUI +participant AuthorizationServer +participant S2ServerNode + +note over S2ClientNode, S2ServerNode : Pairing phase +note left of S2ClientNode: The red part of the communication \nis not part of the S2 protocol. \n\nUsed crypto is defined by the developer \nof the Client/Server + + + + +'PRE-OAUTH communication +EndUser -[#red]> S2ServerNodeUI: Retrieve pairingInfo +S2ServerNodeUI --[#red]> EndUser: Provide pairingInfo \n(ws-URL and AuthServer-URL) +EndUser -[#red]> S2ClientNodeUI: Enter pairingInfo + +S2ClientNode-[#blue]> S2ServerNode : Setup TLS connection +S2ClientNode-[#blue]> S2ClientNode: Check certificate +alt Self-signed certificate +S2ClientNode-[#blue]> S2ClientNode: Check if server is local +alt Server is not local +S2ClientNode-[#blue]> S2ClientNode: Disconnect. Pairing failed. +end +else Certificate does not validate +S2ClientNode-[#blue]> S2ClientNode: Disconnect. Pairing failed. +end + +'Pairing with server +alt First time that these nodes pair +S2ClientNode-[#blue]> S2ServerNode : Request client identifier (RFC 7591) +S2ServerNode--[#blue]> S2ClientNode: Client identifier +end + + +S2ClientNode-[#blue]> S2ServerNode : Pairing request (Client identifier) +S2ServerNode -[#blue]> S2ClientNode: response(device code, user code, verification uri) + + +S2ClientNodeUI-[#red]>EndUser: Display uri +EndUser-[#red]>S2ServerNode: Connect to uri, and verify request +S2ServerNode-[#red]>S2ServerNode: Check token, authorize request + + +S2ClientNode-[#blue]> S2ServerNode : Polling for connection (Device code, client identifier) +S2ClientNode-[#blue]> S2ServerNode : Polling for connection (Device code, client identifier) +S2ServerNode -[#blue]> S2ClientNode: Accept (token, refresh token) +@enduml +``` + +
+ + +Let's break that down: + +The process starts with an end user who wants to pair two S2 nodes. The end user goes to the S2ServerNodeUI to retrieve the following URLs: +- Authentication server URL +- Websocket server URL + +Note that some of these urls could be composed by only communicating a base URL and specifying on which paths the different servers are located, which would reduce amount of URLs that the end user needs to enter in the S2ClientNodeUi. + +In addition, the end users receives an device code that is needed for the OAuth 2.0 device flow grant. + +Next, the S2ClientNode sets up a TLS connection to the authorization server. + +If it's the first time that the S2ClientNode wants access to a specific server, then follows a dynamic client registration (according to [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). This is needed because one of the requirements of the S2 pairing process is that the client and server cannot have any knowledge about each other. This guarantees interoperability because it allows for any S2 client to be able to connect to any S2 server without a developer that needs to request a client identifier (and possible a client secret) and use that in the client application for a specific server. + +Please note that dynamic client registration is not very common and has also security risks that need to be mitigated which means that using 'standard OAuth 2.0' is not so standard in this context. + +After client registration, the S2ClientNode requests an access code following the device authorization grant specification ([RFC 8628](https://www.rfc-editor.org/rfc/rfc8628)), again over a TLS connection to the authorization server. + +This token would then be used in the authorization header when making a websocket connection. + + +## Why not using OAuth 2.0? + +While we have specified the way how OAuth 2.0 can be used for authorizing S2 clients, there are several reasons why we favor our own protocol: +* Using OAuth 2.0 will require the end user to enter more information from S2ServerNodeUI to the S2ClientNodeUI compared to our custom pairing specification. The user has to provide the Authentication server URL, the Resource Server URL, the Websocket URL, and copy the token to S2ClientUI. +* The required functionality of OAuth 2.0 is separated in three different RFC's. This shows that this functionality is not part of the OAuth 2.0 core. Using OAuth 2.0 would limit OAuth 2.0 libraries that implement all three RFC's or still require manual implementation of . +* Since S2 would use such a specific use case in OAuth2.0, it's unknown how future proof this use case is. It's unknown if this use case will still be available in OAuth 3.0. +* The communication layer of S2 specifies the use of websockets. OAuth 2.0 does not have a (out of the box) solution for communicating to the client where the websocket connection should be opened. Hence, this requires the end user to manually configure the websocket URL on the client. +* S2 requires the protocol to be usable in a local situation, without internet connection. S2 does accept self-signed certificates in these specific situations. OAuth2.0 is not clear about this situation. As a result it is not clear whether it's possible to use OAuth 2.0 in this situation. +* In addition, to support the local-local scenario, the S2ServerNode needs to run the authorization server locally as well. Such a server is not necessarily the most resource intensive application but still requires the server to be packed with extra code. + + +## Alternative OAuth 2.0 grants + +Below are listed other OAuth 2.0 grant types and we briefly explain why those are not suitable for this purpose. + +**Authorization Code** + +The Authorization Code grant type is used to exchange an authorization code in order to get an access token. This type relies on a client being redirected via a URL in the browser. For S2, S2 nodes need to communicate directly and we can't therefore rely on a an end user's browser. + +https://tools.ietf.org/html/rfc6749#section-1.3.1 + +**Proof Key for Code Exchange (PKCE)** + +PKCE is an extension to the Authorization Code grant type with improved security features. However the same limitation around browser redirects apply. + +www.rfc-editor.org/rfc/rfc7636 + +**Client Credentials** + +The Client Credentials grant type is generally recommended for machine to machine communication. It relies un using a client id and client secret that the server knows about in other to authenticate. It is required that the client can keep a secret and that the server knows about this secret. In the S2 scenario any CEM and RM need to be able to communicate. It's thus not possible to agree on a client id and secret in advance, while being able to guarantee that this remains a secret. Distributing the information with the S2 node acting as a server, for example for the end user to fill in, would mean that it can't be kept secret. + +[tools.ietf.org/html/rfc6749#section-4.4](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4) + + +**Refresh Token** + +The Refresh Token grant type is not really a separate grant type, but is a way to obtain a new token once the existing token has expired. + +[tools.ietf.org/html/rfc6749#section-1.5](https://datatracker.ietf.org/doc/html/rfc6749#section-1.5) \ No newline at end of file diff --git a/website/docs/concepts/_category_.yml b/website/docs/concepts/_category_.yml index 12c659a..e54df12 100644 --- a/website/docs/concepts/_category_.yml +++ b/website/docs/concepts/_category_.yml @@ -1 +1,2 @@ -label: Concepts \ No newline at end of file +label: Concepts +position: 3 \ No newline at end of file diff --git a/website/docs/examples/_category_.yml b/website/docs/examples/_category_.yml index 46d2d48..c8c5aca 100644 --- a/website/docs/examples/_category_.yml +++ b/website/docs/examples/_category_.yml @@ -1 +1,2 @@ -label: Examples \ No newline at end of file +label: Examples +position: 4 \ No newline at end of file diff --git a/website/docs/examples/ev.md b/website/docs/examples/ev.md index abe77f3..b8c97c8 100644 --- a/website/docs/examples/ev.md +++ b/website/docs/examples/ev.md @@ -62,7 +62,7 @@ We cover the situation in which the RM has access to the following data: Furthermore, the RM can control the charging power of the EV such that it can set the power at any value between the minimum and maximum value. -The following sequence diagram is an example of what a message exchange between the CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/s2-json-over-websockets/state-of-communication.md) and the [FRBC Message reference](/model-reference/FRBC/FRBC.SystemDescription)). `ReceptionStatus` messages are omitted for readability. +The following sequence diagram is an example of how a message exchange between the CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/communication-layer/discovery-pairing-authentication/#state-of-communication)). `ReceptionStatus` messages are omitted for readability. ![cem_rm_interactions](https://www.plantuml.com/plantuml/png/VP7DJiCm3CVlUOey0F007D1W0x539TI2E9lKWcYf7MndQ3mzeI0HMCNLF_y_BA_KGAnCoH4RUjwZ-FLrT-Bxxjm_ujF0OOVc0nDXC1oTgzIVNipy5cZK5zYXw-TPHUrmQRD7pKoARYblIz4YfFXUSrhBAk8Y0JiWU4RPe45CsleFc33Ocic4q_qXB_itt4Emk0VxatJJNwtFXeCQJXlK835RP78kCMSVoHFx368nb0JYMKQKLdx7RoWTWXR12ScElI-35J2MmS2A7aTNL4_yfks5CzwIcfGmTsgapVXB-P17C7H8e_zi_gl6WAfriSVNWchk_x-FKNzUlwf-PKeV)
diff --git a/website/docs/examples/heat-pump.md b/website/docs/examples/heat-pump.md index b763d93..9a269a6 100644 --- a/website/docs/examples/heat-pump.md +++ b/website/docs/examples/heat-pump.md @@ -54,7 +54,7 @@ The possible Control Types to implement are summarized in the table below. In this example we will work out the communication between CEM and RM for an all electric heat pump that utilizes the DHW buffer for energy flexibility using FRBC. -The following sequence diagram is an example of what a message exchange between a CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/s2-json-over-websockets/state-of-communication.md) and the [FRBC Message reference](/model-reference/FRBC/FRBC.SystemDescription)). `ReceptionStatus` messages are omitted for readability. +The following sequence diagram is an example of what a message exchange between a CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/communication-layer/discovery-pairing-authentication/#state-of-communication)). `ReceptionStatus` messages are omitted for readability. ![XPBVhX8n4CRl-nHz0FK1l308I2Hn4xCByNhiVe66RcUTcMBmwLqW9-bXEJcty_l-TD9Pg95O6P9pcGsUpn2_-jPyy6tpsV_2xux32UO3vunWw9sRgF_uvSQ_K-xrI2UuzZQRK3ryfcoX8sV5qxvjZXOfnN_NdYfoCd6HW8Oo7I1h6CMaTNw7X60hpYQSTfVnUNx5FGMBPxA7fasxN](https://github.com/flexiblepower/s2-ws-json/assets/851310/49422881-d6e3-4ffc-b513-74230d61875d)
diff --git a/website/docs/examples/pv.md b/website/docs/examples/pv.md index 238f1e3..07c251b 100644 --- a/website/docs/examples/pv.md +++ b/website/docs/examples/pv.md @@ -32,7 +32,7 @@ Power Envelope Based Control is used for devices that can be influenced to use o ## Example of controlling an PV inverter using Power Envelope Based control (PEBC) This example describes how a PV inverter can expose its curtailment capabilities to the CEM and let the CEM control this inverter by sending it messages that will ask it to curtail itself. -The following sequence diagram is an example of what a message exchange between a CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/s2-json-over-websockets/state-of-communication.md)). ReceptionStatus messages are omitted for readability. +The following sequence diagram is an example of what a message exchange between a CEM and RM could look like, but messages could also be sent in a different order (see also [State of communication](/docs/communication-layer/discovery-pairing-authentication/#state-of-communication)). ReceptionStatus messages are omitted for readability. First an overview of the messages is presented graphically, next sections will describe the example messages in more detail. diff --git a/website/docs/s2-json-over-websockets/_category_.yml b/website/docs/s2-json-over-websockets/_category_.yml deleted file mode 100644 index bf0abc8..0000000 --- a/website/docs/s2-json-over-websockets/_category_.yml +++ /dev/null @@ -1 +0,0 @@ -label: S2 Json over Websockets \ No newline at end of file diff --git a/website/docs/s2-json-over-websockets/discovery-scenarios.md b/website/docs/s2-json-over-websockets/discovery-scenarios.md deleted file mode 100644 index bd286d1..0000000 --- a/website/docs/s2-json-over-websockets/discovery-scenarios.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Discovery in S2" ---- - -TODO \ No newline at end of file diff --git a/website/docs/s2-json-over-websockets/state-of-communication.md b/website/docs/s2-json-over-websockets/state-of-communication.md deleted file mode 100644 index 3d6e337..0000000 --- a/website/docs/s2-json-over-websockets/state-of-communication.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: "States of Communication" ---- - -# State of S2 session - -![image](/img/state_of_communication.png) - - -| State | Messages that can be sent by CEM /received by RM | Messages that can be sent by RM / received by CEM | -| --- | --- | --- | -| WebSocket Connected | Handshake HandshakeResponse ReceptionStatus | Handshake ReceptionStatus | -| Initialized | SelectControlType SessionRequest ReceptionStatus | ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | -| ControlType PEBC activated | PEBC.Instruction SelectControlType SessionRequest ReceptionStatus | PEBC.EnergyConstraint PEBC.PowerConstraint RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | -| ControlType PPBC activated | PPBC.EndInterrptionInstruction PPBC.ScheduleInstruction PPBC.StartInterruptionInstruction SelectControlType SessionRequest ReceptionStatus | PPBC.PowerProfileDefinition PPBC.PowerPorfileStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | -| ControlType OMBC activated | OMBC.Instruction SelectControlType SessionRequest ReceptionStatus | OMBC.Status OMBC.SystemDescription OMBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | -| ControlType FRBC activated | FRBC.Instruction SelectControlType SessionRequest ReceptionStatus | FRBC.ActuatorStatus FRBC.FillLevelTargetProfile FRBC.LeakageBehaviour FRBC.StorageStatus FRBC.SystemDescription FRBC.UsageForecast FRBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | -| ControlType DDBC activated | DDBC.Instruction SelectControlType SessionRequest ReceptionStatus | DDBC.ActuatorStatus DDBC.AverageDemandRateForecast DDBC.SystemDescription DDBC.TimerStatus RevokeObject InstructionStatusUpdate ResourceManagerDetails PowerMeasurement PowerForecast SessionRequest ReceptionStatus | \ No newline at end of file diff --git a/website/docs/welcome.md b/website/docs/welcome.md index d741d3b..7455fd0 100644 --- a/website/docs/welcome.md +++ b/website/docs/welcome.md @@ -1,6 +1,6 @@ --- title: "Introduction" -sidebar_position: 0 +sidebar_position: 1 pagination_next: null pagination_prev: null --- @@ -24,6 +24,6 @@ If you want to know more about the design principles of S2, you can continue rea Before starting to implement S2, make sure to familiarize yourself with the [concepts](/docs/concepts/architecture.md). -More information about the implementing protocol specification is provided [here](docs/s2-json-over-websockets/introduction.md). +More information about the implementing protocol specification is provided [here](docs/communication-layer/introduction.md). If you want to read about how to model energy flexibility from some typical devices, head over to the [examples](/docs/examples/ev.md). diff --git a/website/static/img/communication-layer/certificate-chains.png b/website/static/img/communication-layer/certificate-chains.png new file mode 100644 index 0000000..a52d6ec Binary files /dev/null and b/website/static/img/communication-layer/certificate-chains.png differ diff --git a/website/static/img/communication-layer/connection-initiation.png b/website/static/img/communication-layer/connection-initiation.png new file mode 100644 index 0000000..91258e3 Binary files /dev/null and b/website/static/img/communication-layer/connection-initiation.png differ diff --git a/website/static/img/communication-layer/deployment-options.png b/website/static/img/communication-layer/deployment-options.png new file mode 100644 index 0000000..3463120 Binary files /dev/null and b/website/static/img/communication-layer/deployment-options.png differ diff --git a/website/static/img/communication-layer/oauth2-s2.png b/website/static/img/communication-layer/oauth2-s2.png new file mode 100644 index 0000000..8ca5690 Binary files /dev/null and b/website/static/img/communication-layer/oauth2-s2.png differ diff --git a/website/static/img/communication-layer/pairing-manually.png b/website/static/img/communication-layer/pairing-manually.png new file mode 100644 index 0000000..79300a0 Binary files /dev/null and b/website/static/img/communication-layer/pairing-manually.png differ diff --git a/website/static/img/communication-layer/pairing-security.png b/website/static/img/communication-layer/pairing-security.png new file mode 100644 index 0000000..e7bcbd2 Binary files /dev/null and b/website/static/img/communication-layer/pairing-security.png differ diff --git a/website/static/img/communication-layer/state-of-communication.png b/website/static/img/communication-layer/state-of-communication.png new file mode 100644 index 0000000..6f362ee Binary files /dev/null and b/website/static/img/communication-layer/state-of-communication.png differ