---
title: SAIF.NetCore.LegacyAuth operations and processes
summary: Business and technical operations supported by this library.
status: draft
owner: Framework
last_reviewed: 2026-10-02
library: SAIF.NetCore.LegacyAuth
reference_type: package
---

# 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](operations/issue-legacy-auth-cookie.md) | 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](business-rules.md#br-01-fixed-cookie-name-saifauth), [BR-02](business-rules.md#br-02-tab-delimited-credential-payload), [BR-03](business-rules.md#br-03-client-ip-as-encryption-entropy), [BR-04](business-rules.md#br-04-machine-scope-dpapi-encryption), [BR-10](business-rules.md#br-10-active-http-request-required-for-cookie-operations) |
| [Append a raw Set-Cookie header](operations/append-raw-set-cookie-header.md) | 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](business-rules.md#br-05-no-url-encoding-on-cookie-value), [BR-06](business-rules.md#br-06-cookie-attributes-omit-secure-and-samesite) |
| [Encrypt a string with DPAPI](operations/encrypt-string-with-dpapi.md) | 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](business-rules.md#br-07-instance-encrypt-defaults-to-user-key-scope), [BR-08](business-rules.md#br-08-null-inputs-coerced-to-empty-values), [BR-09](business-rules.md#br-09-utf-8-and-base64-encoding-for-string-encryption) |
| [Encrypt bytes with CryptProtectData](operations/encrypt-bytes-with-cryptprotectdata.md) | 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](business-rules.md#br-04-machine-scope-dpapi-encryption), [BR-08](business-rules.md#br-08-null-inputs-coerced-to-empty-values), [BR-11](business-rules.md#br-11-no-dpapi-ui-prompts-permitted), [BR-12](business-rules.md#br-12-generic-exception-wrapping-on-encryption-failure), [BR-13](business-rules.md#br-13-windows-only-dpapi-dll-path) |
| [Remove the legacy auth cookie](operations/clear-legacy-auth-cookie.md) | Delete the `SAIFAUTH` cookie from the response. | A consumer calls `ClearCookie()`, inferred at logout*. | ambient `HttpContext` | Expiring `Set-Cookie: SAIFAUTH=` header | [BR-01](business-rules.md#br-01-fixed-cookie-name-saifauth), [BR-14](business-rules.md#br-14-default-cookie-delete-options-on-clear) |
| [Decrypt (internal only)](operations/decrypt-internal-only.md) | 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](business-rules.md#br-11-no-dpapi-ui-prompts-permitted) |

## Process flow diagram

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

```mermaid
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](business-rules.md#br-10-active-http-request-required-for-cookie-operations))
- 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](business-rules.md#br-12-generic-exception-wrapping-on-encryption-failure), [BR-13](business-rules.md#br-13-windows-only-dpapi-dll-path)). 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](business-rules.md#br-02-tab-delimited-credential-payload))
- The internal `Decrypt` overloads are unreachable dead code with no caller in the library; they are documented for completeness only.

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

> **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`