Repository navigation
Releases
go-iec60870-5 v0.9.0
Date: 2026-11-16
Previous release: v0.8.0
Opt-in pacing of the iec102 server's answers and of the iec103 server's
disturbance channels by the controlling station's polls, an
iec103.MEAOf that sets ER for NaN, tls.Config callbacks and
sec.Config.OnEvent of the IEC 104 client and server that end only what
they belong to, an IEC 104 Connect that fails with ErrClosed when
its Dialer stops during Close, and an IEC 104 test station that
listens on loopback. Three changes of behaviour are breaking; each says
who notices and how to get the previous behaviour back. Two fields are
added; no identifier is removed or changed, and no default changes.
Breaking
iec103:MEAOf(NaN)returnsMEA{Error: true}: ER set ("MVAL is
not a valid value", clause 7.2.6.8) and MVAL 0. Before, it converted
NaN toint16, a result that Go leaves to the platform, without ER.
Who notices: an application that passes NaN for a measurand it has no
value for, and a controlling system that then sees ER set where it saw
a plain value. Previous behaviour: passiec103.MEA{}instead of
MEAOf(v)whenmath.IsNaN(v).iec104/client: a callback of thetls.Configgiven toWithTLS
(GetClientCertificate,VerifyPeerCertificate,VerifyConnection
and the others the handshake calls) or thesec.Config.OnEventof the
WithSecurityendpoint that does not return normally is logged at
Error ascallback did not return normallywith its stack and closes
the client:Connect, the reconnect loop or the request in progress
fails withiec104.ErrClosed, and the state handler is told
"disconnected" with an error that namestls.Config callbackor
sec.Config.OnEvent. Who notices: an application whose callback ended
the process. Previous behaviour: the process ended; an application
that wants that ends it itself in the callback.iec104/server: a callback of thetls.ConfigofWithTLS, or of a
TLS listener given toServe(GetCertificate,GetConfigForClient,
VerifyPeerCertificate,VerifyConnectionand the others), that does
not return normally is logged with its stack and rejects only that
connection, as forWithAccept: Warnconnection rejectedwith the
reasontls.Config callback did not return normally. A session's
sec.Config.OnEventthat does not return normally is logged with its
stack and ends that session. The server serves the others. Who
notices: an application whose callback ended the process. Previous
behaviour: the process ended; an application that wants that ends it
itself in the callback.
Added
iec102/server:Config.PaceAnswers. The answers the server builds
itself (C_RD_NA_2, C_TI_NA_2, the reads of integrated totals and single
points, refusals included) are queued as the controlling station's
class 2 polls take the queue, so an answer longer thanQueueSize
goes out whole, its termination included. Meanwhile the server serves
no other request: up to 16 wait, and more are refused with NACK and
DFC. A reset of remote link drops the rest of the answer;Closeends
the wait.Send,Mirrorand theHandlerare not paced. Off by
default: an answer is cut where the queue is full, as before.iec103/server:Config.PaceChannels. The ASDUs 30 and the ASDU 31
of a disturbance channel are queued as the controlling system's class
1 polls take the queue, so a channel longer thanQueueSizegoes out
whole, and a record whose longest channel does not fit the queue is
announced at its selection. Meanwhile other requests wait in the
server's input, with DFC set while it is more than half full. A reset
of the communication unit or of the FCB drops the rest of the channel,
logged at Info asdisturbance channel ended by a reset;Closeends
the wait. Tags are not paced. Off by default: a channel is queued all
or none (TOO 37 when it does not fit now, TOO 34 at the selection when
it can never fit), as before.
Fixed
iec104/client:Connectreturnsiec104.ErrClosedwhen aDialer
that does not return normally races withClose; it no longer
continues without a connection.
Documentation
- The OnState docs of the iec101 server (unbalanced mode), the iec102
server and the iec103 server say that OnState forStateUpruns on
the link's reader under the lock of the secondary station, before the
reset is acknowledged, so a slow OnState delays the link's answers. iec103.Uintsandiec103.Intssay that each value keeps its low
sizeoctets and that nothing reports a value that needs more.WithTLSandWithSecurityofiec104/clientandiec104/server,
andsec.Config.OnEvent, say on which goroutine the callbacks run and
what happens to one that does not return normally; the client's
WithTLSsays that a renegotiation, whichtls.Config.Renegotiation
allows, runs them later on the connection's reader.
docs/iec102/README.md, docs/iec103/README.md,
docs/iec103/INTEROPERABILITY.md (interpretation 15), docs/iec104/API.md,
ERRORS.md, OBSERVABILITY.md, SECURITY.md and TESTING.md follow the
changes above; docs/api is regenerated.
Tests
- Pacing, on the fake clock of
testing/synctestwhere unit:
iec102/serverTestAnswerLongerThanTheQueue(the default),
TestPacedAnswer,TestPacedAnswerEnds(reset and Close);
iec102/e2e.TestPacedAnswers;iec103/serverTestPacedChannel,
TestPacedChannelEnds(reset of the communication unit, of the FCB,
Close);iec103/e2e.TestPacedChannels(on and off). iec103.TestMEAcovers 0, the largest value below full scale, full
scale, beyond it in both directions, the infinities and NaN;
TestGenericValuespins the octetsUintsandIntskeep.iec104/client.TestConnectWhenTheDialerStopsDuringClose: the Dialer
stops onceClosehas closed the client, every time.iec104/client.TestTLSCallbackThatDoesNotReturnNormally,
iec104/server.TestTLSCallbackRejectsOnlyThatConnection,
iec104/e2e.TestSecurityEventHandlerOfTheClientand
TestSecurityEventHandlerOfTheStation.- The IEC 104 test station (
iec104/internal/station) listens on
127.0.0.1:0, the address the e2e suites dial, and on the wildcard
only for the interop suites, which a container dials
(iec104/e2e.TestStationListensOnLoopback). Another process that
listens on the loopback address with the same port no longer takes the
suites' connections.
go-iec60870-5 v0.8.0
Date: 2026-11-16
Previous release: v0.7.0
State notifications of the serial stations that come one at a time and
in order, an iec102 client whose OnState may make requests, IEC 104
client callbacks and loggers that no longer end the process when they do
not return normally, a takeover in a redundancy group that ends the
previous session's started state at once, and the remaining tests that
waited a fixed time rewritten to wait for what they check. Four changes
of behaviour are breaking; each says who notices and how to get the
previous behaviour back where there is a way. No identifier is added,
removed or changed.
Breaking
iec102/client:Config.OnStateruns on a goroutine of the client's
own, outside the request slot, one call at a time and in the order of
the changes,StateClosedlast. A request made from OnState is
answered after the request in progress, instead of waiting for the
slot until its deadline. The request that changed the state goes on
while OnState runs and returns once OnState has returned for that
change, as before. Close called from OnState returns at once; the
close completes,StateClosedreported included, when OnState has
returned, soDonemay close before OnState is toldStateClosed.
Who notices: an OnState that relies on running on the goroutine of the
request that changed the state. Previous behaviour: none; the request
still returns only after OnState for its change.iec101/server,iec102/server,iec103/server: OnState is called
one change at a time and in order,StateClosedlast: Close waits for
an OnState call in progress before it reportsStateClosed. Before,
on a transport that is not anio.Closer,StateClosedcould be
reported while OnState for the link coming up still ran on the link's
reader. Who notices: an OnState that waits for something the closing
goroutine does after Close returns. Previous behaviour: none; such an
OnState returns and waits on another goroutine.iec104/client: aDialer(WithDialer) or a metrics callback
(WithMetrics,iec104.RequestMetricsincluded) that does not return
normally is logged at Error ascallback did not return normallywith
its stack and closes the client, from whichever goroutine called it:
the state handler is told "disconnected" with an error that wraps
iec104.ErrClosedand names the callback, andConnect, the
reconnect loop or the request that called it fails with
iec104.ErrClosed. Previous behaviour: the process ended. An
application that wants that ends it itself in the callback.- Every package: a call of the application's logger (
Logger,
FieldLogger,ContextLogger,DebugEnabled) that does not return
normally loses its entry; the failure is written once more through
Errorfaslogger did not return normallywith the method, the
value and the stack, and dropped whenErrorfdoes not return
normally either. The client, server or session that logged goes on. A
FieldLoggerwhoseWithdoes not return normally is used through
its formatted methods; aDebugEnabledthat does not return normally
counts as false. Previous behaviour: the process ended. An application
that wants that ends it itself in its logger.
Fixed
iec104/server:Session.Startedreports false for a session that a
takeover in a declared redundancy group ends, from before the STARTDT
con of the new connection; it reported true until the session's
protocol goroutine had seen its connection closed, soSessionscould
show two started sessions of one group.iec104/client: the "disconnected" notice names a callback that
closed the client during a reconnect attempt, or while the loss of the
connection was being reported (the metrics'OnDisconnect), as it
does after a local close.iec104/client:Connecton a client that is closed while it
connects, byCloseor by a callback that does not return normally,
fails withiec104.ErrClosed, wrapped in the failure that names the
callback where there is one; it returned nil when the link confirmed
STARTDT, or the secure session came up, before the close reached it.
The state handler is then told "disconnected" once, and no "started"
or "stopped" that the link confirms after the close.
Documentation
- The OnState docs of the iec101, iec102 and iec103 clients and servers
say that the calls come one at a time and in order; the iec102 client
no longer says that OnState must not make a request.WithDialer,
WithMetricsandWithLoggerofiec104/clientandiec104/server,
andiec60870.Logger, say what happens to a callback or a logger call
that does not return normally. ARCHITECTURE.md, ERRORS.md,
OBSERVABILITY.md, TESTING.md, docs/iec102/README.md and
docs/iec104/API.md follow the changes above; docs/api is regenerated.
Tests
- State order:
TestStateNotificationsInOrderiniec102/client,
iec102/server,iec103/clientandiec103/server;
iec101/e2e.TestServerStateNotificationsInOrderand
TestClientStateNotificationsInOrder(both modes), on the fake clock
oftesting/synctest;iec102/client.TestRequestFromOnState. - Callbacks and loggers:
iec104/client
TestHookThatDoesNotReturnNormally,TestMetricsThatDoNotReturnNormally,
TestLoggerThatDoesNotReturnNormally;
internal/logx.TestLoggerThatDoesNotReturnNormally;
iec101/e2e.TestLoggerThatDoesNotReturnNormally. iec104/server.TestTakeoverStopsThePreviousSessionAtOnce.iec104/client.TestConnectClosedWhileSTARTDTIsConfirmed: the client
is closed while the link confirms STARTDT, held there by a failpoint.iec104/server.TestTakeoverEndsThePreviousConnection,
iec104/e2e.TestStopDuringEventStreamand
iec104/e2e.TestSecurityStationswait for the events they check:
the event stream test counts the events on the wire before each STOPDT
con and waits until the Handler has been given exactly those, and the
station test waits for the standby connection before the switchover
and checks the associations of the started sessions only.
iec104/client.TestGroupFailsOverBehindABusyHandlerwaits for both
connections to be established, not connecting, before it switches
over. Fixed waits
in the iec101, iec102, iec103 and iec104 tests that synchronised on
time now wait for what they check; the waits left are pacing, a
duration under test, or need a hook the library does not have.
go-iec60870-5 v0.7.0
Date: 2026-11-14
Previous release: v0.6.0
Bounds on what a peer can make the IEC 104 client, the IEC 104 security
and the serial stations hold, IEC 104 server callbacks that close only
their own session when they do not return normally, session keys that
the controlled station stops accepting at their limits, and disturbance
transfers that keep to one fault. Five changes of behaviour are
breaking; each says how to get the previous behaviour back where there
is a way. The only new identifiers are client.WithMaxResult and
client.DefaultMaxResult of iec104/client; none is removed or
changed.
Breaking
iec104/client:WithMaxResultbounds what one collecting request
returns: the ASDUs ofInterrogateand ofCounterInterrogatewith
asdu.FreezeRead, the directory entries ofListFiles. The answer
that would exceed it ends the request with the results so far and an
error wrappingtelecontrol.ErrResultLimit, instead of growing it
until its deadline; such a request is not retried. The default is
DefaultMaxResult, 65536, as for the IEC 101 client. Why: a station
that keeps answering held the request's memory until its deadline.
Previous behaviour:WithMaxResult(-1).iec104/server: a state handler (WithStateHandler), aMetricsor
HandlerMetricshook, an accept filter (WithAccept) or a security
endpoint factory (WithSecurity) that does not return normally is
logged at Error ascallback did not return normallywith its stack
and closes only its session (the accept filter: rejects only that
connection, logged asconnection rejectedwith the reasonaccept filter did not return normally); the server goes on serving the
others. After aHandlerpanic the session ends at once: ASDUs
already received on it are no longer delivered to theHandler.
Previous behaviour: the process ended (the Handler: the session closed
in the background and later ASDUs were still delivered). An
application that wants the process to end ends it itself in the
callback.sec:Trustchecks the key usage of the remote certificate and the
validity period of the authority certificates. A remote certificate
with a key usage extension that allows neither keyAgreement nor
digitalSignature is refused, and an authority certificate outside its
validity period authorizes nothing. Why: the key of the certificate
serves the key agreement of the Station Association, and an expired
authority issues nothing valid. Previous behaviour: for the authority
validity,Config.IgnoreValidity(which also skips the validity
check of the station certificate); for the key usage there is none:
issue the certificate with keyAgreement or digitalSignature, or
without the extension.sec: a Station Association completed at the controlled station ends
its session: the session keys of the earlier association are no longer
accepted,Readyreports false, and the Session Key Change that
follows sets up new ones (IEC TS 60870-5-7:2025 Table 15). Why: new
update keys replace the association the session keys were sent under.
There is no way back; a controlling station that follows the TS, this
module's included, changes the session keys right after the
association.iec103/server: the ASDUs 30 of a disturbance channel and the ASDU 31
that ends it are queued all or none. When the class 1 queue has no
room for all of them the channel ends with TOO 37 (aborted by the
protection equipment), which the controlling station acknowledges
negatively and may request again. The selection of a record whose
longest channel cannot fit the class 1 queue at all is answered with
TOO 34 and no transfer starts. Why: a channel cut at the queue bound
went out with values missing.
Previous behaviour, for long records: raiseConfig.QueueSize.
Added
iec104/client:WithMaxResultandDefaultMaxResult(above).
Changed
iec104/client: a request that waits for one answer (Command,
Read,ClockSync, ...) queues at most 16 mirrors of earlier requests
ahead of its answer, and otherwise ends with an error wrapping
telecontrol.ErrResultLimit.iec104/client:GetFileends withiec104.ErrProtocolwhen the
station announces more than 255 sections, the most a file can have (one
per name of section, IEC 60870-5-101 7.2.6.33).telecontrol:Requester.Collectqueues at mostMaxResultplus a
small margin while its request is still being sent.iec104: with IEC 62351-5, security output waiting for the peer's
acknowledgements is bounded: above 128 KiB received I frames are no
longer acknowledged, so a conformant peer stops afterkmore; a peer
that keeps sending past its window is closed withErrProtocolabove
1 MiB.iec104: ignored or unsolicited STARTDT/STOPDT frames are logged at
Debug instead of Warn.sec: a controlled station stops accepting session keys as soon as
they reachSettings.KeyUsesor their lifetime, not only at its next
Tick: it discards the message that finds them so, counts the
invalidation and asks for new keys at once.Readyand
Status().Readyreport false from then.sec: the remote certificate of an association (Status().Remote) is
taken only once the Station Association has authenticated it.sec: a connection not yet bound to an association answers one
Station Association request per request timeout; a repeated request
gets the same answer, with the same random data.iec103/server: NOE announces the longest channel of a record, so
that no channel carries values beyond it.link: a broadcast reachesSecondaryHandler.UserDataonly as
send/no reply in a variable-length frame, and only when the handler's
FunctionFilterserves function 4, as an addressed message.ci: the Extended workflow validates itsfuzztimeandchaos_seeds
inputs and passes them to the shell through the environment.
Fixed
iec104/client: a callback that stops the client while it is still
connecting is named in the "disconnected" notice, as after the connect.link: an exchange (Primary,Balanced) ends with its context also
while its frame waits for room in a full send queue, which a peer that
stops reading leaves full.link: Close on a transport that is not anio.Closerno longer waits
for a writer blocked inWrite; the writer ends when thatWrite
returns and writes nothing more.iec103/client:Disturbancekeeps to the selected fault (FAN,
IEC 60870-5-103 7.4.7): it skips an end of transmission of another
FAN, ends withiec103.ErrInvalid(and the record so far) on a channel
offered for another FAN, and acknowledges negatively a channel whose
disturbance values carry another FAN. Disturbance values that add
nothing to the record (no values, or another FAN) count against
Config.MaxResultper channel.iec102/client:ReadTotalsandReadSinglePointskeep only the data
of the requested record address.iec104/server:FileServerupload sections no longer hold more
capacity than their announced length.internal/pcapio: capture lengths are checked before they are
converted toint, which is 32 bits wide on some platforms.
Documentation
iec102/ree:Sessiondocuments that its state follows the last
access key received, so a C_AC_NA_2 with a wrong key closes an open
session.- SECURITY.md, LIMITATIONS.md, ERRORS.md (new section Result bounds),
ARCHITECTURE.md, OBSERVABILITY.md, TESTING.md, docs/REQUIREMENTS.md
(LK-9, LK-16), docs/iec102, docs/iec103 (interpretations 14 and 15),
docs/iec104/API.md, docs/iec104/ARCHITECTURE.md,
docs/iec104/INTEROPERABILITY.md and docs/iec104/LIMITATIONS.md follow
the changes above; docs/api is regenerated.
Tests
- Result and queue bounds:
iec104/clientTestInterrogateResultLimit,
TestListFilesResultLimit,TestGetFileSectionLimit,
TestExchangeQueueBound;telecontrol.TestCollectQueueBound. - Security output:
iec104/internal/link
TestSecurityOutputSlowAcknowledgementStaysBounded,
TestSecurityOutputPeerPastWindowIsClosed. iec104/servercallbacks:TestStateHandlerPanicClosesOnlyItsSession,
TestMetricsPanicClosesOnlyItsSession,
TestAcceptFilterPanicRejectsOnlyThatConnection,
TestEndpointFactoryPanicEndsTheSession,
TestHandlerPanicStopsDelivery.sec:TestControlledKeyUsesEnforced,
TestControlledKeyLifetimeAtUse,TestAssociationEndsSession,
TestRemoteAfterAuthentication,TestCandidateAssociationRequests,
TestCandidateKeyUses,TestCandidateAssociationEndsSession,
TestTrustKeyUsage,TestTrustAuthorityValidity.link:TestExchangeEndsWithContextOnFullQueue,
TestCloseWithoutCloserBlockedWrite,TestCloseWithoutCloserIdleWriter,
TestSecondaryBroadcastKindAndFilter.- IEC 103 disturbance data:
iec103/e2eTestDisturbanceOtherFAN,
TestDisturbanceEmptyValues;iec103/server
TestDisturbanceChannelQueuedWhole,TestDisturbanceSelectNOE. iec102/client.TestReadOtherRecord,
internal/pcapio.TestPacketsLengthsBeyondInt32; theiec104/e2e
station that announces sections without end now expects
iec104.ErrProtocolafter 255 sections.
go-iec60870-5 v0.6.0
Date: 2026-11-14
Previous release: v0.5.3
Bounds on what a peer can make a station hold, callbacks that stop only
their own station when they do not return normally, Close from inside a
callback in every serial station, and Done/Err where they were
missing. Three changes of behaviour are breaking; each says how to get
the previous behaviour back. No exported identifier is removed or
changed.
Breaking
-
iec104/server: aFileServersession has at most
FileServer.MaxTransferstransfers open at once, files fetched and
files delivered together; the default isDefaultMaxTransfers(16). A
selection (F_SC_NA_1) or a file ready (F_FR_NA_1) beyond it is refused
like a file the station does not have, with "unknown information object
address", and logged at Warn, until a transfer of that session ends.
Why: an open delivery keeps what arrived of up toasdu.MaxFileLength
octets, and IEC 60870-5-101 7.4.11 has the files of a station
transferred one after the other, so a controlling station has one or
two open. Previous behaviour: setMaxTransfersto a negative value. -
iec101/client,iec102/client,iec103/client:Config.MaxResult
bounds the ASDUs one request collects; the request that would collect
more ends with the ASDUs so far and an error wrapping
telecontrol.ErrResultLimit(IEC 101:Interrogate,
CounterInterrogate),iec102.ErrResultLimit(every request) or
iec103.ErrResultLimit(Interrogate, the generic services, the tags
of a disturbance transfer), instead of growing until its deadline. The
defaults areDefaultMaxResult: 65536 (IEC 101, IEC 103) and 131072
(IEC 102, more than three years of quarter-hour periods). The bound
comes fromtelecontrol.Requester.MaxResultin IEC 101, whose zero
value still means no bound. Previous behaviour: setMaxResultto a
negative value. -
A callback that does not return normally is recovered where the
library calls it, logged at Error ascallback did not return normally
with its stack (fieldscallback,value,stack), and stops only the
station that called it; the process goes on. The call sites:link: theSecondaryHandlerandBalancedHandlermethods,
Config.OnFrame(frames sent and received) andConfig.OnDiscard.
The station stops;Donecloses andErrwrapslink.ErrClosed
and names the callback. The newlink.Config.Loggerreceives the
entry; the clients and servers pass theirs when it is nil.iec101/clientandiec101/server:Config.Handler,
Config.OnState.iec102/client:Config.Handler,Config.OnState;
iec102/server:Config.Handler,Config.Clock,Config.OnState.iec103/client:Config.Handler,Config.OnState;
iec103/server:Config.Handler,Config.OnTimeSync, the methods of
Config.Disturbances(DisturbanceSource),Config.OnState.- In those serial stations
Donecloses,Errwraps the standard's
ErrClosedand names the callback, and requests in progress fail
withErrClosed. iec104/client: theHandler(WithHandler), the state handler
(WithStateHandler) and the start handler (WithStartHandler) close
their client, which does not reconnect: the state handler is told
"disconnected" with an error that wrapsiec104.ErrClosedand names
the callback. The switch handler (WithSwitchHandler) closes its
group.
Previous behaviour: the process ended. An application that wants that
ends it itself whenErrnames a callback (serial), or when the state
handler reports such an error (IEC 104).
Added
iec101.ErrInHandler,iec103.ErrInHandler: a request called where its
answer cannot arrive (below).telecontrol.ErrResultLimit,telecontrol.Requester.MaxResult,
iec102.ErrResultLimit,iec103.ErrResultLimit,Config.MaxResult
andDefaultMaxResultof the three serial clients,
server.FileServer.MaxTransfersandserver.DefaultMaxTransfersof
iec104/server,link.Config.Logger.iec103.ErrOverflow: a request that missed answers, which arrived
faster than it took them beyond the 1024 ASDUs it buffers. It is the
error such a request returned before, now exported, with the same text.DoneandErroniec102/client.Clientandiec103/server.Server,
Erroniec102/server.Server: when and why the station stopped (the
transport, or a callback that did not return normally);Erris nil
while it runs and after Close.
Changed
iec101/client: a request that waits for an answer (Interrogate,
CounterInterrogate,Read,Command,Deactivate,ClockSync,
TestCommand,ResetProcess,MeasureDelay), called from
Config.HandlerorConfig.OnStateon one of the client's goroutines,
returnsiec101.ErrInHandlerat once and is not sent; fromOnState
on a client goroutine so doSendandSetDelay. Before, such a
request waited behind the Handler's queue and failed at its deadline
once the station sent more than 256 ASDUs (LIMITATIONS.md; the
Handler documentation of v0.5.3 says it must not wait for the
station). Issue it from another goroutine.iec103/client: the requests,Send,Broadcastand
BroadcastClockSync, called fromConfig.HandlerorConfig.OnState
on one of the client's goroutines, returniec103.ErrInHandlerat once
and are not sent, where they waited for the link loop that waits for
the Handler. Issue them from another goroutine.iec104/server:Server.Closewaits for the goroutine of each event
queue to end, and an event queued after Close starts none.
Fixed
- Serial stations (
link.Primary,link.Secondary,link.Balanced, the
clients and servers ofiec101,iec102andiec103): Close called
from one of the station's own callbacks (a handler, OnState, the iec102
server'sClock, the iec103 server'sOnTimeSyncand
DisturbanceSource,link.Config.OnFrameandOnDiscard) stops the
station and returns at once, instead of waiting for the goroutine it
runs on. The callback is not called again, the close completes when it
has returned, andErrstays nil. Theiec102/clientreports
StateClosedafter its Close has completed, so OnState may call Close
then too. link: on a transport that is not anio.Closer, Close no longer
waits for the reader's pending Read; the reader ends when that Read
returns. A frame read after Close or after a callback stopped the
station reaches no handler.iec101/client: a request in flight at Close and every request after
it returniec101.ErrClosed, in both modes, as Close documents; a
request after Close returnediec101.ErrLinkDownbefore.iec102:SinglePointswith aQualifierabove 127, which SPQ cannot
hold, does not encode (ErrInvalid) where bit 7 was dropped.iec103:Measurandswith anMEA.Rawoutside -4096..4095 does not
encode (ErrInvalid) where the 13-bit MVAL kept the low bits.iec103/server: a disturbance record is ended with TOO 34 when any of
its channels has more values than NOE holds, not only the first, so the
NFE of every ASDU 31 fits its two octets.
Deferred
- Pacing a server answer longer than the send queue, or ending it with a
negative termination (iec103/serverdisturbance data,
iec102/server): it changes what a valid controlling station receives. iec103.MEAOf(NaN)and the truncation ofUints/Intsin generic
data: their documentation does not call those values invalid, so a
change is a change of behaviour for valid input.iec102/client: a request from OnState still waits for the request
slot that the request calling OnState holds; OnState documents that it
must not issue one.- Callbacks of
iec104/serverother than the handlers it already
recovers (the state handler,WithAccept, the logger, metrics) and the
Dialer, logger and metrics ofiec104/client.
Documentation
- Every handler, OnState and hook of the serial stations says it may call
Close, what happens when it does not return normally, and which
requests returnErrInHandler. LIMITATIONS.md, ERRORS.md, SECURITY.md,
ARCHITECTURE.md, OBSERVABILITY.md, API.md, docs/iec102,
docs/iec103, docs/iec104/API.md and docs/iec104/ARCHITECTURE.md follow
the changes above; TESTING.md lists the new tests against the contract
rows L3, L9, L10 and L12.
Tests
- Callbacks that do not return normally, per call site:
TestCallbackThatDoesNotReturnNormallyinlink,iec101/e2e(both
modes),iec102/client,iec102/server,iec103/client,
iec103/serverandiec104/client;
iec104/client.TestSwitchHandlerThatDoesNotReturnNormally;
internal/callback. - Close from a callback:
TestL10CallbackClosesSynchronouslyinlink
andiec101/e2e,TestCloseFromCallbacksSynchronouslyin
iec102/server,iec103/clientandiec103/server,
iec102/client.TestCloseFromHandlerSynchronously,
iec102/client.TestCloseFromOnState;link.TestCloseWithoutCloser. - Requests from a callback and after Close:
TestRequestFromHandlerFailsAtOnceandTestRequestsFailWithErrClosed
iniec101/e2eandiec103/client;TestServerWithoutHandlerRejects
now expectsiec101.ErrClosedafter Close. - Bounds, on the fake clock of
testing/synctestwith an allocation
budget:telecontrol.TestCollectResultLimit,
iec101/e2e.TestInterrogationResultLimit,
iec102/client.TestRequestResultLimit,
iec103/client.TestInterrogationResultLimit;
iec103/client.TestWaitOverflow;
iec104/server.TestFileServerMaxTransfers.iec104/e2e
TestHostileSectionAnnouncementBudgetannounces
DefaultMaxTransfers / 2files per round, so both rounds fit the
bound. Done/Err:TestDoneAndErriniec102/clientandiec103/server,
iec102/server.TestErr.iec104/server:TestCloseWaitsForEventQueues,
TestNoEventQueueAfterClose.- Value bounds:...
go-iec60870-5 v0.5.3
Date: 2026-11-14
Previous release: v0.5.2
Bounds and lifecycle fixes in every companion standard, from the policy 1.6
review: limits on what a peer can make a station hold or wait for, Close
that is safe to call more than once in the serial stations, balanced IEC 101
sends on the client's own goroutine, and the callback, ownership and Close
contracts documented on every station. No exported identifier is added,
removed or changed.
Fixed
sec: the segments of one security message are reassembled up to the
longest message the A-Profile defines, the Association Response with a
certificate of 65535 octets (IEC TS 60870-5-7:2025, Figure 8; 65797
octets after the data unit identifier). A series that would grow beyond
it is abandoned and counted inStatDiscardedMessages.iec104/serverwithWithSecurity: a connection is bound to the
association of its controlling station only once a message on it is
authenticated for it (a Station Association or Session Key Change that
completes, or Secure Data under the current session keys). Until then
its key management runs on a copy of the association and changes
nothing of it: the connection that carries the association keeps it,
andSession.Securityof the other is nil. An association that no
message has authenticated is kept only while a connection waits for it;
newEndpointis called again for that AIM when its station is heard
next.iec104/server:Servekeeps serving through accept errors other than
a closed listener (out of file descriptors, a connection aborted before
accept, a timeout); each is logged and retried after a pause that
doubles from 5 ms up to 1 s and ends when the server is closed. With
WithMaxSessions, a TLS handshake in progress counts as a session, and
a connection beyond the limit is closed before its handshake starts.
Without a limit nothing changes.iec104/server:FileServerreserves no memory for a file section a
controlling station announces; an upload grows only with the segments
that arrive.iec104/client: aDialerthat returns neither a connection nor an
error fails the connect withiec104.ErrConnectFailed.Closewaits
for the start handlers (WithStartHandler) to return, after cancelling
their contexts; called from a start handler, it waits for everything
else and returns.ft12: after a pause longer thanDecoder.Gapthe rest of a rejected
frame is no longer awaited, as an unfinished frame already was not:
the octets after the pause start a new frame (IEC 60870-5-1 6.2.4.2, as
Gapdocuments).Decoder.Resetalso forgets the rest of a rejected
frame still to come and the single-character hold-off.iec101/client, balanced transmission: the supervisor goroutine sends
the user data of requests, under the client's own context, as the
poller does in unbalanced transmission. A request returns at its
deadline even while the link repeats another frame, and an exchange
whose request ended is still finished on the link, so the station
receives the message once and the FCB stays in step. OnState for a
failed send is called from the supervisor. The first test function for
link follows oneTestIntervalafter the link came up.iec103/client:Disturbancekeeps at most the NOC channels of NOE
values its ASDU 26 announced (clauses 7.2.6.10, 7.2.6.11). A value or a
channel beyond them ends the transfer at once with an error wrapping
iec103.ErrInvalid, returns the record so far and sends no further
order.iec103/server:AnswerGIandAckCommandreturn an error wrapping
iec103.ErrInvalid, and send nothing, for a request whose body is not
a general interrogation or general command (an ASDU 7 or 20 with a
private cause decodes asiec103.Raw). The quickstart example checks
the body the same way.iec103/server: a time synchronization whose time is flagged invalid,
or lies outside the years 1970 to 2069 of CP56Time2a, is not applied:
the clock andOnTimeSyncstay as they were, and an addressed one is
answered with ASDU 6 carrying the station's time with IV set (clause
7.4.2 defines no negative answer; interpretation 13 of
docs/iec103/INTEROPERABILITY.md). The clock offset is held within
±36525 days.iec101/serverandiec102/serverapply no clock
synchronization themselves (the handler, orree.Session.OnSetTime,
does).iec102/client: an answer belongs to a request only when it also
repeats the request's information object, its addresses and time range
(iec102.ASDU.Mirrorsis unchanged). A request after one that ended
before its answer was complete first polls the station until it has no
more data and drops the rest of that answer; ASDUs of other common
addresses still go to the Handler.- Serial stations (
link.Primary,link.Secondary,link.Balanced, the
clients and servers ofiec101,iec102andiec103): Close is safe
to call more than once and from several goroutines. The first call
closes the transport, once, also when the writer closed it after a
write error, and returns its error; later calls return nil.
Changed
iec104/client: each reconnect, request retry andGroupredial wait
is chosen at random between half the delay and the delay (equal
jitter); the loggedretry_inis that wait.
Documentation
- Every handler and OnState of the serial stations says which goroutine
calls it, what it may call, and that it must not call Close (Close
waits for that goroutine; call it in a new goroutine, which returns
once the handler has returned). The iec101 and iec103 client Handlers
no longer say they may issue requests: a request from them stalls
behind their queue (LIMITATIONS.md). - Ownership: the slices that cross the
linkAPI (SendNoReply,
SendConfirm,Balanced.Send, whatClass1,Class2andUserData
hand over, theOnDiscardbuffer), the ASDUs the iec102 and iec103
handlers receive, and the*asdu.ASDUthat the iec104 client shares
between its Handler and the request that collects it (read-only). - Close needs a transport whose Close unblocks Read (
link,iec101).
iec104/server.Server.Closedoes not wait for the goroutines of the
event queues. - No transaction identifier: a late confirmation of a request that ended
completes the next identical request (LIMITATIONS.md,
docs/iec104/LIMITATIONS.md, thetelecontrolpackage doc). - TESTING.md lists the long-lived types against the contract test matrix
(L1 to L16). SECURITY.md, ERRORS.md, ARCHITECTURE.md, OBSERVABILITY.md,
docs/iec104/API.md, docs/iec102 and docs/iec103 follow the changes
above.
Tests
sec:TestReassemblyLengthLimit(the bound, one octet below, at and
above it),TestReassemblyAllocationBudget(20,000 segments without
FIN within 8 times the bound);FuzzDecodechecks the bound on every
input.iec104/server:TestUnauthenticatedMessageLeavesTheAssociation,
TestAuthenticatedSessionTakesTheAssociationOver,
TestPendingAssociationIsShared,
TestUnauthenticatedAssociationsAreNotKept,
TestServeRetriesAcceptErrors,TestServeEndsWhenTheListenerIsClosed,
TestTLSHandshakesCountAgainstTheSessionLimit;iec104/e2e:
TestHostileSectionAnnouncementBudget.iec104/client:TestReconnectPausesAreJittered,
TestRetryPausesAreJittered,TestGroupRedialPausesAreJittered,
TestDialerWithoutConnection,TestCloseWaitsForTheStartHandler,
TestCloseFromTheStartHandler.ft12: the rejected-header case ofTestDecoderGap,
TestDecoderResetForgetsARejectedFrame,
TestDecoderGapKeepsAFrameWithoutPause;iec101/e2e: the
rejected-header case of the half-open line inTestHostileServer.iec101/e2e:TestBalancedRequestDeadlineWhileTheLinkRepeats,
TestBalancedSendAfterItsDeadline.iec103:TestDisturbanceWithinAnnounced(e2e),
TestAnswersNeedTheirRequestBody,TestTimeSyncValidity,
TestTimeSyncRefusedKeepsTheClock,TestTimeSyncOffsetClamped
(server).iec102:TestUnfinishedAnswerNotTaken(e2e),
TestMirrorOfAnotherRange(client).- Contract rows L1, L2 and L10 for the serial stations:
link.TestL01CloseTwice,link.TestL01CloseAfterAWriteError,
link.TestL02ConcurrentClose,link.TestL10CallbackClosesAsynchronously,
the same three iniec101/e2e, andTestCloseTwice,
TestConcurrentClose,TestCloseFromHandlerin the iec102 and iec103
clients and servers. internal/testutil/leakcheckcompares goroutine stacks instead of counting
goroutines;leakcheck.Mainruns after the tests oflink,telecontrol,
the iec101, iec102, iec103 and iec104 clients and servers and
iec104/internal/link, and the e2e suites useleakcheck.Check. The
iec104/internal/capturereplay peer queues frames without a bound,
so its reader ends with the connection.- Waits that slept are now events, hooks or
testing/synctestin
link/close_test.go,iec101/client/waitup_test.go,
iec101/e2e/hostile_test.go,iec101/e2e/deadline_test.go,
ft12/gap_test.go,iec102/client/client_test.go,
iec103/e2e/silent_test.go,iec104/server/ordering_test.go,
iec104/server/reconnect_test.go,iec104/internal/link/link_test.go
andiec104/internal/link/invariants_test.go.
go-iec60870-5 v0.5.2
Date: 2026-11-12
Previous release: v0.5.1
The interop suites of all four standards move to the reference images of
otfabric/iec60870-5-interop v0.5.0 (was v0.4.0). No change to the library's
code or API.
Changed
- Interop pin: iec60870-5-interop v0.5.0 (contract 2.3, unchanged; the same
upstream revisions as v0.4.0, rebuilt), its 13 reference images pinned by
multi-arch index digest iniec101/interop/harness.go,
iec102/interop/harness.go,iec103/interop/harness.go,
iec104/interop/harness.go, the Makefile and the Interop workflow. The
copied harness tables (testdata/cases.tsv,known-bugs.tsv,
known-bugs-consumer.tsv) are refreshed from v0.5.0. iec103/interop:known-bugs-consumer.tsventries may name a role
(vitusdong@client,vitusdong@server,open103@client), as the harness
writes them since v0.5.0. The suite strips the role after checking that it
agrees with its own table of client bugs; a disagreement fails the run.- Docs (README, TESTING, LIMITATIONS, INTEROPERABILITY, docs/FEATURE-STATUS,
docs/iec102, docs/iec103, docs/iec104) name the v0.5.0 images.
Verified
Locally on linux/arm64 (Docker on macOS), 2026-11-12, on the pinned v0.5.0
images: IEC 101 3 top-level tests, 490 subtests passed, 5 skipped (the
digitalpetri balanced known bug), 0 failed; IEC 102 2 top-level tests, 19
subtests passed, 0 failed; IEC 103 4 top-level tests, 75 subtests passed, 38
skipped (known bugs and undeclared features), 0 failed; IEC 104 31 top-level
tests, 519 subtests passed, 35 skipped (undeclared features and the j60870
known bug), 0 failed.
The same counts as on the v0.4.0 images.
go-iec60870-5 v0.5.1
Date: 2026-11-12
Previous release: v0.5.0
Fixes a silent loss of data on a noisy line in every serial standard (IEC
101, 102, 103): the FT 1.2 decoder could take an E5 octet inside the user
data of a corrupted frame for a single-character answer.
Fixed
ft12: after rejecting a frame,Decoderresynchronized on the next
start character inside the rejected octets. A single character (E5) has
no checksum, so an E5 in the user data of a corrupted variable frame was
returned as a frame: the controlling station took it for "no data"
(or a positive acknowledgement), toggled FCB on its next request, and the
message the corrupted frame carried was lost while the procedure ended
successfully (otfabric/iec60870ctl's chaos test: 7 of 8 general
interrogation messages). Since v0.1.0. Now a rejected variable frame
whose two length octets agree is dropped whole (4 + L + 2 octets, also
when the rest arrives in later reads), and after any other error a
single character is accepted only from octets that arrive after a pause
ofErrorIdle(10 ms), the line idle IEC 60870-5-1 asks for after an
error. A real answer follows a request sent after the error, so it is
not affected; a frame dropped in error is repeated by the link layer.
Added
ft12.ErrorIdle.
Tests
ft12:TestDecoderNoSingleFromRejectedFrame(five corruptions, one read
and one octet per read),TestDecoderDropsTheRestOfARejectedFrame,
TestDecoderSingleAfterIdle;TestDecoderResyncnow expects the E5 read
with a rejected header to be dropped.
go-iec60870-5 v0.5.0
Date: 2026-11-12
Previous release: v0.4.1
Two lifecycle fixes, found by otfabric/iec60870ctl's tests: a link station
no longer outlives its Close, and the IEC 101 and IEC 103 clients no longer
wait in vain for a link whose transport has failed.
Added
iec103/client:Client.DoneandClient.Err, asiec101/clienthas
them: Done is closed when the transport failed or the client was closed,
Err returns the transport error.
Fixed
link:Closeof aPrimary,SecondaryorBalancedwaits for the
writer goroutine as well as the reader.Config.OnFrameis no longer
called, and no frame is written, afterClosereturned; a frame queued
before the station stopped is not sent after it.iec101/client,iec103/client:WaitUpreturns the transport error
when the transport fails before the link came up (a peer that closed the
connection, say), instead of waiting until its context ended; it returns
ErrClosedafterClose. The client stops initializing the link on a
failed transport instead of retrying everyRetryInterval.
(iec102/client.Initalready returned the error.)
Tests
link:TestCloseWaitsForTheWriter;iec101/client,iec103/client:
TestWaitUpTransportClosedBeforeLinkUp,TestWaitUpCloseWhileWaiting.
Each fails on v0.4.1.
go-iec60870-5 v0.4.1
Date: 2026-11-12
Previous release: v0.4.0
iec103/client keeps every identification a station sends after a reset,
so the one with cause 4 is not lost behind a start/restart (cause 5).
Added
iec103/client:Client.IdentificationFor(cause)returns the last
identification (ASDU 5) with that cause (IEC 60870-5-103:1997 7.4.1,
table 8).Identificationstill returns the last one of any cause.
Fixed
iec103/interop: the identification case reads the cause 4
identification withIdentificationFor. A station that follows clause
7.4.1 and sends start/restart (cause 5) after it, as the fixed
vitusdong/iec103-dotnet (vitusdong/iec103-dotnet#10) does, failed the
case.
go-iec60870-5 v0.4.0
Date: 2026-11-12
Previous release: v0.3.0
More independent evidence for the serial standards: IEC 101 against a third
reference, digitalpetri/iec60870, and with four non-default sets of field
sizes; IEC 103 generic services and disturbance data against the harness's
contract 2.3, with the server's disturbance data transfer evidenced by
Open103. iec104/client returns from a counter freeze or reset at the
confirmation and shares the matching rules of telecontrol. SAST stays at
zero. All interop suites pin the images of iec60870-5-interop v0.4.0
(contract 2.3) by digest.
Fixed
iec104/client:CounterInterrogatewith a freeze or reset qualifier
returns at the activation confirmation with no ASDUs, instead of waiting
for a termination the station does not send (IEC 60870-5-104 7.8;
IEC 60870-5-101:2003 7.4.8 mode C, figures 95 and 96). It is still never
retried. A termination or totals a station sends anyway reach the
Handler.telecontrol: the test sequence counter of C_TS_TA_1 starts at 0
(IEC 60870-5-104 8.8), as iniec104/client.
Changed
iec104/clientuses the matching rules oftelecontrol(Mirrored,
FromStation) instead of its own copy; behaviour is unchanged. It keeps
its own request handling; see docs/IEC104_PARITY.md for why it does not
usetelecontrol.Requester.
Security hardening
internal/testutil/serialline: the noise octet of the faulty test line is
bounded to a byte before conversion (gosec G115). Its use ofmath/rand
(G404, a seeded, reproducible test line, not security relevant) is
recorded as a false positive in the organisation's triage records. SAST
(gosec, opengrep) at the lowest thresholds: 0 findings, also in the nested
moduleiec104/interop/cbsigma.
Tests
- All interop suites pin the images of otfabric/iec60870-5-interop v0.4.0
(contract 2.3) by multi-arch index digest (iec101,iec102,iec103
andiec104/interop/harness.go, the Makefile, the Interop workflow); the
testdata copies of its case and known-bug tables are those of v0.4.0. On
those images (2026-11-12, linux/arm64): IEC 101 490 subtests passed and 5
skipped (known bug), IEC 102 18 passed, IEC 103 75 passed and 38 skipped
(known bugs, undeclared features), IEC 104 519 passed and 35 skipped, the
cB-Sigma IEC 62351-5 tests pass; 0 failures. iec101/interop: digitalpetri/iec60870 as third reference, and the field
sizes 2/2/2/3, 1/2/1/3, 2/1/2/2 and (balanced) 0/1/1/2 (link address,
cause, common address, object address). This module's client: 5 + 5
scenarios and 12 + 16 field-size runs pass against lib60870-C and against
cB-Sigma (unbalanced + balanced), against digitalpetri 5 scenarios and 12
field-size runs unbalanced; balanced against a digitalpetri station is
skipped as the harness's known bug
digitalpetri-balanced-server-no-link-reset(testdata/known-bugs.tsv),
checked to reproduce on every run. The reference clients replay the
harness's 64 cases (33 with field sizes) against this module's server:
61 + 64 pass for lib60870-C and for cB-Sigma, 55 + 64 for digitalpetri (6
cases with a common address other than its link address not run). 0
failures (INTEROPERABILITY.md).iec103/interop: the 7 cases of generic services and disturbance data and
5 value checks. Open103's client againstiec103/server: the disturbance
transfer case passes and the description, tags and channel ratings match
the fixture; its values hit the known Open103 bugopen103-asdu30-nfe.
vitusdong's client: the disturbance list case passes; the generic cases,
the transfer and the value checks are known vitusdong bugs. This module's
client against vitusdong's server: generic read, generic write and the
list are known server bugs, asserted on the octets; the transfer is
skipped (vitusdong declares nodisturbanceDataServer). The bugs no
harness pairing shows are intestdata/known-bugs-consumer.tsv(six
entries); none is counted as a pass
(docs/iec103/INTEROPERABILITY.md).- Unit and e2e: the counter freeze returning at the confirmation
(iec104/client), the C_TS_TA_1 counter starting at 0 (telecontrol),
a full IEC 103 class 1 queue (iec103/server), a broadcast on a closed
IEC 103 client.
Documentation
- docs/IEC104_PARITY.md: the decision that
iec104/clientshares the
matching rules oftelecontrolbut nottelecontrol.Requester, and why. - docs/iec103/INTEROPERABILITY.md: interpretation 12, the numbering of the
disturbance values (NFE counts from 0, as TAP counts tag positions), and
the contract 2.3 results. - README, LIMITATIONS, ROADMAP, FEATURE-STATUS, STANDARDS: the IEC 101 and
IEC 103 evidence of this release.
Behaviour changes
CounterInterrogate with a freeze or reset qualifier returns at the
confirmation.