feat(fido2): WebAuthn previewSign extension

[DennisDyallo]

Summary

Adds the previewSign WebAuthn extension to the v1 SDK (ARKG-P256 key generation, offline derivation, sign-by-credential, offline signature verification) targeting YubiKey 5.8.0-beta firmware. Ported from yubikit-swift release/1.3.0, cross-verified against python-fido2, the Rust cnh-authenticator-rs-extension reference, and the upstream Yubico/5-8-hello-world quickstart.

ARKG-P256 (RFC draft bradleylundberg-cfrg-arkg-09) implemented in Yubico.Core.Cryptography.ArkgPrimitivesOpenSsl via OpenSSL P/Invoke through Yubico.NativeShims. No BouncyCastle dependency.

Stacking: depends on #472. Merge #472 first — this branch consumes its new Native_EC_POINT_is_on_curve export, the Yubico.NativeShims 1.16.1-prerelease.20260428.1 version bump, and the relocated HkdfUtilities.

Verification

Suite	Result
Yubico.YubiKey.UnitTests	3588 PASS
Yubico.Core.UnitTests	488 PASS / 21 SKIP (Windows-only on macOS)
ARKG KAT vectors (ArkgP256Tests + ArkgPrimitivesTests)	8 PASS — byte-for-byte vs Rust hid-test reference
Hardware integration: PreviewSignTests (3 tests)	✅ on YubiKey 5.8.0-beta (5C NFC)
DocFX /t:DocFXBuild warnings-as-errors	✅ clean

CI note

