Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Every decoder works on a byte slice through `cip.Reader`, whose first
short read sets a sticky error, or checks lengths before slicing. Counts in
messages (items, services, segments, attributes, tags) are compared with
the octets that carry them before anything is allocated, and are bounded
(`encap.MaxItems`, the 255-word path limit, 256 path segments, 200 embedded
(`encap.MaxItems`, the 255-word path limit, 256 path segments, 1000 embedded
services, `WithMaxPacket` for whole packets). Fuzz targets cover every
decoder and the server's dispatch of Logix requests; the corpus seeds are
in `testdata/fuzz`.
89 changes: 89 additions & 0 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,94 @@
# go-ethernetip Releases

## v0.7.0

**Date:** 2026-11-14
**Previous release:** v0.6.0

## Summary

Tighter bounds and lifecycles in the server, the scanner, the Logix client
and emulation, and the EDS package. The server frees the place of a
connection whose TLS handshake fails, stops building a reply as soon as it
exceeds what the packet or connection can carry, and no longer leaves a
multicast producer running when a Forward_Close arrives during the
Forward_Open. The scanner checks the actual packet intervals of a
Forward_Open reply. The Logix client bounds the tag list and template
reads like the fragmented read. EDS files with several spellings of one
number give one entry, and Validate runs in linear time. The public API is
unchanged.

## Changes

### Fixes

- **server**: a connection whose TLS handshake fails frees its place under
the TCP connection limit (2 × `WithMaxSessions` + 16); before, it held it
until `Close`.
- **server**: Multiple Service Packet, Get_Attribute_List and
Get_Attributes_All stop with 0x11 (reply data too large) as soon as the
reply exceeds what the encapsulation packet or the Class 3 connection can
carry, instead of building the whole reply first. Replies that fit are
unchanged.
- **server**: a Forward_Close that arrives while a multicast Forward_Open
is handled no longer leaves a multicast producer running (the
Forward_Open is answered 0x31C); the change-of-state producer set is
updated together with the connection's close.
- **server**: a connection opened while the server closes is refused
(0x31C), and the Class 3 inactivity timer always stops with its
connection.
- **server**: delayed ListIdentity replies (`WithDiscoveryDelay`) still
waiting at `Close` are dropped; none is sent after `Close` returns.
- **implicit**: `Endpoint.Close` also closes connections that only
produce, as documented.
- **scanner**: `Open` refuses a Forward_Open reply with a T->O actual
packet interval of 0 or an O->T actual packet interval below a quarter of
the requested RPI (and below 100 µs), with `ErrProtocol`, and closes that
connection again.
- **scanner**: O->T data of a point-to-point connection goes to the
target's address, at the port named in the Sockaddr Info O->T item;
another address in that item is ignored.
- **logix**: `Client.ListTags` stops with `ErrProtocol` after 65536 partial
replies or 16 MiB of reply data, like a fragmented read;
`Client.Template` stops after 65536 Read_Template replies.
- **logix**: `TagServer` compares BOOL array indices as 32-bit values, so
indices of 0x80000000 and above are answered with "access beyond end" on
32-bit platforms too.
- **logix**: `TagServer` answers Read-Modify-Write on an array member of no
elements with "access beyond end" instead of reading beyond the tag, and
a Template Get_Attribute_List whose reply exceeds the reply size with
0x11.
- **logix**: `TagServer.AddTag` and `AddStructTag` compute tag sizes without
integer overflow and refuse tags above 16 MiB on every platform.
- **logix**: template decoding refuses structure members above 2 GiB;
template definitions are parsed without splitting the data after the
member names.
- **eds**: keywords that name the same number (`Param1` and `Param01`, or a
repeated `Param1`) give one parameter, enum, assembly or connection: the
first. `GenerateGo` output no longer grows with such copies, and
`Validate` reports them as errors.
- **eds**: `Validate` looks up entries through a per-section index, so its
run time is linear in the number of assemblies, connections and
references.

### Tests

- New regression tests in server (TLS handshake failures, reply budgets,
Forward_Close during a multicast Forward_Open, opening while closing,
delayed discovery at Close), implicit (`Endpoint.Close` of producers),
scanner (reply intervals, Sockaddr O->T address), logix (tag list and
template reply limits, BOOL array indices, tag sizes) and eds (numbered
entries, many assemblies).

### Documentation

- SECURITY.md, docs/LIMITATIONS.md and docs/IMPLICIT.md describe the new
bounds and the scanner's handling of actual packet intervals;
ARCHITECTURE.md gives the Multiple Service Packet limit as 1000 embedded
services, as the code has it.

---

## v0.6.0

**Date:** 2026-11-08
Expand Down
10 changes: 7 additions & 3 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,13 @@ The server bounds what a peer can make it hold:
- packets above `WithMaxPacket` (4096 octets by default) close the
session; sessions are limited by `WithMaxSessions` (64), connections by
`WithMaxConnections` (128), and per originator address by
`WithMaxConnectionsPerOriginator` (off by default); Class 3 replies are
bounded by the connection's T->O size; idle TCP connections close after the
encapsulation inactivity timeout (120 s);
`WithMaxConnectionsPerOriginator` (off by default); a connection whose
TLS handshake fails frees its place at once; Class 3 replies are bounded
by the connection's T->O size and unconnected replies by the
encapsulation packet, and Multiple Service Packet, Get_Attribute_List and
Get_Attributes_All stop with 0x11 as soon as the reply being built
exceeds that bound; idle TCP connections close after the encapsulation
inactivity timeout (120 s);
- every count in a message (items, services, segments, attributes, tag
list entries) is checked against the octets that carry it before memory
is allocated, and bounded; the fuzz targets check this, and found two
Expand Down
11 changes: 11 additions & 0 deletions docs/IMPLICIT.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,17 @@ multicast on most systems. Groups are joined on the interface of
else on the bound address's interface, else on the system's choice (the
default route's).

## Actual packet intervals

The scanner produces and watches at the actual packet intervals of the
target's Forward_Open reply, which may differ from the requested RPI. It
refuses a reply (`ErrProtocol`, and closes the connection again with
Forward_Close) whose T->O interval is 0 or whose O->T interval is below
max(O->T RPI / 4, min(RPI, 100 µs)). O->T data of a point-to-point
connection goes to the target's address, at the port of the reply's
Sockaddr Info O->T item when it has one; another address in that item is
ignored.

## Timeouts and recovery

The consumer of each direction times out after RPI × 4 << multiplier
Expand Down
8 changes: 4 additions & 4 deletions docs/LIMITATIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@
| I/O security | the server filters O->T datagrams by source address only; a host on the same network that spoofs the originator can inject data | EtherNet/IP I/O is unauthenticated without DTLS |
| Class 1 delivery | `OnData` may be called once more while `Close` runs | a callback lock would deadlock callbacks that call `Close` |
| Multicast | needs `IP_ADD_MEMBERSHIP` (Unix, Windows); TTL is the system default | stdlib only |
| ListIdentity over UDP | the server's reply delay applies only when `WithDiscoveryDelay` is set; at most 256 delayed replies wait at once, later requests go unanswered | without IP_PKTINFO the server cannot tell broadcast from unicast; the bound keeps a request flood from piling up timers |
| Server limits | at most 2 × `WithMaxSessions` + 16 TCP connections, registered or not; `WithMaxConnections` at most 65535; one originator address may hold them all unless `WithMaxConnectionsPerOriginator` is set (originators behind one NAT address share that limit); Class 3 replies are bounded by the connection's T->O size and a Class 3 request larger than its O->T size is still served; the class attributes Max Instance and Number of Instances, and the Message Router's class list, saturate at 0xFFFF | unregistered connections must be bounded too; those attributes are UINTs while instance IDs are 32-bit |
| Logix emulation | tags and templates only: no programs, tasks, modes, alarms, access control; templates are what you give it, with at most 65535 members | a test tool; the member count attribute is a UINT |
| Logix client | no CIP Generic MSG, no alarm/event, no program-scoped tag write by instance; a fragmented read stops at 16 MiB or 65536 fragments, a write above 16 MiB is refused, a template definition above 1 MiB is refused | not needed for tag access; replies are untrusted input |
| ListIdentity over UDP | the server's reply delay applies only when `WithDiscoveryDelay` is set; at most 256 delayed replies wait at once, later requests go unanswered; replies still waiting at Close are dropped | without IP_PKTINFO the server cannot tell broadcast from unicast; the bound keeps a request flood from piling up timers |
| Server limits | at most 2 × `WithMaxSessions` + 16 TCP connections, registered or not (a failed TLS handshake frees its place); `WithMaxConnections` at most 65535; one originator address may hold them all unless `WithMaxConnectionsPerOriginator` is set (originators behind one NAT address share that limit); Class 3 replies are bounded by the connection's T->O size and unconnected replies by the encapsulation packet (a reply that exceeds them is answered 0x11 before it is built in full), and a Class 3 request larger than its O->T size is still served; the class attributes Max Instance and Number of Instances, and the Message Router's class list, saturate at 0xFFFF | unregistered connections must be bounded too; those attributes are UINTs while instance IDs are 32-bit |
| Logix emulation | tags and templates only: no programs, tasks, modes, alarms, access control; templates are what you give it, with at most 65535 members; a tag above 16 MiB is refused | a test tool; the member count attribute is a UINT |
| Logix client | no CIP Generic MSG, no alarm/event, no program-scoped tag write by instance; a fragmented read stops at 16 MiB or 65536 fragments, the tag list at 16 MiB of replies or 65536 replies, a template definition at 65536 replies, a write above 16 MiB is refused, a template definition above 1 MiB is refused | not needed for tag access; replies are untrusted input |
| EDS | the connection bit masks are exposed raw, not interpreted; generated scanner configurations use the default real-time formats | the EDS specification is not available |
| EDS sizes | an assembly member above `8*eds.MaxAssemblySize` bits (524280) is rejected, and `GenerateGo` writes no struct for an assembly whose members add up to more than `eds.MaxAssemblySize` octets | the assembly size field is 16 bits; EDS files are untrusted input |
| Recorded traffic | the recordings ([testdata/captures](../testdata/captures/README.md)) are of a 1756-L63 (firmware 15.4) and a 1756-ENBT/A (4.3) with RSLinx and FactoryTalk from 2008, a Micro850 (12.11) and a MicroLogix 1400 from 2017–2019, and unidentified targets; no recording of Large_Forward_Open, Read/Write Tag Fragmented, the tag list, structures, CompactLogix, a third-party adapter or I/O with its Forward_Open; symbolic Read/Write Tag only of BOOL tags (Micro850); PCCC is not implemented; Template Get_Attributes_All is not implemented (its third attribute is not identified); the server does not answer command 0x0001, the Identity attributes 0x65/0x66 or the Micro800 objects | no other recording with an identified device was found |
Expand Down
2 changes: 1 addition & 1 deletion docs/api/eds.md
Original file line number Diff line number Diff line change
Expand Up @@ -360,7 +360,7 @@ func Validate(f *File) []Issue

Validate checks a file and returns its issues, errors first. A file with no Error issue can be used by the typed views and the generator.

It checks: [File](#type-file) and [Device](#type-device) come first, with their required entries; dates, times and revisions are well formed; numbers are numbers; data types of parameters are elementary types whose size matches; minimum, maximum and default are ordered; ParamN and AssemN references resolve; EPATHs decode; assembly members fill their size; keywords are not repeated within a section.
It checks: [File](#type-file) and [Device](#type-device) come first, with their required entries; dates, times and revisions are well formed; numbers are numbers; data types of parameters are elementary types whose size matches; minimum, maximum and default are ordered; ParamN and AssemN references resolve; EPATHs decode; assembly members fill their size; keywords are not repeated within a section, and no two ParamN, EnumN, AssemN or ConnectionN keywords name the same number (Param1 and Param01).

#### func (Issue) String

Expand Down
1 change: 1 addition & 0 deletions docs/api/implicit.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@ Trigger produces a datagram now, in addition to the cyclic ones: a change of sta
type Endpoint struct {

// consumers by consumed connection ID
// every open connection, producers too
// multicast memberships, counted
// the interface address each group was joined on
// the default multicast interface address
Expand Down
4 changes: 2 additions & 2 deletions docs/api/logix.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ DecodeStruct decodes the first element of a structure value, reading the templat
func (c *Client) ListTags(ctx context.Context, program string) ([]Tag, error)
```

ListTags reads the tag list of the Symbol object with Get Instance Attribute List (0x55): controller-scoped tags when program is "", the tags of a program ("Program:Main") otherwise. System tags and the names of programs are included as the controller reports them.
ListTags reads the tag list of the Symbol object with Get Instance Attribute List (0x55): controller-scoped tags when program is "", the tags of a program ("Program:Main") otherwise. System tags and the names of programs are included as the controller reports them. Like a fragmented read, the list stops with ethernetip.ErrProtocol beyond 16 MiB of replies or 65536 replies.

#### func (Client) ProgramName

Expand Down Expand Up @@ -139,7 +139,7 @@ ReadMany reads one element of each tag in one Multiple Service Packet (per batch
func (c *Client) Template(ctx context.Context, id uint16) (*Template, error)
```

Template reads a structure template (Template object instance id): its attributes, then its definition with Read\_Template. Templates are cached.
Template reads a structure template (Template object instance id): its attributes, then its definition with Read\_Template (at most 65536 replies, like a fragmented read). Templates are cached.

#### func (Client) Write

Expand Down
10 changes: 9 additions & 1 deletion docs/api/scanner.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Package scanner is the originator (scanner) of EtherNet/IP implicit I/O connecti
io.SetOutput(out)
in, run, at := io.Input()

The scanner's I/O endpoint listens on UDP port 2222 by default, the port targets send to; WithLocalAddr picks another, which Forward\_Open then announces in a Sockaddr Info item (not every target honours it).
The scanner's I/O endpoint listens on UDP port 2222 by default, the port targets send to; WithLocalAddr picks another, which Forward\_Open then announces in a Sockaddr Info item (not every target honours it). O->T data goes to the target's address, at the port the target's Sockaddr Info O->T item names (2222 without one).

## Types

Expand Down Expand Up @@ -124,6 +124,14 @@ type IOConfig struct {
InputSize int
// RPI is the requested packet interval of both directions; OTRPI and
// TORPI, when set, replace it per direction.
//
// The target answers with the actual packet intervals (APIs), which
// the connection then uses and [IO.Info] reports; they may differ from
// the RPIs. Open refuses the reply with ErrProtocol, and closes the
// connection again, when the T->O API is 0 (no consumption timeout)
// or the O->T API is below a quarter of the O->T RPI or below 100 µs
// (the O->T RPI itself when that is shorter), so that the scanner
// never produces more than four times as often as asked.
RPI time.Duration
OTRPI time.Duration
TORPI time.Duration
Expand Down
3 changes: 3 additions & 0 deletions docs/api/server.md
Original file line number Diff line number Diff line change
Expand Up @@ -378,6 +378,9 @@ type Server struct {

// pendingDiscovery counts the delayed UDP replies waiting in timers.

// delayed are the timers of the delayed UDP replies, by a sequence
// number; under mu. Close stops them.

}
```

Expand Down
38 changes: 38 additions & 0 deletions eds/generate_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -424,3 +424,41 @@ func TestGenerateNoParams(t *testing.T) {
t.Error("no Key")
}
}

// TestGenerateNumberedOnce checks that keywords naming the same number
// (Param1, Param01, Enum01) give one declaration: the typed views
// and GenerateGo keep the first entry of each number.
func TestGenerateNumberedOnce(t *testing.T) {
one := valid + "[Params]\n" + param("1", "0xC7", "2", `"Mode"`, "0, 2, 0") +
"\tEnum1 = 0, \"Off\", 1, \"On\", 2, \"Auto\";\n" +
"[Assembly]\n\tAssem1 = \"a\", \"20 04 24 01\", 2, 0, ,, 16, Param1;\n" +
"[Connection Manager]\n\tConnection1 = 1, 0, ,,, ,,, ,,,, \"c\", \"\", \"20 04 24 01\";\n"
var copies strings.Builder
for _, kw := range []string{"01", "001", "0000000001"} {
copies.WriteString(param(kw, "0xC7", "2", `"Mode`+kw+`"`, "0, 2, 0"))
}
src := strings.Replace(one, "\tEnum1 =", copies.String()+"\tEnum01 = 0, \"X\";\n\tEnum1 =", 1)
src = strings.Replace(src, "[Connection Manager]\n", "\tAssem001 = \"b\", \"20 04 24 02\", 4, 0;\n[Connection Manager]\n", 1)
src += "\tConnection01 = 1, 0, ,,, ,,, ,,,, \"d\", \"\", \"20 04 24 02\";\n"
f := mustParse(t, src)
ps, err := f.Params()
if err != nil {
t.Fatal(err)
}
if len(ps) != 1 || ps[0].Name != "Mode" || len(ps[0].Enum) != 1 || ps[0].Enum[0].Name != "X" {
t.Errorf("params %+v, want the first Param1 with the first Enum1", ps)
}
as, err := f.Assemblies()
if err != nil || len(as) != 1 || as[0].Name != "a" {
t.Errorf("assemblies %+v %v", as, err)
}
cs, err := f.Connections()
if err != nil || len(cs) != 1 || cs[0].Name != "c" {
t.Errorf("connections %+v %v", cs, err)
}
// The output does not grow with the copies.
want := generate(t, strings.Replace(one, `0, "Off", 1, "On", 2, "Auto"`, `0, "X"`, 1))
if got := generate(t, src); !bytes.Equal(got, want) {
t.Errorf("output of %d octets, want the %d octets of one entry per number", len(got), len(want))
}
}
26 changes: 20 additions & 6 deletions eds/model.go
Original file line number Diff line number Diff line change
Expand Up @@ -208,26 +208,40 @@ func (f *File) Device() (Device, error) {
}

// numbered returns the entries of s whose keyword is prefix followed by a
// number, sorted by the number.
// number, sorted by the number. Spellings such as Param1 and Param01 name
// the same number; only the first entry of each number is returned
// ([Validate] reports the others).
func numbered(s *Section, prefix string) []numberedEntry {
if s == nil {
return nil
}
var out []numberedEntry
seen := map[int]bool{}
for _, e := range s.Entries {
if len(e.Keyword) <= len(prefix) || !strings.EqualFold(e.Keyword[:len(prefix)], prefix) {
continue
}
n, err := strconv.Atoi(e.Keyword[len(prefix):])
if err != nil || n < 0 {
n, ok := keywordNumber(e.Keyword, prefix)
if !ok || seen[n] {
continue
}
seen[n] = true
out = append(out, numberedEntry{n, e})
}
sort.SliceStable(out, func(i, j int) bool { return out[i].n < out[j].n })
return out
}

// keywordNumber returns N of a keyword that is prefix (case-insensitive)
// followed by a non-negative decimal number N.
func keywordNumber(kw, prefix string) (int, bool) {
if len(kw) <= len(prefix) || !strings.EqualFold(kw[:len(prefix)], prefix) {
return 0, false
}
n, err := strconv.Atoi(kw[len(prefix):])
if err != nil || n < 0 {
return 0, false
}
return n, true
}

type numberedEntry struct {
n int
e Entry
Expand Down
Loading
Loading