---
title: SAIF.Services.WebServices.Epay business rules
summary: Enumerated business rules with per-rule trigger, enforcement, and outcomes.
status: draft
owner: <owner>
last_reviewed: 2026-07-24
library: SAIF.Services.WebServices.Epay
reference_type: package
---

# SAIF.Services.WebServices.Epay business rules

This page captures business rules enforced by this library.

## BR-001: Fail-fast on missing signing/encryption certificates

| Field | Value |
| --- | --- |
| **Statement** | `GetSSOData` must have both the US Bank SSO certificate and the SAIF admin authentication certificate available in the local machine certificate store; if either cannot be resolved, the SSO handshake aborts immediately with an `ApplicationException`. |
| **Trigger** | Certificate lookup by distinguished name returns `Nothing` for either the US Bank certificate (`LocalMachine\Root`) or the SAIF admin authentication certificate (`LocalMachine\My`) during a `GetSSOData` invocation. |
| **Enforcement** | `USBank.GetSSOData`: throws `ApplicationException("USBank Cert not found.")` after `LoadUSBankCert` returns `Nothing`; throws `ApplicationException("SAIF cert not found.")` after `LoadSaifAdminCert` returns `Nothing`. |
| **Outcome** | The SSO handshake generation aborts with a descriptive exception rather than silently producing an invalid or partial payload. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb` |

---

## BR-002: Symmetric key material is not retained on the DTO

| Field | Value |
| --- | --- |
| **Statement** | `AdminSingleSignOnData` property setters (`Private Set`) discard any assigned byte array rather than storing it — backing fields are set directly during construction and cannot be overwritten via the property setter; `GetSSOData` also explicitly discards the raw AES symmetric key from memory after RSA-wrapping it.* |
| **Trigger** | Any internal attempt to assign a value to an `AdminSingleSignOnData` property via its `Private Set`, or completion of the RSA key-wrapping step in `GetSSOData`. |
| **Enforcement** | Each `Private Set` implementation in `AdminSingleSignOnData` sets its backing field to `Nothing` rather than to the supplied value; `GetSSOData` sets `symmetricKey = Nothing` immediately after `EncryptWithCertPublicKey` completes.* |
| **Outcome** | The DTO is effectively immutable from a consumer's perspective; cleartext AES key material is not retained in writable form after the handshake payload is constructed.* |
| **Confidence** | Inferred |
| **Source** | `Services\SAIF.Services.WebServices.Epay\WebService\AdminSingleSignOnData.vb`, `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb` |

---

## BR-003: Certificate DN composition is externally configurable

| Field | Value |
| --- | --- |
| **Statement** | The X.509 certificates used for SSO encryption and signing are identified by distinguished names (DNs) composed from configuration-supplied key/value pairs, not from hard-coded DN strings or thumbprints. This allows certificate rotation and per-environment certificate selection without a code change. |
| **Trigger** | Any invocation of `GetSSOData`, `GetSAIFCertDistinguishedName`, or `GetSAIFAdminCertDistinguishedName`. |
| **Enforcement** | `USBank.GetCertificateParameters(ParameterKey)` reads a JSON-serialized dictionary from `AppGlobal.EnvironmentService.GetConfigSetting(ParameterKey)` and passes the deserialized key/value pairs to `SAIFCrypto.Certificates.GetDistinguishedName` to build the DN string. Three configuration keys drive this: `usBankEPaySSOCertDN`, `usBankEPayAuthenticationCertDN`, and `usBankEPayAuthenticationAdminCertDN`. |
| **Outcome** | Certificate identity is environment-specific and can be updated by changing configuration rather than redeploying code. |
| **Confidence** | Verified |
| **Source** | `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb` |

---

## Related documentation
- [Index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Configuration](configuration.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
- `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb`
- `Services\SAIF.Services.WebServices.Epay\WebService\AdminSingleSignOnData.vb`