mirror of https://github.com/OPCFoundation/UA-.NETStandard.git synced 2026-10-18 22:55:08 +08:00

Files

T

History

romanett 7fe7794a19 Enable AES-GCM and ChaCha20-Poly1305 policies on net48 via BouncyCastle (stacked on #4703 ) (#4705 )

> Follow-up to #4703 (now merged to master; this PR has been retargeted
to `master`).

Part of #4510. #4703 enabled the CBC ECC policies on net48 through a
BouncyCastle raw-ECDH polyfill. The AEAD policies were still unavailable
there because .NET Framework has no `AesGcm` or `ChaCha20Poly1305`. This
PR adds those ciphers the same way, so on net48 all of these are now
offered:
`ECC_{nistP256,nistP384,brainpoolP256r1,brainpoolP384r1}_AesGcm` /
`_ChaChaPoly`, `RSA_DH_AesGcm`, `RSA_DH_ChaChaPoly`.

## Changes
- **Polyfill**
`src/Opc.Ua.Security.Certificates/Org.BouncyCastle/AeadCiphers.cs`
(internal, `#if NETFRAMEWORK`, next to `EcdhRawAgreement`): `AesGcm` and
`ChaCha20Poly1305` types with the .NET 8 BCL surface. They wrap
BouncyCastle's `GcmBlockCipher(AesEngine)` and
`Org.BouncyCastle.Crypto.Modes.ChaCha20Poly1305`.
- A tag mismatch throws `CryptographicException`, never BC's
`InvalidCipherTextException`, so
`PlatformSymmetricCryptoProvider.DecryptAuthenticated` still returns
`false` and the channel still raises a protocol error.
- GCM releases plaintext blocks before it checks the tag, so plaintext
stays in a scratch buffer and is copied out only after the tag verifies.
On failure the destination is cleared, as the BCL does. Scratch buffers
and the key copy are zeroed.
- **Opc.Ua.Core**: aliases the polyfill types on `NETFRAMEWORK` and
removes the `NET8_0_OR_GREATER` gates in `SecurityPolicies`
(`SupportsAesGcmPolicy` / `SupportsChaCha20Poly1305Policy`),
`CryptoUtils` (`SymmetricEncryptAndSign` / `SymmetricDecryptAndVerify`,
AEAD helpers) and `PlatformSymmetricCryptoProvider`. The channel, the
provider facet and the encrypted ECC user tokens (`EncryptedSecret`,
through `CryptoUtils`) now run the same code on every target. .NET 8+
keeps the BCL ciphers.
- **FIPS** (requested by the #4703 session, after a2ecf13b1): under
`CryptoCompliancePolicy.FipsOnly`, `CryptoCompliance.IsPolicyPermitted`
now also withholds every AEAD policy on .NET Framework. That adds
`RSA_DH_AesGcm`, which is FIPS-approved and not ECC. The BouncyCastle
cipher runs outside any validated module and the user-token path
bypasses the provider registry, so the auditor cannot see it. Tests and
`docs/CryptoProvider.md` are updated to match.
- **Docs**: EccProfiles (Known Limitations), migration `certificates.md`
(and the bundled skill copy), ProductionChecklist, Profiles,
WhatsNewIn2.0, CryptoProvider. They state that on net48 these primitives
run in managed BouncyCastle, which is not a validated (FIPS) module and
not hardware-accelerated or hardened against cache-timing attacks like
CNG AES.

## Tests
- New `AeadPolyfillTests` (Core.Tests):
- Known answers: NIST GCM test cases 2/4 (AES-128) and 14/16 (AES-256),
plus RFC 8439 §2.8.2 for ChaCha20-Poly1305. They run through
`PlatformSymmetricCryptoProvider` on every TFM and through the polyfill
directly.
- Tampering with the tag, the ciphertext or the AAD gives `false` from
the provider, and `CryptographicException` with a cleared plaintext from
the polyfill.
  - Argument validation.
- **BCL cross-check:** on .NET 8+, Core.Tests also compiles
`AeadCiphers.cs` (`AEAD_POLYFILL_CROSSCHECK`, test-only
`BouncyCastle.Cryptography` reference). Polyfill and BCL must produce
identical ciphertext and tag, and each must decrypt the other's output:
3 algorithms × 8 message lengths (0 to 8192) × 3 AAD lengths.
- `CryptoProviderRegistryTests`: `RSA_DH_AesGcm` is permitted under
FipsOnly only off .NET Framework and withheld on it.
- Tests that `Assert.Ignore` when AEAD is unavailable now run on net48,
e.g. `EccSecretRejectsDifferentNegotiatedPolicyAsync` and the
`RSA_DH_AesGcm` server session tests.

### Local results
| Run | Result |
|---|---|
| Core.Tests net48, full (before the FIPS commit) | 6049 passed, 0
failed, 88 skipped |
| Core.Tests crypto/AEAD/ECC/EncryptedSecret/Nonce subset, net48 /
net10.0 | 278 / 343 passed, 0 skipped |
| Server.Tests session-security/ECC subset, net48 | 128 passed, 0
skipped |
| `EccInteropTests` net48 vs **open62541 1.5.8 (OpenSSL)** peer | all 16
AEAD cases pass, 4 of them two-renewal token-renewal runs
(`ECC_nistP256_AesGcm`/`_ChaChaPoly` × Sign/SignAndEncrypt ×
Anonymous/UserName, both directions). Remaining 8 failures are the
documented open62541 CBC Sign-only HKDF differences in
`expected-differences.json` |
| `EccInteropTests` net48 vs 1.5.378 LegacyPeer | unchanged 26 passed /
28 skipped |

Note on the acceptance criterion: the 1.5.378 LegacyPeer does not
implement the AEAD policies, so its
`_AesGcm`/`_ChaChaPoly`/`*AeadTokenRenewalAsync` cases skip on every TFM
("The peer (UA-.NETStandard) does not declare …"). Before this PR they
skipped on the 2.0 side; now they get past it and stop at the peer
check. The open62541 peer is the real cross-stack check of the net48
AEAD path against a non-BouncyCastle implementation.

## PubSub DTLS on net48
The DTLS 1.3 transport (`src/Opc.Ua.PubSub.Udp/Dtls`) was compiled out
on .NET Framework, so net48 registered no DTLS profiles. It now reuses
the same polyfills (`Opc.Ua.Security.Certificates` gains
`InternalsVisibleTo Opc.Ua.PubSub.Udp`):
- The `NET8_0_OR_GREATER` gates in the handshake, ECDHE, record
protection and profile probe are removed.
- Two .NET 8 APIs get net48 fallbacks: the AES-ECB record-number mask
uses `CreateEncryptor`, and the handshake random uses
`RandomNumberGenerator.Create`.
- The HKDF probe now checks the managed `DtlsHkdf` that the key schedule
actually uses.
- The public `IsAeadSupported` / `IsRawSharedSecretSupported` probes are
kept and now return `true` everywhere.
- The DTLS tests now also run on net48. The net48 "registers no
profiles" test now asserts that the NIST AEAD profiles are registered.
The socket transport-peer tests and the benchmarks stay .NET 8-only
because they use .NET 8 socket APIs.
- `docs/PubSub.md` DTLS profile table: the net48 column is updated.

Results: PubSub.Udp.Tests net48, full suite: **229 passed, 0 skipped**.
It includes complete NIST AEAD, brainpool and integrity-only handshakes
and ChaCha20 records. The DTLS subset is 76 on net48 vs 81 on net10.0;
the 5 still-gated socket-peer tests are the difference.

Note: DTLS profile selection does not consult `CryptoCompliancePolicy`
on any target. That is pre-existing and unchanged here.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-09 06:30:14 +02:00

alarms-model-change.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

certificates.md

Enable AES-GCM and ChaCha20-Poly1305 policies on net48 via BouncyCastle (stacked on #4703 ) (#4705 )

2026-10-09 06:30:14 +02:00

configuration.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

encoders.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

identity.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

node-states.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

packages.md

Remove netstandard2.1 and net472 target frameworks (#4624 )

2026-10-02 17:09:49 +02:00

pubsub.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

README.md

Make Bad_CertificateChainIncomplete unsuppressible; add UpdateCertificate renewal regression tests (#4683 )

2026-10-06 18:14:17 +02:00

sessions-subscriptions.md

Server subscriptions: fix spec defects in Subscription/MonitoredItem handling found by audit (#4629 )

2026-10-03 05:43:16 +02:00

source-generation.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

telemetry.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

timeprovider.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

transport-listener-async.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

types.md

Add a documentation learning path and fix issues found while verifying it (#4555 )

2026-09-28 19:19:39 +00:00

README.md

Migrating from 1.5.378 to 2.0.x

Version 2.0 introduces a major architectural change from pre-generated code files to runtime source generation and more efficient memory use, with several major breaking changes requiring changes to your applications.

This folder includes all of the 1.5.378 → 2.0 migration content as a set of focused sub-documents so you can read only the parts that affect your application. Start with the Migration sub-doc index below to find the sub-doc that matches the symptom you are seeing.

Automate the migration. Add the OPCFoundation.NetStandard.Opc.Ua.MigrationAnalyzer analyzer package to your projects to receive analyzer warnings and one-click fixes for many of the patterns in these sub-docs. The package implements 26 analyzer rules through UA0030 (excluding UA0013, UA0016, UA0017, and the shim-only UA0029) across the index below and the cross-cutting guidance in the Migration Guide. UA0029 is currently a runtime-shim/manual marker surfaced through CS0618, not an analyzer. The type-safety subset (UA0002–UA0008, UA0014, UA0019) maps to types.md.

Pro TIP. Point your favorite coding agent at the opcua-v20-migration skill, which knows when to load each sub-doc and runs the codefixer for you.

Migration sub-doc index
All sub-documents
See also

Migration sub-doc index

Find the row that matches the error / API surface you are dealing with and read only the listed sub-doc. The agent skill uses the same table; loading a single sub-doc keeps the context window small.

When you hit…	Read
`CS0029` / `CS1503` / `CS0266` on `NodeId`, `Variant`, `DataValue`, `ExtensionObject`, `QualifiedName`, `LocalizedText`, `ArrayOf<T>` / `MatrixOf<T>`, `ByteString`, `StatusCode`, `XmlElement`, `EnumValue`; `[Obsolete]` warnings on built-in type APIs (analyzers `UA0002`–`UA0008`, `UA0014`, `UA0019`)	`types.md`
Loggers (`Utils.LogX`, `Utils.Trace`), removed static logger helpers (`Utils.SetLogger` / `Utils.SetLogLevel`), telemetry context, constructor `ITelemetryContext` parameter changes, OLD-vs-NEW snippets, fluent DI registration (`AddOpcUa().AddLogging().AddMetrics()`), breaking-changes inventory, migration utilities	`telemetry.md`
`OPCFoundation.NetStandard.Opc.Ua.*` package upgrade, TFM changes, Newtonsoft removal	`packages.md`
Source-generated `*Collection` shims, NodeManager generator, default of boolean properties, project structure	`source-generation.md`
`IEncodeableFactoryBuilder`, `IType`, JSON / XML / binary encoders, `EncodeableFactory.GlobalFactory`, `IJsonEncodeable`, `ComplexTypes` namespace move	`encoders.md`
`CustomNodeManager`, `NodeState` clone / read / write helpers, `OnAfterCreate(CancellationToken)`, `FindChild` / `CreateChild` NodeId assignment, `INodeManager3`, `INodeCache.InvalidateNode`, generics on `BaseVariableState` / `BaseVariableTypeState`, predefined-node processing, `lock (node)` on a `NodeState`, `NodeBrowser.DataLock` (analyzer `UA0027`)	`node-states.md`
`IUserIdentityTokenHandler`, `IClientIdentityProvider`, `IUserTokenAuthenticator`, `IAccessTokenProvider`, `ITokenIssuer`, `IIdentityClaims`, caller-supplied secrets, secret store	`identity.md`
`CertificateValidator`, ref-counted `Certificate` wrapper, `CertificateManager`, `ICertificateProvider`, obsoleted `X509Certificate2` direct-exposure APIs, PushManagement transactions (`ApplyChanges`-gated TrustList updates), caller-owned `CertificateStoreIdentifier.OpenStore` stores, non-suppressible `Bad_CertificateChainIncomplete`	`certificates.md`
`ApplicationConfiguration` changes, Data-Contract serializer removal, `MinMetadataSamplingInterval` → `MinSupportedSamplingInterval`, `ParseExtension` / `UpdateExtension` signature, session / browser state persistence	`configuration.md`
`Session` → `ManagedSession`, V2 subscription engine, GDS-client `Task` → `ValueTask` modernisation, removed obsolete GDS APIs, durable subscriptions, PubSub, reverse-connect, server `ISubscription` publish-pipeline members / `SessionPublishQueue` internalized (analyzer `UA0030`)	`sessions-subscriptions.md`
`UaPubSubApplication.Create*`, `IUaPubSubConnection`, `UaPubSubConfigurator`, `IUaPublisher`, AMQP transport, `JsonEncodingMode.Reversible/NonReversible`, PubSub JSON encoder changes, `DataSetFieldContentMask` RawData / timestamp behaviour	`pubsub.md`
`AlarmConditionState` state-transition behaviour, auto-emitted `GeneralModelChangeEvent`, `ModelChangeAggregator`, `INodeCache.InvalidateNode` triggered by model change	`alarms-model-change.md`
`DateTime.UtcNow`, `Timer`, deterministic time in tests; `System.TimeProvider` adoption	`timeprovider.md`
`ITransportListener.Open` / `Close` removed, `ReverseConnectManager.StartService` / `Dispose` obsolete, reverse-connect DI/provider migration, custom `ITransportListenerFactory` / `ITransportListenerCertificateRotation` implementers need the new async method names	`transport-listener-async.md`

All sub-documents

telemetry.md — Telemetry and Logging
packages.md — Package, Target Framework, and Dependency Changes
source-generation.md — Source Generation
types.md — Improved Type Safety
encoders.md — Encoders and Complex Types
node-states.md — Node States and INodeCache
identity.md — Identity, Token Handlers, and Secrets
certificates.md — Certificates and ICertificateProvider
configuration.md — Configuration and State Persistence
sessions-subscriptions.md — Sessions, GDS Client, and Subscriptions
pubsub.md — PubSub (Part 14): breaking API, transport, JSON, and field-encoding changes
alarms-model-change.md — Alarms and Address-Space Model Changes
timeprovider.md — Time and Timer Abstraction (TimeProvider)
transport-listener-async.md — Async ITransportListener API (issue #3923)

README.md Unescape Escape

Migrating from 1.5.378 to 2.0.x

Contents

Migration sub-doc index

All sub-documents

See also

README.md