submit-nuget will fail until Yubico.NativeShims 1.16.1-prerelease.20260428.1 is reachable from the public NuGet feed (currently published only to Yubico's internal feed). All other CI checks green across Windows/Linux/macOS.

In-branch design docs

Plans/preview-sign-v1-port-plan.md (design), codeaudit-previewsign-port.md (vslsp + crypto audit), python-fido2-reference-findings.md (cross-impl archaeology), previewsign-followups.md (deferred cleanup with suggested PR sequence). Untracked — intentionally kept out of this PR's tree.

[github-actions]

Test Results: Windows

    2 files      2 suites   40s ⏱️
4 171 tests 4 149 ✅ 22 💤 0 ❌
4 173 runs  4 151 ✅ 22 💤 0 ❌

Results for commit be57c2c.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results: Ubuntu

    2 files      2 suites   1m 8s ⏱️
4 163 tests 4 141 ✅ 22 💤 0 ❌
4 165 runs  4 143 ✅ 22 💤 0 ❌

Results for commit 216c956.

♻️ This comment has been updated with latest results.

[github-actions]

Test Results: MacOS

    4 files      4 suites   54s ⏱️
4 145 tests 4 142 ✅ 3 💤 0 ❌
4 147 runs  4 144 ✅ 3 💤 0 ❌

Results for commit 216c956.

♻️ This comment has been updated with latest results.

[Copilot]

Pull request overview

Adds support for the WebAuthn previewSign extension to the FIDO2 surface area of Yubico.NET.SDK, including ARKG-P256 offline public-key derivation and sign-by-credential plumbing, plus associated cryptographic/native support and tests.

Changes:

• Introduces previewSign extension APIs for MakeCredential (generate key) and GetAssertion (sign by derived credential), plus parsing of signed/unsigned extension outputs.
• Adds ARKG-P256 primitives (OpenSSL-backed via NativeShims) and wires them through CryptographyProviders.
• Adds unit/integration tests for previewSign + ARKG, and a test-only cache warmup workaround for a macOS device-listener race.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Yubico.YubiKey/tests/utilities/Yubico/YubiKey/TestUtilities/IntegrationTestDeviceEnumeration.cs	Updates allow-list path documentation for macOS/Linux.
Yubico.YubiKey/tests/utilities/Yubico/YubiKey/TestUtilities/DeviceListenerCacheWarmup.cs	Adds test utility to wait for initial device enumeration to populate.
Yubico.YubiKey/tests/unit/Yubico/YubiKey/Fido2/PreviewSignExtensionTests.cs	Unit tests for previewSign CBOR encoding/decoding and regression scenarios.
Yubico.YubiKey/tests/unit/Yubico/YubiKey/Fido2/Arkg/ArkgP256Tests.cs	Known-answer tests for ARKG-P256 derivation behavior.
Yubico.YubiKey/tests/unit/Yubico/YubiKey/Cryptography/HkdfUtilitiesTests.cs	Updates HKDF tests to reference the moved HKDF utility.
Yubico.YubiKey/tests/integration/Yubico/YubiKey/Fido2/PreviewSignTests.cs	Adds end-to-end integration tests for previewSign generate/derive/sign/verify.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/PreviewSignGeneratedKey.cs	New public type representing generated key material and offline derivation entrypoint.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/PreviewSignExtension.cs	Implements CBOR encoder/decoder for previewSign extension input/output.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/PreviewSignDerivedKey.cs	New public type representing derived key material and signature verification helper.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/MakeCredentialParameters.cs	Adds API to request previewSign key generation during registration.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/MakeCredentialData.cs	Adds parsing of CTAP unsigned extension outputs and accessor for generated key.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/GetAssertionParameters.cs	Adds API to request previewSign signing-by-credential during assertions.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/Extensions.cs	Adds previewSign extension identifier constant.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/Cose/CoseAlgorithmIdentifier.cs	Adds previewSign-related COSE algorithm identifiers (Esp256, ArkgP256Esp256).
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/AuthenticatorInfo.cs	Updates imports to use the relocated HKDF utility.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/AuthenticatorData.cs	Adds accessor to extract previewSign signature from signed extension outputs.
Yubico.YubiKey/src/Yubico/YubiKey/Fido2/Arkg/ArkgP256.cs	Adds ARKG-P256 wrapper to route derivation through Core primitives.
Yubico.YubiKey/src/Yubico/YubiKey/Cryptography/CryptographyProviders.cs	Adds ArkgPrimitivesCreator delegate to allow swapping ARKG primitive implementation.
Yubico.NativeShims/ssl.ecpoint.c	Exposes EC_POINT_is_on_curve via NativeShims for on-curve validation.
Yubico.NativeShims/exports.msvc	Exports new Native_EC_POINT_is_on_curve symbol on Windows (MSVC).
Yubico.NativeShims/exports.llvm	Exports new symbol for LLVM toolchains.
Yubico.NativeShims/exports.gnu	Exports new symbol for GNU toolchains.
Yubico.Core/tests/unit/Yubico/Core/Cryptography/ArkgPrimitivesTests.cs	Adds Core-level tests for on-curve validation and ECDH behavior.
Yubico.Core/src/Yubico/PlatformInterop/Desktop/Cryptography/EcPoint.Interop.cs	Adds P/Invoke wrapper for Native_EC_POINT_is_on_curve.
Yubico.Core/src/Yubico/Core/Cryptography/IArkgPrimitives.cs	Introduces interface contract for ARKG primitives (validation, ECDH, derive).
Yubico.Core/src/Yubico/Core/Cryptography/HkdfUtilities.cs	Moves/renames HKDF utility into Core and updates implementation details.
Yubico.Core/src/Yubico/Core/Cryptography/ArkgPrimitivesOpenSsl.cs	Implements ARKG-P256 primitives and derivation using OpenSSL via NativeShims.
Yubico.Core/src/Yubico/Core/Cryptography/ArkgPrimitives.cs	Adds factory for default ARKG primitives implementation.
Yubico.Core/src/Yubico.Core.csproj	Updates NativeShims package dependency version for the new export.

Comments suppressed due to low confidence (2)

Yubico.Core/src/Yubico/Core/Cryptography/HkdfUtilities.cs:74

• HkdfExtract creates temporary byte[] copies of both the salt and the input keying material via ToArray(). Since IKM can be secret material, these temporary arrays should be zeroed after ComputeHash to avoid extending the lifetime of sensitive data in memory.
  Yubico.Core/src/Yubico/Core/Cryptography/HkdfUtilities.cs:87
• HkdfExpand currently calls pseudoRandomKey.ToArray() to build the HMAC instance, which creates an extra copy of the PRK. Since DeriveKey already zeroes the original PRK, this additional copy will remain in memory unless explicitly cleared. Consider avoiding the extra copy (e.g., accept byte[] and pass it through) and/or ensuring any extra key buffer is zeroed when no longer needed.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 24 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (2)

Yubico.YubiKey/src/Yubico/YubiKey/Fido2/MakeCredentialData.cs:217

• The previous MakeCredentialData constructor validated that the attestation statement is well-formed (packed format, contains alg/sig, optional x5c, no extra keys) and threw Ctap2DataException via ReadAttestation when it wasn't. With this refactor, validation only happens inside AttestationObject.ParsePackedAttestationStatement, whose return value is discarded (_ = ParsePackedAttestationStatement(...) in AttestationObject.cs:216). A "packed" response with a missing sig, an unknown extra key, or too many entries will now silently produce a MakeCredentialData with AttestationAlgorithm == ES256 (the fallback) and AttestationStatement == Empty, instead of throwing. This is a behavior regression for malformed-input handling.

                // Backward compatibility: expose properties from AttestationObject
                Format = AttestationObject.Format;
                AuthenticatorData = AttestationObject.AuthenticatorData;
                AttestationAlgorithm = AttestationObject.AttestationAlgorithm ?? CoseAlgorithmIdentifier.ES256;
                AttestationStatement = AttestationObject.AttestationStatement ?? ReadOnlyMemory<byte>.Empty;
                EncodedAttestationStatement = AttestationObject.EncodedAttestationStatement;
                AttestationCertificates = AttestationObject.AttestationCertificates;

Yubico.YubiKey/src/Yubico/YubiKey/Fido2/PreviewSignExtension.cs:53

• PreviewSignExtension.CtapUnsignedExtensionOutputsKey = 6 is declared here, but MakeCredentialData.cs declares its own private const int KeyUnsignedExtensionOutputs = 6; and uses that instead. Either consume the constant exported here from MakeCredentialData, or remove the unused constant.

        // Cross-ref: yubikit-swift, python-fido2, Rust, JS.
        /// <summary>CTAP key on the MakeCredential RESPONSE map carrying unsigned extension outputs.</summary>
        internal const int CtapUnsignedExtensionOutputsKey = 6;
        private const int CoseKeyTypeArkgP256 = -65537;
        private const int CoseAlgorithmArkgP256 = -65700;

[Copilot]

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (2)

Yubico.YubiKey/src/Yubico/YubiKey/Fido2/AuthenticatorData.cs:1

• Previously, bytesRead came from CoseKey.Create and represented the exact byte length consumed by the COSE parser. Now it is derived from CborReader.ReadEncodedValue().Length, which is computed against the slice starting at offset. If EncodedAuthenticatorData[offset..] contains trailing extension bytes (ED flag set), ReadEncodedValue returns only the COSE key portion — which is the intended behavior — but please verify that coseKeyReader advancing through an indefinite-length map still produces a Length equal to the canonical bytes consumed (rather than the source slice length). A small unit test covering an authData with both AT and ED bits would harden this.

// Copyright 2025 Yubico AB

Yubico.YubiKey/tests/utilities/Yubico/YubiKey/TestUtilities/Fido2/PreviewSignDerivedKey.cs:1

• The XML doc says the method 'computes the SHA-256 hash internally before verifying', but the implementation delegates to EcdsaVerify.VerifyData(..., isStandardSignature: true). Please confirm that VerifyData indeed hashes the input message (not pre-hashed) — if it expects a pre-hashed digest, callers following the docstring will get a false negative. If hashing is indeed internal to VerifyData, this is fine; otherwise the docstring or the call needs to be corrected.

// Copyright 2025 Yubico AB

[github-actions]

Package	Line Rate	Branch Rate	Complexity	Health
Yubico.Core	56%	49%	1642	➖
Yubico.YubiKey	51%	47%	7350	➖
Summary	52% (13592 / 26330)	47% (3345 / 7128)	8992	➖

Minimum allowed line rate is 40%