---
title: USBank
summary: API reference for USBank.
status: draft
owner: <owner>
last_reviewed: 2026-07-24
library: SAIF.Services.WebServices.Epay
reference_type: package
---

# USBank

`USBank` is a static VB module implementing the US Bank ePay admin single-sign-on (SSO) cryptographic handshake. It orchestrates hybrid AES/RSA encryption and RSA digital signing of a session-transfer payload using X.509 certificates resolved from the local machine's Windows certificate store. Certificate distinguished names are composed at runtime from configuration-supplied parameters, enabling per-environment certificate selection without code changes. See [BR-003](../../business-rules.md#br-003-certificate-dn-composition-is-externally-configurable).

## Purpose
- Orchestrate the US Bank ePay SSO cryptographic handshake (`GetSSOData`): AES-encrypt the payload, RSA-wrap the symmetric key, and RSA-sign the ciphertext.
- Resolve X.509 certificate distinguished names from configuration-driven key/value pairs.
- Load X.509 certificates from the local machine Windows certificate store by distinguished name.
- Provide Base64 conversion for byte arrays (`ToBase64` extension).

## Context
- Namespace: `SAIF.Services.WebServices.Epay`
- Assembly/package: `SAIF.Services.WebServices.Epay` (`SAIF.BOF.Services.WebServices.Epay.nupkg`)
- Type kind: VB `Module` — equivalent to a static, non-inheritable class with no instance state.
- Source: `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb`

## Public members

| Member | Signature | Purpose |
| --- | --- | --- |
| `GetSSOData` | `Public Function GetSSOData(sessionTransferData As String) As AdminSingleSignOnData` | Orchestrates the full SSO encryption/signing handshake: AES-encrypts the payload, RSA-wraps the AES key with the US Bank certificate, RSA-signs the ciphertext with the SAIF admin certificate, and returns an `AdminSingleSignOnData` DTO. Throws `ApplicationException("USBank Cert not found.")` or `ApplicationException("SAIF cert not found.")` if either required certificate is not found. See [BR-001](../../business-rules.md#br-001-fail-fast-on-missing-signingencryption-certificates). |
| `GetSAIFCertDistinguishedName` | `Public Function GetSAIFCertDistinguishedName() As String` | Returns the distinguished name (DN) for the SAIF (non-admin) authentication certificate, built from the `usBankEPayAuthenticationCertDN` configuration setting via `GetCertificateParameters`. See [BR-003](../../business-rules.md#br-003-certificate-dn-composition-is-externally-configurable). |
| `LoadSAIFCert` | `Friend Function LoadSAIFCert(Optional validOnly As Boolean = False) As X509Certificate2` | Assembly-internal. Loads the SAIF authentication certificate from `LocalMachine\My` by the DN returned by `GetSAIFCertDistinguishedName`. Returns `Nothing` if the certificate is not found. Not called by `GetSSOData` in the current code.** |
| `ToBase64` | `Friend Function ToBase64(bytes As Byte()) As String` | Assembly-internal extension method on `Byte()`. Converts a byte array to a Base64-encoded string; returns an empty string (`""`) when `bytes` is `Nothing`. |

## Behavioral notes
- `GetSSOData` enforces [BR-001](../../business-rules.md#br-001-fail-fast-on-missing-signingencryption-certificates): it throws `ApplicationException("USBank Cert not found.")` if the US Bank SSO certificate cannot be resolved from `LocalMachine\Root`, and `ApplicationException("SAIF cert not found.")` if the SAIF admin authentication certificate cannot be resolved from `LocalMachine\My`.
- Certificate DN composition enforces [BR-003](../../business-rules.md#br-003-certificate-dn-composition-is-externally-configurable): all three certificate lookups resolve DNs through the private helper `GetCertificateParameters`, which calls `AppGlobal.EnvironmentService.GetConfigSetting` and JSON-deserializes the result using `System.Web.Script.Serialization.JavaScriptSerializer`.*
- `GetSSOData` discards the raw AES symmetric key from memory immediately after RSA-wrapping it (`symmetricKey = Nothing`), limiting in-memory exposure of cleartext key material. See [BR-002](../../business-rules.md#br-002-symmetric-key-material-is-not-retained-on-the-dto).
- `SAIF.Framework.Security.Cryptography` (`SAIFCrypto`) and `AppGlobal.EnvironmentService` are not defined in this library's source; their full internals are not documented here.**
- Private helpers (`LoadUSBankCert`, `GetSAIFAdminCertDistinguishedName`, `LoadSaifAdminCert`, `GetCertificateParameters`) are not part of the public or Friend surface; they are documented here only to support understanding of `GetSSOData` behavior.

## Constraints and usage notes
- This is a VB `Module` — it has no instance state and cannot be instantiated or inherited.
- Callers must ensure all three certificate-DN configuration keys (`usBankEPaySSOCertDN`, `usBankEPayAuthenticationCertDN`, `usBankEPayAuthenticationAdminCertDN`) are present in the environment configuration store and contain valid JSON-encoded DN dictionaries; a missing or malformed key causes `JavaScriptSerializer.Deserialize` to throw before certificate lookup occurs.
- The required certificates must be pre-deployed to the local machine's Windows certificate store (`LocalMachine\Root` for the US Bank cert, `LocalMachine\My` for SAIF certs) before `GetSSOData` is called.

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

## Sources
- `Services\SAIF.Services.WebServices.Epay\WebService\USBank.vb`