RecordReplay.BouncyCastle 1.2.24

RecordReplay.BouncyCastle

Optional RecordReplay instrumentation for BouncyCastle SecureRandom and a lossless method argument/return codec for Org.BouncyCastle.Math.BigInteger. The adapter has no static BouncyCastle NuGet dependency: the target application continues to own and load its BouncyCastle implementation.

Supported package

The formal compatibility and acceptance targets are BouncyCastle.Cryptography 2.7.0 and the legacy Portable.BouncyCastle 1.9.0 adapter covered by the isolated process tests. The adapter resolves target types and methods by reflection, without adding another BouncyCastle implementation to the application. Do not add a second BouncyCastle implementation just to use this adapter.

Other versions and distributions are outside the random-source support contract. Their known byte-array exits are not treated as initialization-safe. Historical BigInteger payload compatibility is kept where the reflected type is accepted by the codec, but that should not be read as a promise that those distributions are supported for SecureRandom recording and replay.

Registration

Register before serving requests:

using RecordReplay.BouncyCastle;

builder.Services.AddRecordReplayBouncyCastleInstrumentation();

The registration is idempotent. It registers the BigInteger codec and the request-scoped random initializer, patches an already loaded SecureRandom from a recognized assembly, and listens for later loads. If the package is not installed, registration succeeds and no patch is installed. Method policies remain separately configured for application-owned methods that accept or return BigInteger.

The acceptance-critical exits are resolved by exact signature:

Org.BouncyCastle.Security.SecureRandom.NextBytes(byte[])
Org.BouncyCastle.Security.SecureRandom.NextBytes(byte[], int, int)
Org.BouncyCastle.Security.SecureRandom.NextBytes(Span<byte>)

All three signatures are covered by the official BouncyCastle.Cryptography 2.7.0 acceptance tests, including the ref-struct Span<byte> overload. A different runtime or an out-of-contract BouncyCastle version that cannot patch the ref-struct signature emits a capability-degraded warning and is not treated as formally supported.

If the application owns a SecureRandom subclass that overrides these exits, pass that concrete type explicitly. This avoids scanning arbitrary application assemblies and preserves the type identity of the application's BouncyCastle package:

builder.Services.AddRecordReplayBouncyCastleInstrumentation(
    typeof(MyApplicationSecureRandom));

The supplied type must be a closed type derived from Org.BouncyCastle.Security.SecureRandom in BouncyCastle.Cryptography 2.7.0. The overload patches only the exact methods declared by that type. Register each application-owned override explicitly; do not pass a type from another BouncyCastle distribution.

Record and replay behavior

Only an active RecordReplay record or replay execution scope changes random behavior. During recording the real SecureRandom method runs first, then the written bytes are copied into the existing dependency snapshot channel. The byte[] and Span<byte> overloads record the complete supplied buffer; the range overload records only the requested offset/length interval. Random bytes are excluded from the fingerprint, log messages, exception text, and management DTOs.

During replay the next bouncycastle-random-v2 snapshot is checked for the assembly, method overload, buffer capacity, offset, length, explicit type, and sequence. On a match the recorded bytes are copied into the caller's buffer and the real random method is skipped. A missing, incompatible, or exhausted snapshot fails closed with BOUNCYCASTLE_RANDOM_REPLAY_MISS; replay must not silently fall back to live entropy. Calls outside RecordReplay continue to use the real random source. Re-entrant overload calls are collapsed to one dependency by a request-local guard.

Automatic seeding is isolated at a verified BouncyCastle method boundary. The Portable.BouncyCastle 1.9.0 adapter uses SecureRandom.CreatePrng(string,bool); the BouncyCastle.Cryptography 2.7.0 adapter uses SecureRandom.AutoSeed(...). Those calls use real system entropy and do not consume the business random sequence. If the expected boundary signature is absent, the adapter reports a degraded capability and does not install the random exit patches. The v1 random snapshot format has no purpose metadata and is incompatible; traces using it must be recorded again.

AddRecordReplayBouncyCastleMethodReturnCodecs() remains available for hosts that need only the legacy BigInteger return codec. The bouncycastle-biginteger-v1 payload format remains unchanged. The codec uses the runtime return Type (rather than a static BouncyCastle type), reads SignValue/Abs()/ToByteArrayUnsigned() reflectively, and constructs the restored value with that same Type.

Protect the trace store as sensitive material and use process-generated test keys. This adapter is intended to make deterministic QA replay possible; it is not a replacement for production key management or a reason to persist private keys.