Skip to content

SAIF.NetCore.LegacyAuth operations and processes

This page is the operation catalog and cross-operation hub for this library. Each operation's detailed, step-by-step logic lives in its own page under operations/.

Operation catalog

Operation Intent Trigger Inputs Outputs Rules
Issue the legacy auth cookie Encrypt a user's credentials with DPAPI and write the SAIFAUTH response cookie. A consuming application calls SetCookie(user, password) after the user authenticates*. user, password; ambient HttpContext Set-Cookie: SAIFAUTH=<base64> response header BR-01, BR-02, BR-03, BR-04, BR-10
Append a raw Set-Cookie header Write any cookie to the response without URL-encoding its value. Called by "Issue the legacy auth cookie", or directly by a consumer. cookie key, raw value, HttpContext One additional Set-Cookie header value BR-05, BR-06
Encrypt a string with DPAPI Convert a plaintext string and optional entropy/description into Base64 DPAPI ciphertext. Called by "Issue the legacy auth cookie", or any direct consumer of DPAPI. key scope, plaintext, optional entropy, optional description Base64 ciphertext string BR-07, BR-08, BR-09
Encrypt bytes with CryptProtectData Call the native Windows DPAPI primitive to encrypt a byte array. Called by "Encrypt a string with DPAPI". plaintext bytes, entropy bytes, description Ciphertext byte array BR-04, BR-08, BR-11, BR-12, BR-13
Remove the legacy auth cookie Delete the SAIFAUTH cookie from the response. A consumer calls ClearCookie(), inferred at logout*. ambient HttpContext Expiring Set-Cookie: SAIFAUTH= header BR-01, BR-14
Decrypt (internal only) Mirror the encrypt path to recover plaintext from DPAPI ciphertext; unreachable from any consumer. No caller in the library; recorded for completeness. Base64 or byte-array ciphertext, entropy Decrypted plaintext (unreachable) BR-11

Process flow diagram

The following diagram visualizes the primary operational flow: cookie issuance through DPAPI encryption, and the independent clear/logout path.

flowchart TD
    Start([Consumer calls SetCookie]) --> Ctx["Read HttpContext<br>from accessor"]
    Ctx --> Payload["Build payload:<br>user + TAB + password + TAB"]
    Payload --> Entropy["Read client remote IP<br>as DPAPI entropy"]
    Entropy --> Encrypt["DPAPI.Encrypt:<br>MachineKey scope + IP entropy"]
    Encrypt --> Header["AddCookieToHeader:<br>raw Base64, no URL-encoding"]
    Header --> EndSet(["Set-Cookie: SAIFAUTH written"])
    StartClear([Consumer calls ClearCookie]) --> CtxClear["Read HttpContext<br>from accessor"]
    CtxClear --> Delete["Response.Cookies.Delete<br>SAIFAUTH, default options"]
    Delete --> EndClear([Expiring Set-Cookie written])

Failure and edge-case behavior

  • SetCookie throws NullReferenceException when called outside an active HTTP request (no ambient HttpContext), or when RemoteIpAddress is unavailable on that context; ClearCookie throws the same exception only when called outside an active HTTP request — it never reads RemoteIpAddress (BR-10)
  • An exception raised inside the byte-array Encrypt(KeyType, byte[], byte[], string) overload's try block — including a non-Windows host or a non-default Windows installation directory surfacing as DllNotFoundException — is wrapped as a generic System.Exception("DPAPI was unable to encrypt data.") (BR-12, BR-13). Preparation (UTF-8/Base64 conversion in the string overload), argument coercion before the try block, and finally-block cleanup failures are not wrapped by this rule.
  • A tab character embedded in the user or password value corrupts the legacy reader's parsing of the payload (BR-02)
  • The internal Decrypt overloads are unreachable dead code with no caller in the library; they are documented for completeness only.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • src/SAIF.NetCore.LegacyAuth/src/SAIF.NetCore.LegacyAuth/SAIF.NetCore.LegacyAuth/LegacyAuthCookieService.cs
  • src/SAIF.NetCore.LegacyAuth/src/SAIF.NetCore.LegacyAuth/SAIF.NetCore.LegacyAuth/DPAPI.cs