Skip to content

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.

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<br>LocalMachine Root]
    B -->|LoadSaifAdminCert by DN| F[Windows Cert Store<br>LocalMachine My]
    B -->|EncryptWithCertPublicKey /<br>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.

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.
  • Certificate DN composition is externally configurable via three configuration keys (usBankEPaySSOCertDN, usBankEPayAuthenticationCertDN, usBankEPayAuthenticationAdminCertDN) retrieved through IEnvironmentService.GetConfigSetting, not hard-coded — see BR-003 and Configuration 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.

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