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 <christofer.d...@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 cd...@apache.org.