You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2018/02/26 20:16:40 UTC
[incubator-plc4x] branch master updated: Continued cleaning up the
S7 documentation (In preparation of adding "S7 Comm Plus" protocol
documents)
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-plc4x.git
The following commit(s) were added to refs/heads/master by this push:
new 92892f9 Continued cleaning up the S7 documentation (In preparation of adding "S7 Comm Plus" protocol documents)
92892f9 is described below
commit 92892f9d3ca6ecebf640928b564b5950c3ecb4d2
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Mon Feb 26 21:16:37 2018 +0100
Continued cleaning up the S7 documentation (In preparation of adding "S7 Comm Plus" protocol documents)
---
src/site/asciidoc/protocols/s7/index.adoc | 274 +++++++++++++-----------
src/site/asciidoc/protocols/s7/s7comm-plus.adoc | 23 ++
src/site/asciidoc/protocols/s7/s7comm.adoc | 98 +++++++++
3 files changed, 268 insertions(+), 127 deletions(-)
diff --git a/src/site/asciidoc/protocols/s7/index.adoc b/src/site/asciidoc/protocols/s7/index.adoc
index 28a438e..fd259c1 100644
--- a/src/site/asciidoc/protocols/s7/index.adoc
+++ b/src/site/asciidoc/protocols/s7/index.adoc
@@ -16,66 +16,71 @@
//
:imagesdir: ../../img/
-== S7
+== S7 Communication
+
+When communicating with S7 Devices there is a whole family of protocols, that can be used.
+In general you can divide them into `Profinet` protocols and `S7 Comm` protocols.
+The later are far simpler in structure, but also far less documented.
+The `S7 Comm` protocols are generally split up into to flavours: The classic `S7 Comm` and a newer version called `S7 Comm Plus`.
=== Overview of the Protocols
[ditaa,protocols-s7-osi]
....
- : : implemented :
- : : | :
- : Profinet : | S7 Protocol :
- : : V :
-- - - - - - - - - - +-------------+-------------+-------------+-------------+-------------+-------------+
- |c0B0 |c0B0 |c0B0 |c0B0 |c0BA |c0BA |
- Application | | | | | | |
- Layer | | | | | | |
- | | | | | | |
- | Profinet IO | Profinet IO | Profinet CBA| Profinet CBA| | |
-- - - - - - - - - - | RT / IRT | | | RT | | | - -
- | | | | | | |
- Presentation | | | | | | |
- Layer | | | | | S7 | S7 |
- | | | | |Communication|Communication|
- | | | | | | |
-- - - - - - - - - - | +-------------+-------------+ | | | - -
- | |cAAA |cAAA | | | |
- Session | | | | | | |
- Layer | | RPC | DCOM | | | |
- | | | | | | |
- | | | | | | |
-- - - - - - - - - - | +-------------+-------------+ +-------------+-------------+ - -
- | |cAAA |cAAA | |cF6F |
- | | | | | ISO Transport Protocol |
- | | | | | RFC 905 |
- | | | | | (Class 0) |
- | | | | +-------------+ |
- | | | | |cFF6 | |
- Transport | | | | | ISO on TCP | |
- Layer | | UDP | TCP | | RFC 1006 | |
- | | | | +-------------+ |
- | | | | |cAAA | |
- | | | | | TCP | |
- | | | | | | ISO |
-- - - - - - - - - - | +-------------+-------------+ +-------------+ Transport | - -
- | | cAAA | |cAAA | Protocol |
- Network | | | | | RFC 905 |
- Layer | | IP | | IP | (Class 4) |
- | | | | | |
- | | | | | |
-- - - - - - - - - - +-------------+---------------------------+-------------+-------------+-------------+ - -
- |cAAA |
- Data Link | |
- Layer | |
- | |
- | Industrial |
-- - - - - - - - - - | Ethernet | - -
- | |
- Physical | |
- Layer | |
- | |
- | |
-- - - - - - - - - - +-----------------------------------------------------------------------------------+ - -
+ : : : implemented :
+ : : : | :
+ : Profinet : : | S7 Protocol :
+ : : : V :
+- - - - - - - - - - +-------------+-------------+-------------+-------------+-------------+-------------+-------------+ - -
+ |c0B0 |c0B0 |c0B0 |c0B0 |c05A |c0BA |c0BA |
+ Application | | | | | | | |
+ Layer | | | | | | | |
+ | | | | | | | |
+ | Profinet IO | Profinet IO | Profinet CBA| Profinet CBA| | | |
+- - - - - - - - - - | RT / IRT | | | RT | | | | - -
+ | | | | | | | |
+ Presentation | | | | | | | |
+ Layer | | | | | S7 | S7 | S7 |
+ | | | | | Comm | Comm | Comm |
+ | | | | | Plus | | |
+- - - - - - - - - - | +-------------+-------------+ | | | | - -
+ | |cAAA |cAAA | | | | |
+ Session | | | | | | | |
+ Layer | | RPC | DCOM | | | | |
+ | | | | | | | |
+ | | | | | | | |
+- - - - - - - - - - | +-------------+-------------+ +-------------+-------------+-------------+ - -
+ | |cAAA |cAAA | |cF6F |
+ | | | | | ISO Transport Protocol |
+ | | | | | RFC 905 |
+ | | | | | (Class 0) |
+ | | | | +---------------------------+ |
+ | | | | |cFF6 | |
+ Transport | | | | | ISO on TCP | |
+ Layer | | UDP | TCP | | RFC 1006 | |
+ | | | | +---------------------------+ |
+ | | | | |cAAA | |
+ | | | | | TCP | |
+ | | | | | | ISO |
+- - - - - - - - - - | +-------------+-------------+ +---------------------------+ Transport | - -
+ | | cAAA | |cAAA | Protocol |
+ Network | | | | | RFC 905 |
+ Layer | | IP | | IP | (Class 4) |
+ | | | | | |
+ | | | | | |
+- - - - - - - - - - +-------------+---------------------------+-------------+---------------------------+-------------+ - -
+ |cAAA |
+ Data Link | |
+ Layer | |
+ | |
+ | Industrial |
+- - - - - - - - - - | Ethernet | - -
+ | |
+ Physical | |
+ Layer | |
+ | |
+ | |
+- - - - - - - - - - +-------------------------------------------------------------------------------------------------+ - -
....
=== Protocol Descriptions
@@ -85,61 +90,57 @@
|Transmission Control Protocol (TCP) |- | RFC 793 |https://tools.ietf.org/html/rfc793
|ISO Transport Protocol (Class 4) |ISO DP 8073 | RFC 905 |https://tools.ietf.org/html/rfc905
|ISO on TCP |- | RFC 1006| https://tools.ietf.org/html/rfc1006
-|S7 Protocol |- |- |http://gmiru.com/article/s7comm/ http://gmiru.com/article/s7comm-part2/
+|S7 Comm (0x32) |- |- |http://gmiru.com/article/s7comm/ http://gmiru.com/article/s7comm-part2/
+|S7 Comm Plus (0x72) |- |- |https://opensource-security.de/thesis/MA_Maik_Brueggemann.pdf
|RPC |- | RFC 1057 & RFC 5531 |https://tools.ietf.org/html/rfc1057 https://tools.ietf.org/html/rfc5531
|DCOM |- |- | https://msdn.microsoft.com/library/cc201989.aspx
|===
-While a lot of information was available on the general structure of S7 communication, only little information was available on the constant values this protocol uses.
-If information was available, this was mostly provided with a GPL license and therefore was disqualified for being used in this project.
-The information on the S7 constants in this project were therefore generated by a little tool that generates "pcapng" files `WireShark` can process.
-The tool then generated 256 versions of a given template with the only difference being the one byte having all possible values.
-Using the `tshark` commandline tool, the generated packets were decoded to an XML format.
-For each examined byte an XPath expression was created to detect valid values.
-As soon as a valid value was found the tool then output the detected constant value to the console.
+=== Interaction with an S7 PLC
+
+Currently we are concentrating on implementing the TCP-based variants of the `S7 Comm` and `S7 Comm Plus` protocols.
+Both are transferred using `ISO TP` which is wrapped by `ISO on TCP`.
+Both protocols require establishing a connection on the `ISO TP` level first.
+After the `ISO TP` connection is established, the higher level protocols then establish their connections.
+These are then handled by the individual protocol sub-pages:
-The tool for generating this is located in the `plc4j/protocols/s7-utils` project.
+- link:s7comm.html[S7 Comm (0x32)]
+- link:s7comm-plus.html[S7 Comm Plus (0x72)]
-=== Interaction with an S7 PLC
+The hex-value behind each of these correlates to the first byte used in the protocols messages to indicate the type of protocol.
[seqdiag,s7-interaction]
....
{
- group Client {
- Client;
- }
-
- group PLC {
- "ISO TP";
- S7;
- }
-
=== Connect ===
Client -> "ISO TP" [label = "Connection Request"]
Client <- "ISO TP" [label = "Connection Response"]
- Client -> "ISO TP" [label = "Setup Communication Request"]
- "ISO TP" -> S7 [label = "Setup Communication"]
- "ISO TP" <-- S7
- Client <- "ISO TP" [label = "Setup Communication Response"]
- === Read ===
+ === Higher Level Connect ===
- Client -> "ISO TP" [label = "Read Request"]
- "ISO TP" -> S7 [label = "Read"]
- "ISO TP" <-- S7
- Client <- "ISO TP" [label = "Read Response"]
+ === Higher Level Communication ===
- === Write ===
+ === Disconnect ===
+
+ Client -> "ISO TP" [label = "Disconnect Request"]
- Client -> "ISO TP" [label = "Write Request"]
- "ISO TP" -> S7 [label = "Write"]
- "ISO TP" <-- S7
- Client <- "ISO TP" [label = "Write Response"]
}
....
-==== Structure of a Connection Request
+=== ISO TP Message Types
+
+Even if `ISO TP` defines more types of messages, the ones required for `S7 Comm` or `S7 Comm Plus` are only the following.
+Each message is called a `TPDU` (Transport Protocol Data Unit):
+
+- Connection Request TPDU
+- Connection Response TPDU
+- Data TPDU
+- Disconnect Request TPDU
+
+Notice: There is no `Disconnect Response` in `ISO TP: Class 0`.
+
+==== Connection Request TPDU
// len (length of bits - use instead of explicit byte count - requires "*" as first element)
// label
@@ -153,7 +154,7 @@ The tool for generating this is located in the `plc4j/protocols/s7-utils` projec
// stacked (no value)
// icon
// shape (box, circle, ...)
-[packetdiag,s7-connection-request,svg]
+[packetdiag,s7-connect-request,svg]
....
{
colwidth = 32
@@ -197,13 +198,25 @@ Legend:
- [protocolId]#Part of the packet that identifies the type of request#
- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
-==== Structure of a Connection Response
+==== Connection Response TPDU
The `Connection Response` is identical to the `Connection Request` with the only difference that the `TPDU-Code` has a code of `0xD0`.
-==== Structure of a Setup Communication Request
+==== Data TPDU
-[packetdiag,s7-setup-communication-request,svg]
+// len (length of bits - use instead of explicit byte count - requires "*" as first element)
+// label
+// color / background
+// linecolor
+// rotate (degrees)
+// colheight
+// height
+// numbered
+// label_orientation (vertical, horizontal)
+// stacked (no value)
+// icon
+// shape (box, circle, ...)
+[packetdiag,s7-data,svg]
....
{
colwidth = 32
@@ -215,29 +228,10 @@ The `Connection Response` is identical to the `Connection Request` with the only
// ISO Transport Protocol
* ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
- * TPDU-Code\n(Data = 0xF0) [len = 4, color = "#AEECEF"]
+ * TPDU-Code\n(DATA = 0xF0) [len = 4, color = "#AEECEF"]
* Signal CDT\n(0x00) [len = 4, color = "#53599A"]
- // ISO TP Header (Fixed Part)
- * Destination Reference (0x??)[len = 16, color = "#53599A"]
- * Source Reference (0x??)[len = 16, color = "#53599A"]
- * Protocol Class\n(Class 0 = 0x00) [len = 8, color = "#53599A"]
+ * TPDU-NR/EOT [len = 8, color = "#53599A"]
- // S7
- 96-103: S7 Protocol Magic Byte (0x32) [color = "#6D9DC5"]
- * Message Type (JOB = 0x01) [len = 8, color = "#AEECEF"]
- * Reserved (0x0000) [len = 16, color = "#6D9DC5"]
- * PDU Reference (0x??)[len = 16, color = "#6D9DC5"]
- * S7 Parameters Length (8 = 0x08) [len = 16, color = "#6D9DC5"]
- * S7 Data Length (0 = 0x00) [len = 16, color = "#6D9DC5"]
-
- // S7 Parameters
- * Function\n(Setup Communication = 0xF0) [len = 8, color = "#AEECEF"]
- * Reserved (0x00) [len = 8, color = "#6D9DC5"]
- * Max AMQ Caller [len = 16, color = "#80DED9"]
- * Max AMQ Callee [len = 16, color = "#80DED9"]
- * PDU Size [len = 16, color = "#80DED9"]
-
- // S7 Data
}
....
@@ -245,25 +239,51 @@ Legend:
- [protocolIsoOnTcp]#ISO on TCP Packet Header#
- [protocolIsoTP]#ISO Transport Protocol Packet Header#
-- [protocolS7]#S7 Protocol#
- [protocolId]#Part of the packet that identifies the type of request#
-- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
-==== Structure of a Setup Communication Response
+==== Disconnect Request TPDU
-The `Setup Communication Response` is identical to the `Setup Communication Request` with the only difference that the `Message Type` has an ACK_DATA code of `0x03`.
+// len (length of bits - use instead of explicit byte count - requires "*" as first element)
+// label
+// color / background
+// linecolor
+// rotate (degrees)
+// colheight
+// height
+// numbered
+// label_orientation (vertical, horizontal)
+// stacked (no value)
+// icon
+// shape (box, circle, ...)
+[packetdiag,s7-disconnect-request,svg]
+....
+{
+ colwidth = 32
-Also does the response eventually provide different values for `Max AMQ Caller`, `Max AMQ Callee` and `PDU Size`.
+ // ISO on TCP
+ * ISO on TCP Magic Number (0x03) [len = 8, color = "#068D9D"]
+ * Reserved (0x00) [len = 8, color = "#068D9D"]
+ * Packet Length (including ISO on TCP header) [len = 16, color = "#068D9D"]
-The values might be lower than in the request, but never higher.
+ // ISO Transport Protocol
+ * ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
+ * TPDU-Code\n(DR = 0x80) [len = 4, color = "#AEECEF"]
+ * Signal CDT\n(0x00) [len = 4, color = "#53599A"]
+ * Destination Reference [len = 16, color = "#53599A"]
+ * Source Reference [len = 16, color = "#53599A"]
+ * Reason [len = 8, color = "#53599A"]
-TIP: One thing about `Setup Communication Responses` which is kind of strange, is that usually S7 response messages have additional `error class` and `error code` fields, which this type of response doesn't seem to have.
+ // ISO TP Header (Variable Part / Parameters) (Optional)
+ * Parameter Code\n(Disconnect Additional Information = 0xE0) [len = 8, color = "#53599A"]
+ * Parameter Length\n(1 ... 128) [len = 8, color = "#53599A"]
+ * Parameter Data\n(Custom user data) [len = 24, color = "#53599A"]
-=== Links
+}
+....
-Providing some additional information without directly being used:
+Legend:
-- High Level description: http://snap7.sourceforge.net/siemens_comm.html
-- https://support.industry.siemens.com/cs/document/26483647/welche-eigenschaften-vorteile-und-besonderheiten-bietet-das-s7-protokoll-?dti=0&lc=de-WW
-- Interesting presentation mentioning a new protocol flavor 0x72 instead of the old 0x32: https://www.research.ibm.com/haifa/Workshops/security2014/present/Avishai_Wool_AccurateModelingoftheSiemensS7SCADAProtocol-v5.pdf
-- Open Source SCADA System: https://www.eclipse.org/eclipsescada/
\ No newline at end of file
+- [protocolIsoOnTcp]#ISO on TCP Packet Header#
+- [protocolIsoTP]#ISO Transport Protocol Packet Header#
+- [protocolId]#Part of the packet that identifies the type of request#
+- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
diff --git a/src/site/asciidoc/protocols/s7/s7comm-plus.adoc b/src/site/asciidoc/protocols/s7/s7comm-plus.adoc
new file mode 100644
index 0000000..45cffc8
--- /dev/null
+++ b/src/site/asciidoc/protocols/s7/s7comm-plus.adoc
@@ -0,0 +1,23 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+:imagesdir: ../../img/
+
+== S7 Comm Plus (0x72)
+
+==== General
+
+...
diff --git a/src/site/asciidoc/protocols/s7/s7comm.adoc b/src/site/asciidoc/protocols/s7/s7comm.adoc
new file mode 100644
index 0000000..a3996f9
--- /dev/null
+++ b/src/site/asciidoc/protocols/s7/s7comm.adoc
@@ -0,0 +1,98 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+:imagesdir: ../../img/
+
+== S7 Comm (0x32)
+
+==== General
+
+While a lot of information was available on the general structure of S7 communication, only little information was available on the constant values this protocol uses.
+If information was available, this was mostly provided with a GPL license and therefore was disqualified for being used in this project.
+The information on the S7 constants in this project were therefore generated by a little tool that generates "pcapng" files `WireShark` can process.
+The tool then generated 256 versions of a given template with the only difference being the one byte having all possible values.
+Using the `tshark` commandline tool, the generated packets were decoded to an XML format.
+For each examined byte an XPath expression was created to detect valid values.
+As soon as a valid value was found the tool then output the detected constant value to the console.
+
+The tool for generating this is located in the `plc4j/protocols/s7-utils` project.
+
+==== Structure of a Setup Communication Request
+
+[packetdiag,s7-setup-communication-request,svg]
+....
+{
+ colwidth = 32
+
+ // ISO on TCP
+ * ISO on TCP Magic Number (0x03) [len = 8, color = "#068D9D"]
+ * Reserved (0x00) [len = 8, color = "#068D9D"]
+ * Packet Length (including ISO on TCP header) [len = 16, color = "#068D9D"]
+
+ // ISO Transport Protocol
+ * ISO TP Header Length\n(excluding length byte) [len = 8, color = "#53599A"]
+ * TPDU-Code\n(Data = 0xF0) [len = 4, color = "#AEECEF"]
+ * Signal CDT\n(0x00) [len = 4, color = "#53599A"]
+ // ISO TP Header (Fixed Part)
+ * Destination Reference (0x??)[len = 16, color = "#53599A"]
+ * Source Reference (0x??)[len = 16, color = "#53599A"]
+ * Protocol Class\n(Class 0 = 0x00) [len = 8, color = "#53599A"]
+
+ // S7
+ 96-103: S7 Protocol Magic Byte (0x32) [color = "#6D9DC5"]
+ * Message Type (JOB = 0x01) [len = 8, color = "#AEECEF"]
+ * Reserved (0x0000) [len = 16, color = "#6D9DC5"]
+ * PDU Reference (0x??)[len = 16, color = "#6D9DC5"]
+ * S7 Parameters Length (8 = 0x08) [len = 16, color = "#6D9DC5"]
+ * S7 Data Length (0 = 0x00) [len = 16, color = "#6D9DC5"]
+
+ // S7 Parameters
+ * Function\n(Setup Communication = 0xF0) [len = 8, color = "#AEECEF"]
+ * Reserved (0x00) [len = 8, color = "#6D9DC5"]
+ * Max AMQ Caller [len = 16, color = "#80DED9"]
+ * Max AMQ Callee [len = 16, color = "#80DED9"]
+ * PDU Size [len = 16, color = "#80DED9"]
+
+ // S7 Data
+}
+....
+
+Legend:
+
+- [protocolIsoOnTcp]#ISO on TCP Packet Header#
+- [protocolIsoTP]#ISO Transport Protocol Packet Header#
+- [protocolS7]#S7 Protocol#
+- [protocolId]#Part of the packet that identifies the type of request#
+- [protocolParameter]#Variable Parts of the ISO Transport Protocol Packet Header#
+
+==== Structure of a Setup Communication Response
+
+The `Setup Communication Response` is identical to the `Setup Communication Request` with the only difference that the `Message Type` has an ACK_DATA code of `0x03`.
+
+Also does the response eventually provide different values for `Max AMQ Caller`, `Max AMQ Callee` and `PDU Size`.
+
+The values might be lower than in the request, but never higher.
+
+TIP: One thing about `Setup Communication Responses` which is kind of strange, is that usually S7 response messages have additional `error class` and `error code` fields, which this type of response doesn't seem to have.
+
+=== Links
+
+Providing some additional information without directly being used:
+
+- High Level description: http://snap7.sourceforge.net/siemens_comm.html
+- https://support.industry.siemens.com/cs/document/26483647/welche-eigenschaften-vorteile-und-besonderheiten-bietet-das-s7-protokoll-?dti=0&lc=de-WW
+- Interesting presentation mentioning a new protocol flavor 0x72 instead of the old 0x32: https://www.research.ibm.com/haifa/Workshops/security2014/present/Avishai_Wool_AccurateModelingoftheSiemensS7SCADAProtocol-v5.pdf
+- Open Source SCADA System: https://www.eclipse.org/eclipsescada/
\ No newline at end of file
--
To stop receiving notification emails like this one, please contact
cdutz@apache.org.