Wop.Sdk 0.1.7

wop-dotnet-sdk

Official merchant-side .NET SDK for the WOP gateway: encapsulates the protocol core (suite parsing, canonicalRequest, structured signing, content-digest, L2 digital envelope, signature verification & decryption) plus an HttpClient adapter, so merchants integrate without touching wire-level byte formats.

• Targets: net8.0 + netstandard2.0 (multi-target)
• Crypto dependency (the single blessed path, E5): BouncyCastle.Cryptography (successor of Portable.BouncyCastle)
• Suites (F1): WOP-RSA3072-SHA256 / WOP-RSA4096-SHA256 / WOP-SM2-SM3 (both international and GM suites fully supported)
• Protocol source of truth: gtsp-wop-gateway/docs/crypto-strategy-spec.md (v0.3-reviewed) and wop-sdk-spec.md (v1.0-ratified)

Quick Start

dotnet add package Wop.Sdk   # 0.1.0 (or reference src/Wop.Sdk from source)

using Wop.Sdk;

var client = WopClient.Builder()
    .AppKey("your-app-key")
    .Suite("WOP-RSA3072-SHA256")            // or WOP-SM2-SM3
    .MerchantPrivateKey(merchantPrivateKey)  // PEM or single-line Base64 (D12)
    .PlatformPublicKey(platformPublicKey)
    .Build();

// 1) Build the request draft (pure computation, zero network IO; idempotent
//    apart from CSPRNG values)
RequestDraft draft = client.BuildRequest(
    "POST", "/api/v1/pay",
    Encoding.UTF8.GetBytes("{\"orderNo\":\"20260829001\",\"amount\":100}"),
    SecurityLevel.L0);                       // L0 plaintext / L2 full envelope

// 2) Consume draft.Headers / draft.WireBody with your own HTTP stack,
//    or use the SDK adapter (DelegatingHandler pluggable):
var transport = new HttpClientTransport(
    new SocketsHttpHandler { PooledConnectionLifetime = TimeSpan.FromMinutes(5) },
    "https://wop-gateway.example.com");
var (result, response) = client.Execute(transport, "POST", "/api/v1/pay", body, SecurityLevel.L0);
if (result.Ok)
{
    var plaintext = Encoding.UTF8.GetString(result.Plaintext!);
}

Key Preparation (D12 contract)

Keys are passed as strings (PEM or single-line Base64) and parsed inside the SDK; parse failures return explicit configuration errors (for integration self-checks).

Notes:

• RSA key size is strictly checked against the suite declaration (3072/4096 mismatch is rejected).
• SM2 public points not on the sm2p256v1 curve are rejected immediately (I5 curve guard).
• .NET's BitConverter.ToString produces uppercase hyphenated output by default — this SDK emits lowercase hex everywhere (D10).

L0 + L2 Examples

// L0 plaintext: signature + digest integrity (digest is the only integrity line for L0, D2)
var l0 = client.BuildRequest("GET", "/api/v1/orders?status=PAID", null, SecurityLevel.L0);
// GET / empty body: x-wop-content-digest header is absent (no "digest of empty string" state)

// L2 full digital envelope: CSPRNG CEK + IV (I4: single IV generation point, never reused
// under the same key) → AES-256-GCM / SM4-GCM full-body encryption (cipher = ciphertext‖tag)
// → DEK payload alg$key$iv wrapped by RSA-OAEP (explicit dual SHA-256 + empty label) / SM2(C1C3C2)
// → wire body {"encrypted":"<base64url>"}, directive header x-wop-encrypt: L2;dek=<base64url>
var l2 = client.BuildRequest("POST", "/api/v1/transfer", secretBody, SecurityLevel.L2);

// Verify gateway responses (F6 fixed order: verify signature → digest recheck → DEK unwrap
// → alg family compare → bulk decrypt)
VerifyResult r = client.VerifyResponse("POST", "/api/v1/transfer", responseHeaders, responseBody);

// Verify platform callbacks (canonical URI = callback URL path, method is always POST)
VerifyResult c = client.VerifyCallback(callbackUrl, headersFromBody, rawBody);

Error handling (I7 fuzzing discipline):

• Explicit (programmable self-checks): config CONFIG, suite parsing SUITE_PARSE/SUITE_UNSUPPORTED, protocol format PROTOCOL, digest mismatch DIGEST_MISMATCH, cross-family dek alg ALG_MISMATCH
• Fuzzy (oracle-proof, fixed messages with no cause details): verification VERIFY_FAILED ("签名验证失败" / signature verification failed), decryption DECRYPT_FAILED ("解密失败" / decryption failed) — GCM tag failure / wrong key / DEK unwrap failure share one message

Vector Self-Test (conformance)

Tests consume the same golden-vector copy as gateway CI (tests/Wop.Sdk.Tests/fixtures/crypto-vectors.json, do not modify):

export PATH="$HOME/.dotnet:$PATH"
dotnet test /p:CollectCoverage=true /p:Threshold=98 '/p:ThresholdType="line,branch"'

Coverage:

• Positive vectors byte-exact: digest, AES-256-GCM / SM4-GCM (fixed key/iv), RSA3072/4096 signatures, SM2 sign & encrypt (fixed-k outputs match vectors byte-for-byte), OAEP unwrap, SM2 decrypt
• Negative vectors all rejected: tampering, 63/65-byte signatures, base64url with =, cross-family digest/dek, C1C2C3-ordered ciphertext, MGF1-SHA1 trap (OAEP dual SHA-256 pin), DER signatures, off-curve public points
• Coverage gate: line + branch ≥ 98%