--- title: SAIF.Services.WebServices.Epay architecture summary: Architectural responsibilities, boundaries, and interaction patterns. status: draft owner: last_reviewed: 2026-07-24 library: SAIF.Services.WebServices.Epay reference_type: package --- # SAIF.Services.WebServices.Epay architecture SAIF.Services.WebServices.Epay is a small cryptographic integration helper implementing the US Bank ePay single-sign-on (SSO) handshake. It is not a BOF business object library — neither `AdminSingleSignOnData` nor `USBank` inherits `clsBusinessBase`/`clsBusinessCollectionBase`, and there is no `IBusinessCriteria` implementation anywhere in the library. ## Responsibilities - Encrypt SSO session-transfer data using AES and wrap the AES key with US Bank's RSA public certificate (`USBank.GetSSOData`). - Digitally sign the AES-encrypted payload with SAIF's own RSA private certificate. - Resolve certificates from the local machine's Windows certificate store by distinguished name (DN), where the DN is composed from configuration-driven name parts rather than hard-coded. - Carry the resulting ciphertext, wrapped key, IV, and signature as a serializable, Base64-encoded data-transfer object (`AdminSingleSignOnData`) for transmission to US Bank's ePay service. ## Component boundaries - **`AdminSingleSignOnData`**: serializable DTO exposing encrypted data, encrypted symmetric key, IV, and digital signature as Base64-encoded string properties over private byte-array backing fields; properties have `Private Set` and are populated only via the constructor. - **`USBank`** (VB module): static utility implementing the SSO cryptographic handshake — `GetSSOData`, DN-resolution helpers (`GetSAIFCertDistinguishedName`, `GetSAIFAdminCertDistinguishedName`), and certificate-loading helpers (`LoadSAIFCert`, `LoadUSBankCert`, `LoadSaifAdminCert`) that read the Windows certificate store. - **`wsCreditCardPayment.vb`**: present on disk as a legacy ASP.NET ASMX `WebService`-derived class calling an undefined `USB_EPay.SessionTransfer` type, but excluded from the `.vbproj` compile list — it is not part of this library's active/compiled surface and is not documented as live behavior.* - **Certificate provisioning artifacts** (`Certificates\createepaycerts.bat`, `Certificates\private\*`, `Certificates\public\*`): operational/deployment artifacts for generating and installing certificates into the Windows certificate store consumed at runtime; not application logic. - No cached inherited framework context is available for `SAIF.Framework.Security.Cryptography` (`SAIFCrypto`) or `AppGlobal.EnvironmentService` — their internals are documented only to the extent directly observable from this library's call sites.** ## Interaction model - `USBank.GetSSOData(sessionTransferData)` orchestrates the handshake: (1) AES-encrypt the payload via `SAIFCrypto.AES.Encrypt`, producing ciphertext, a symmetric key, and an IV; (2) load the US Bank SSO certificate from `LocalMachine\Root` (DN resolved via the `usBankEPaySSOCertDN` configuration setting) and RSA-encrypt the symmetric key with its public key (`SAIFCrypto.Certificates.EncryptWithCertPublicKey`), throwing `ApplicationException("USBank Cert not found.")` if the certificate cannot be located; (3) discard the raw symmetric key from memory; (4) load the SAIF admin authentication certificate from `LocalMachine\My` (DN resolved via `usBankEPayAuthenticationAdminCertDN`) and sign the encrypted payload with its private key (`SAIFCrypto.Certificates.SignWithCertPrivateKey`), throwing `ApplicationException("SAIF cert not found.")` if not located; (5) return a new `AdminSingleSignOnData` bundling the four resulting values. - Certificate DN resolution flows through a shared private helper, `GetCertificateParameters(ParameterKey)`, which calls `AppGlobal.EnvironmentService.GetConfigSetting(ParameterKey)` and JSON-deserializes the result into DN key/value pairs consumed by `SAIFCrypto.Certificates.GetDistinguishedName`. - This library performs no database access and defines no `IBusinessCriteria`; all persistence-adjacent state is the Windows certificate store, accessed via `X509Certificate2`/`StoreName`/`StoreLocation`. The following diagram shows the SSO handshake's component interactions. ```mermaid flowchart TD A[Caller] -->|GetSSOData sessionTransferData| B[USBank module] B -->|AES.Encrypt| C[SAIFCrypto.AES] B -->|GetConfigSetting cert-DN settings| D[AppGlobal.EnvironmentService] B -->|LoadUSBankCert by DN| E[Windows Cert Store
LocalMachine Root] B -->|LoadSaifAdminCert by DN| F[Windows Cert Store
LocalMachine My] B -->|EncryptWithCertPublicKey /
SignWithCertPrivateKey| G[SAIFCrypto.Certificates] B -->|bundles result| H[AdminSingleSignOnData] H -->|transmit| I[US Bank ePay service] ``` The following diagram shows the primary GetSSOData request sequence. ```mermaid sequenceDiagram participant Caller participant USBank participant EnvService as AppGlobal.EnvironmentService participant CertStore as Windows Certificate Store participant SAIFCrypto Caller->>USBank: GetSSOData(sessionTransferData) USBank->>SAIFCrypto: AES.Encrypt(sessionTransferData) SAIFCrypto-->>USBank: encryptedData, symmetricKey, IV USBank->>EnvService: GetConfigSetting(usBankEPaySSOCertDN) USBank->>CertStore: LoadUSBankCert(DN) CertStore-->>USBank: X509Certificate2 (or Nothing) USBank->>SAIFCrypto: EncryptWithCertPublicKey(symmetricKey) SAIFCrypto-->>USBank: encryptedKey USBank->>EnvService: GetConfigSetting(usBankEPayAuthenticationAdminCertDN) USBank->>CertStore: LoadSaifAdminCert(DN) CertStore-->>USBank: X509Certificate2 (or Nothing) USBank->>SAIFCrypto: SignWithCertPrivateKey(encryptedData) SAIFCrypto-->>USBank: signature USBank-->>Caller: AdminSingleSignOnData(encryptedData, encryptedKey, IV, signature) ``` ## Design constraints - `GetSSOData` fails fast: it throws `ApplicationException` with a descriptive message if either the US Bank or SAIF admin certificate cannot be resolved from the local machine's certificate store — the handshake cannot proceed without both certificates present. See [BR-001](business-rules.md#br-001-fail-fast-on-missing-signingencryption-certificates). - Certificate DN composition is externally configurable via three configuration keys (`usBankEPaySSOCertDN`, `usBankEPayAuthenticationCertDN`, `usBankEPayAuthenticationAdminCertDN`) retrieved through `IEnvironmentService.GetConfigSetting`, not hard-coded — see [BR-003](business-rules.md#br-003-certificate-dn-composition-is-externally-configurable) and [Configuration](configuration.md) for the settings catalog. - Correct deployment of the named certificates to each environment's certificate store is an implicit, undocumented-in-config runtime dependency, since certificates are resolved by DN lookup against the store rather than a secure config vault. - `wsCreditCardPayment.vb` is excluded from the compiled assembly and its referenced `USB_EPay.SessionTransfer` type is undefined in this library or its declared package dependencies — it would not build even if re-added to the compile list.* - No cached inherited framework context is available for `SAIF.Framework.Security.Cryptography`/`AppGlobal.EnvironmentService` base types; their base-class internals beyond directly observed call sites are not documented here.** > **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with `**` could not be confirmed; treat as unknown until verified. ## Related documentation - [Index](index.md) - [Overview](overview.md) - [Dependencies](dependencies.md) - [Operations and processes](operations-processes.md) - [Business rules](business-rules.md) - [Configuration](configuration.md) - [API reference](api/index.md) ## Sources - `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb` - `Services\SAIF.Services.WebServices.Epay\WebService\AdminSingleSignOnData.vb` - `Services\SAIF.Services.WebServices.Epay\WebService\wsCreditCardPayment.vb` - `Services\SAIF.Services.WebServices.Epay\Certificates\createepaycerts.bat`